econirl.SEES

class econirl.SEES(n_states=90, n_actions=2, discount=0.9999, utility='linear_cost', se_method='asymptotic', basis_type='fourier', basis_dim=8, solution='value', penalty_weight=10.0, num_theta_starts=1, max_iter=500, verbose=False)[source]

Bases: object

Sklearn-style SEES estimator for dynamic discrete choice models.

SEES (Sieve Estimation of Economic Structural models) approximates a Bellman solution object with sieve basis functions and jointly optimizes structural parameters and basis coefficients via penalized MLE. The default solution="value" is the historical value-function SEES path.

Parameters:

  • n_states (int, default=90) – Number of discrete states (e.g., mileage bins).

  • n_actions (int, default=2) – Number of discrete actions (e.g., keep/replace).

  • discount (float, default=0.9999) – Time discount factor (beta).

  • utility (str or RewardSpec, default="linear_cost") – Utility specification. Pass "linear_cost" for the classic Rust bus model (u = -theta_c * s * (1-a) - RC * a), or a RewardSpec for custom features.

  • se_method (str, default="asymptotic") – Method for computing standard errors.

  • basis_type (str, default="fourier") – Sieve basis type. Options: “fourier”, “polynomial”.

  • basis_dim (int, default=8) – Number of basis functions for the value function approximation.

  • solution ({"value", "q", "ev", "policy", "collocation"}, default="value") – Bellman solution object approximated by the sieve.

  • penalty_weight (float, default=10.0) – Weight on the Bellman equilibrium penalty (Luo and Sang 2024).

  • max_iter (int, default=500) – Maximum L-BFGS-B iterations.

  • verbose (bool, default=False) – Whether to print progress messages during estimation.

  • num_theta_starts (int)

Variables:

  • params (dict) – Estimated parameters after fitting.

  • se (dict) – Standard errors for each parameter.

  • coef (numpy.ndarray) – Coefficients as a numpy array (sklearn convention).

  • log_likelihood (float) – Maximized log-likelihood value.

  • pvalues (dict) – P-values for each parameter (from Wald t-test).

  • policy (numpy.ndarray) – Estimated choice probabilities P(a|s) of shape (n_states, n_actions).

  • value (numpy.ndarray) – Estimated value function V(s) of shape (n_states,).

  • alpha (numpy.ndarray or None) – Estimated basis coefficients after fitting. Value and collocation modes return shape (basis_dim,); action-specific modes return (n_actions, basis_dim).

  • converged (bool) – Whether the optimization converged.

  • reward_spec (RewardSpec) – The reward specification used for estimation.

References

Luo, Y. and Sang, Y. (2024). “Efficient Estimation of Structural Models

via Sieves.” Working Paper.

__init__(n_states=90, n_actions=2, discount=0.9999, utility='linear_cost', se_method='asymptotic', basis_type='fourier', basis_dim=8, solution='value', penalty_weight=10.0, num_theta_starts=1, max_iter=500, verbose=False)[source]
Parameters:
fit(data, state=None, action=None, id=None, transitions=None, reward=None)[source]

Fit the SEES estimator to data.

Parameters:

  • data (pandas.DataFrame or Panel or TrajectoryPanel) – Panel data with observations. When a DataFrame is passed, state, action, and id column names are required. When a Panel/TrajectoryPanel is passed, column names are ignored.

  • state (str, optional) – Column name for the state variable (required for DataFrame input).

  • action (str, optional) – Column name for the action variable (required for DataFrame input).

  • id (str, optional) – Column name for the individual identifier (required for DataFrame input).

  • transitions (numpy.ndarray, optional) – Pre-estimated transition matrix of shape (n_states, n_states). If None, transitions are estimated from the data.

  • reward (RewardSpec, optional) – Reward/utility specification. If provided, overrides the utility parameter passed at construction time.

Returns:

self – Returns self for method chaining.

Return type:

SEES

property reward_matrix_: ndarray | None

Structural reward matrix R(s,a) of shape (n_states, n_actions).

Computes the utility matrix from the fitted parameters and the feature specification. Returns None if the model has not been fitted.

summary()[source]

Generate a formatted summary of estimation results.

Returns:

Human-readable summary of the estimation.

Return type:

str

conf_int(alpha=0.05)[source]

Compute confidence intervals for parameters.

Parameters:

alpha (float, default=0.05) – Significance level. Returns (1 - alpha) confidence intervals.

Returns:

{param_name: (lower, upper)} confidence intervals.

Return type:

dict

Raises:

RuntimeError – If the model has not been fitted yet.

predict_proba(states)[source]

Predict choice probabilities for given states.

Parameters:

states (numpy.ndarray) – Array of state indices.

Returns:

Choice probabilities of shape (len(states), n_actions).

Return type:

numpy.ndarray