econirl.SEES

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

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 (RewardSpec) – Utility specification as a RewardSpec. For the classic Rust bus model, use rust_bus_reward_spec(n_states) from econirl.datasets.

• se_method (str, default="asymptotic") – Method for computing standard errors. Options: “robust”, “asymptotic”, “bootstrap”.

• n_bootstrap (int, default=400) – Number of pairs-cluster bootstrap replications when se_method="bootstrap".

• se_seed (int, optional) – Random seed for bootstrap 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=None, se_method='asymptotic', n_bootstrap=400, se_seed=None, basis_type='fourier', basis_dim=8, solution='value', penalty_weight=10.0, num_theta_starts=1, max_iter=500, verbose=False)

Parameters:

• n_states (int)

• n_actions (int)

• discount (float)

• utility (RewardSpec | None)

• se_method (Literal['robust', 'asymptotic', 'bootstrap'])

• n_bootstrap (int)

• se_seed (int | None)

• basis_type (str)

• basis_dim (int)

• solution (Literal['value', 'q', 'ev', 'policy', 'collocation'])

• penalty_weight (float)

• num_theta_starts (int)

• max_iter (int)

• verbose (bool)

fit(data, state=None, action=None, id=None, transitions=None, reward=None)

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()

Generate a formatted summary of estimation results.

Returns:

Human-readable summary of the estimation.

Return type:

str

conf_int(alpha=0.05)

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)

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