choice.HotzMillerCCP

Guide & worked example · Source

choice.HotzMillerCCP(
    n_states,
    n_choices,
    discount_factor,
    transition_type='nonparametric',
    optimizer=torch.optim.LBFGS,
    maxiter=1000,
    tol=1e-06,
    device=None,
)

Hotz & Miller (1993) CCP inversion estimator.

Two-stage procedure: 1. Estimate conditional choice probabilities P̂(a|x) nonparametrically 2. Invert CCPs to recover value function differences 3. Estimate structural parameters via matching/MLE

Attributes

Name	Description
ccp_hat
device
discount_factor
entropy_term
history
inv_matrix
maxiter
n_choices
n_states
optimizer_class
params
tol
transition_matrix
transition_params
transition_type
utility_fn
utility_params

Methods

Name	Description
counterfactual	Re-solve and simulate altered utilities without mutating fitted state.
estimate_ccps	Estimate CCPs from data.
fit
invert_ccps	Invert CCPs to recover integrated value function V_bar.
predict_proba	Structural/equilibrium probabilities using fitted utility coefficients.
set_flow_utility	Specify per-period utility ū(x, a; θ).
set_transition_probabilities	Specify state transition mechanism P(x_{t+1} | x_t, a_t).
simulate	Simulate paths under fitted utility and transition probabilities.
solve_value_functions	Solve value function fixed point via successive approximations.
summary	Print a formatted summary of model estimation results.
to	Move model and transition matrix to specified device.

counterfactual

choice.HotzMillerCCP.counterfactual(
    data,
    policy_change,
    rng=None,
    *,
    n_periods=None,
)

Re-solve and simulate altered utilities without mutating fitted state.

Starts with each individual’s earliest observation. Default horizon is the largest number of observed periods per individual, not max(time ID). Pass n_periods explicitly for unbalanced-panel policy simulations.

estimate_ccps

choice.HotzMillerCCP.estimate_ccps(data)

Estimate CCPs from data.

fit

choice.HotzMillerCCP.fit(data, init_params=None, verbose=False)

invert_ccps

choice.HotzMillerCCP.invert_ccps(flow_utility)

Invert CCPs to recover integrated value function V_bar.

Args: flow_utility: (n_states, n_choices) flow utilities

Returns: V_bar_integrated: (n_states,)

predict_proba

choice.HotzMillerCCP.predict_proba(states)

Structural/equilibrium probabilities using fitted utility coefficients.

For Hotz-Miller this re-solves the Bellman equation; it does not return the empirical first-stage CCPs or freeze them under policy changes.

set_flow_utility

choice.HotzMillerCCP.set_flow_utility(utility_fn, utility_params=None)

Specify per-period utility ū(x, a; θ).

Args: utility_fn: Function computing u(x, a; θ) utility_params: Initial values for θ

set_transition_probabilities

choice.HotzMillerCCP.set_transition_probabilities(
    transition_matrix,
    transition_params=None,
)

Specify state transition mechanism P(x_{t+1} | x_t, a_t).

Args: transition_matrix: (n_states, n_choices, n_states) tensor P[x, a, x’] = Pr(x_{t+1}=x’ | x_t=x, a_t=a) transition_params: Parameters φ if transitions are parametric

Raises: ValueError: If transition matrix shape is incorrect

simulate

choice.HotzMillerCCP.simulate(initial_states, n_periods, rng=None)

Simulate paths under fitted utility and transition probabilities.

Parameters

Name	Type	Description	Default
initial_states	tensor of shape (n_individuals,)	Integer state indices at the start of the simulation.	required
n_periods	int	Number of decisions per individual.	required
rng	torch.Generator	Random generator matching the model’s device; not a NumPy RNG.	None

Returns

Name	Type	Description
	tuple of torch.Tensor	State paths with shape (n_individuals, n_periods + 1) and action paths with shape (n_individuals, n_periods).

solve_value_functions

choice.HotzMillerCCP.solve_value_functions(
    flow_utility,
    tol=1e-08,
    max_iter=10000,
)

Solve value function fixed point via successive approximations.

Iterates: v̄^{k+1} = T(v̄^k) until convergence, where T is the Bellman operator.

Args: flow_utility: (n_states, n_choices) per-period utilities ū(x,a) tol: Convergence tolerance for sup-norm max_iter: Maximum iterations

Returns: v_bar: (n_states, n_choices) converged value functions

Raises: RuntimeError: If iteration does not converge

summary

choice.HotzMillerCCP.summary(alpha=0.05)

Print a formatted summary of model estimation results.

Displays a comprehensive table including parameter estimates, standard errors, t-statistics, p-values, and confidence intervals (if standard errors are available).

Args: alpha: Significance level for confidence intervals (default: 0.05 for 95% confidence intervals).

Examples: >>> model.fit(X, y) >>> model.summary(alpha=0.01) # 99% confidence intervals

to

choice.HotzMillerCCP.to(device)

Move model and transition matrix to specified device.