NestedLogit.prepare_X_matrix#

NestedLogit.prepare_X_matrix(df, utility_formulas, depvar)[source]#

Prepare the X matrix for the utility equations.

The X matrix is a tensor with dimensions: (N observations) x (Alternatives) x (Covariates). Assumes that the utility formulas specify an equal number of covariates per alternative; these can be zero-valued if an alternative lacks a specific attribute.

Utility formulas should express the relationship between the choice outcome (dependent variable) and the attributes of each alternative that incentivize that choice. The left-hand side (LHS) of each formula must correspond to a value of the dependent variable, while the right-hand side (RHS) should define an additive combination of the available covariates.

We also allow the incorporation of fixed covariates that do not vary across alternatives. For these, an alternative-specific parameter is used to allow the contribution to utility to vary by alternative.

Returns:

Tuple containing:
- Xndarray of shape (n_obs, n_alts, n_covariates): The design matrix for the utility model.
- FOptional ndarray of shape (n_obs, n_fixed_covariates): The matrix for fixed covariates (None if no fixed covariates used).
- altslist of str: Names of the alternatives (LHS of the utility equations).
- unique_fixed_covariatesnp.ndarray: Array of unique fixed covariate names.