NestedLogit.make_exp_nest#

NestedLogit.make_exp_nest(U, W, betas_fixed, lambdas_nests, nest, level='top')[source]#

Calculate within-nest probabilities for nested logit models.

This function recursively computes the utility aggregates used to build a nested logit model within a PyMC probabilistic framework. Specifically, it calculates:

Conditional choice probabilities within a nest:

$$ P(y_i = j mid j in text{nest}) = frac{expleft( frac{U_{ij}}{lambda} right)}

{sum_{j in text{nest}} expleft( frac{U_{ij}}{lambda} right)}

$$

This is a softmax probability scaled by the nest-specific temperature (scale) parameter $ lambda $.

Inclusive value (or log-sum utility):

$$ I_{text{nest}}(i) = lambda cdot log left( sum_{j in text{nest}} exp left( frac{U_{ij}}{lambda} right) right) $$

This quantity represents the “meta-utility” of a nest, passed up the hierarchy in nested logit models.

Exponentiated meta-utility:

An exponentiated term combining inclusive value and fixed covariate contributions, used when computing choice probabilities in the parent nest.

Parameters:

UTensorVariable: Tensor of shape (N, J), where N is the number of observations and J is the number of alternatives. Represents latent utilities.
WTensorVariable or None: Optional tensor of shape (N, K), where K is the number of fixed covariates. Represents covariate contributions that do not vary across alternatives.
betas_fixedTensorVariable: Tensor of shape (J, K), with one coefficient vector per alternative for fixed (non-alternative-varying) covariates.
lambdas_nestsTensorVariable: A tensor containing the nest-specific scale parameters $ lambda $, typically modeled with a Beta distribution.
neststr: Name of the current nest to process (e.g., "Land" or "Land_Car"). Determines which subset of alternatives belongs to the nest.
levelstr, default=”top”: Either "top" or "mid", indicating the level of the nest in the hierarchical structure. Used to select the correct index mapping.

Returns:

exp_W_nestTensorVariable: Exponentiated meta-utility for the current nest, used in the parent nest’s softmax normalization.
P_y_given_nestTensorVariable: Conditional probability of choosing each alternative within the current nest.

Notes

This function supports two-level nested logit models, where alternatives are grouped into mutually exclusive nests. The scale parameter $ lambda $ controls the degree of substitutability within each nest.

Currently, deeper nesting levels (more than two) are not supported, to simplify both modeling and computation.