choice.base.ChoiceModel

Guide & worked example · Source

choice.base.ChoiceModel(optimizer=None, maxiter=5000, tol=0.0001, device=None)

Base class for structural discrete choice models.

This abstract class provides the foundation for implementing utility-based choice models such as logit, probit, and multinomial logit. All subclasses must implement methods for predicting choice probabilities, simulating choices, and performing counterfactual analysis.

Inherits from MaximumLikelihoodEstimator, which provides: - fit() method for parameter estimation via optimization - Standard error computation via Fisher information - Model summary statistics

Subclasses must implement: - _negative_log_likelihood(): Model-specific likelihood function - _compute_fisher_information(): Fisher information matrix computation - predict_proba(): Predict choice probabilities - simulate(): Simulate choices from the model - counterfactual(): Perform policy/counterfactual analysis

Attributes

Name	Description
device
history
maxiter
optimizer_class
params
tol

Methods

Name	Description
counterfactual	Perform counterfactual analysis comparing scenarios.
fit	Fit the model using maximum likelihood estimation.
predict_proba	Predict choice probabilities for given covariates.
simulate	Simulate choices from the fitted model given covariates.
summary	Print a formatted summary of model estimation results.
to	Move model parameters and fitted data to device.

counterfactual

choice.base.ChoiceModel.counterfactual(X_new)

Perform counterfactual analysis comparing scenarios.

Evaluates how choice probabilities and market shares change under counterfactual scenarios (e.g., price changes, product entry/exit, policy interventions).

Args: X_new: Counterfactual design matrix representing the alternative scenario.

Returns: Dictionary containing counterfactual results. Common keys include: - market_share_original: Baseline market shares - market_share_counterfactual: Counterfactual market shares - change_in_market_share: Difference in market shares

Raises: ValueError: If model has not been fitted yet.

fit

choice.base.ChoiceModel.fit(
    X,
    y,
    init_params=None,
    verbose=False,
    fe=None,
    fe_design=None,
    hdfe_index=None,
    offset=None,
    batch_size=None,
    stderr=True,
)

Fit the model using maximum likelihood estimation.

Optimizes the model parameters to minimize the negative log-likelihood using the specified PyTorch optimizer. After convergence, computes standard errors via the Fisher information matrix.

Args: X: Design matrix of shape (n_samples, n_features). Assumes X includes an intercept column if desired. y: Target vector of shape (n_samples,). init_params: Initial parameter values. For FE-aware GLMs, may be a packed parameter vector or a dict with coef and fe_coef. verbose: If True, prints convergence information. fe: Optional list of 1D fixed-effect ID vectors. fe_design: Optional list of sparse fixed-effect incidence matrices. hdfe_index: Optional index of the FE block to use for fast inference. offset: Optional offset vector added to the linear predictor. batch_size: Optional mini-batch size for first-order optimizers. stderr: Whether to compute standard errors.

Returns: Self (fitted estimator) with populated params dictionary.

Examples: >>> model = LogisticRegression() >>> model.fit(X_train, y_train, verbose=True) >>> print(model.params[“coef”])

predict_proba

choice.base.ChoiceModel.predict_proba(X)

Predict choice probabilities for given covariates.

Args: X: Design matrix or feature tensor. Shape depends on model type.

Returns: Predicted choice probabilities. Shape depends on model type: - Binary models: (n_samples,) - Multinomial models: (n_samples, n_choices)

Raises: ValueError: If model has not been fitted yet.

simulate

choice.base.ChoiceModel.simulate(X)

Simulate choices from the fitted model given covariates.

Uses the fitted parameters to generate synthetic choice data by sampling from the predicted choice probabilities.

Args: X: Design matrix or feature tensor. Shape depends on model type.

Returns: Simulated choices. Shape and type depend on model: - Binary models: (n_samples,) with values in {0, 1} - Multinomial models: (n_samples,) with choice indices

Raises: ValueError: If model has not been fitted yet.

summary

choice.base.ChoiceModel.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.base.ChoiceModel.to(device)

Move model parameters and fitted data to device.