econirl.NNES

class econirl.NNES(n_states=90, n_actions=2, discount=0.9999, utility='linear_cost', bellman='npl', se_method='asymptotic', hidden_dim=32, num_layers=2, v_lr=0.001, v_epochs=500, n_outer_iterations=3, verbose=False)

Bases: object

Sklearn-style NNES estimator for dynamic discrete choice models.

NNES (Neural Network Estimation of Structural models) estimates utility parameters using a two-phase approach: Phase 1 trains a neural V(s) network, Phase 2 uses the learned V-network in a structural MLE for theta (Nguyen 2025).

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.

• bellman (str, default="npl") – Which Bellman equation to use in Phase 1. "npl" uses the NPL Bellman with Hotz-Miller emax correction (has Neyman orthogonality, standard errors are semiparametrically efficient). "nfxp" uses the NFXP soft Bellman operator (no orthogonality, V-errors contaminate the score).

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

• hidden_dim (int, default=32) – Number of hidden units per layer in the V-network.

• num_layers (int, default=2) – Number of hidden layers in the V-network.

• v_lr (float, default=1e-3) – Learning rate for V-network training (Phase 1).

• v_epochs (int, default=500) – Number of training epochs for V-network per outer iteration.

• n_outer_iterations (int, default=3) – Number of Phase 1 + Phase 2 alternations.

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

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,).

• v_network (numpy.ndarray or None) – V-network values for all states after training, shape (n_states,).

• converged (bool) – Whether the optimization converged.

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

Examples

>>> from econirl.estimators import NNES
>>> model = NNES(n_states=90, bellman="npl")  # default: NPL Bellman
>>> model.fit(df, state="mileage", action="replaced", id="bus_id")
>>> print(model.params_)

__init__(n_states=90, n_actions=2, discount=0.9999, utility='linear_cost', bellman='npl', se_method='asymptotic', hidden_dim=32, num_layers=2, v_lr=0.001, v_epochs=500, n_outer_iterations=3, verbose=False)

Parameters:

• n_states (int)

• n_actions (int)

• discount (float)

• utility (str | RewardSpec)

• bellman (Literal['npl', 'nfxp'])

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

• hidden_dim (int)

• num_layers (int)

• v_lr (float)

• v_epochs (int)

• n_outer_iterations (int)

• verbose (bool)

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

Fit the NNES 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:

NNES

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). Each row sums to 1.

Return type:

numpy.ndarray