Nested logit model

Example of a nested logit model.

Michel Bierlaire, EPFL Sat Jun 21 2025, 15:33:00

from IPython.core.display_functions import display
from biogeme import biogeme_logging as blog
from biogeme.biogeme import BIOGEME
from biogeme.expressions import Beta
from biogeme.models import lognested
from biogeme.nests import NestsForNestedLogit, OneNestForNestedLogit
from biogeme.results_processing import get_pandas_estimated_parameters

See the data processing script: Data preparation for Swissmetro.

from swissmetro_data import (
    CAR_AV_SP,
    CAR_CO_SCALED,
    CAR_TT_SCALED,
    CHOICE,
    SM_AV,
    SM_COST_SCALED,
    SM_TT_SCALED,
    TRAIN_AV_SP,
    TRAIN_COST_SCALED,
    TRAIN_TT_SCALED,
    database,
)

logger = blog.get_screen_logger(level=blog.INFO)
logger.info('Example b09nested')

Example b09nested

Parameters to be estimated.

asc_car = Beta('asc_car', 0, None, None, 0)
asc_train = Beta('asc_train', 0, None, None, 0)
asc_sm = Beta('asc_sm', 0, None, None, 1)
b_time = Beta('b_time', 0, None, None, 0)
b_cost = Beta('b_cost', 0, None, None, 0)
nest_parameter = Beta('nest_parameter', 1, 1, 3, 0)

Definition of the utility functions.

v_train = asc_train + b_time * TRAIN_TT_SCALED + b_cost * TRAIN_COST_SCALED
v_swissmetro = asc_sm + b_time * SM_TT_SCALED + b_cost * SM_COST_SCALED
v_car = asc_car + b_time * CAR_TT_SCALED + b_cost * CAR_CO_SCALED

Associate utility functions with the numbering of alternatives.

v = {1: v_train, 2: v_swissmetro, 3: v_car}

Associate the availability conditions with the alternatives.

av = {1: TRAIN_AV_SP, 2: SM_AV, 3: CAR_AV_SP}

Definition of nests. Only the non-trivial nests must be defined. A trivial nest is a nest containing exactly one alternative. In this example, we create a nest for the existing modes, that is train (1) and car (3).

existing = OneNestForNestedLogit(
    nest_param=nest_parameter, list_of_alternatives=[1, 3], name='existing'
)

nests = NestsForNestedLogit(choice_set=list(v), tuple_of_nests=(existing,))

The following elements do not appear in any nest and are assumed each to be alone in a separate nest: {2}. If it is not the intention, check the assignment of alternatives to nests.

Definition of the model. This is the contribution of each observation to the log likelihood function. The choice model is a nested logit, with availability conditions.

log_probability = lognested(v, av, nests, CHOICE)

Create the Biogeme object.

the_biogeme = BIOGEME(
    database, log_probability, optimization_algorithm='simple_bounds_BFGS'
)
the_biogeme.modelName = "b09nested"

Biogeme parameters read from biogeme.toml.
/Users/bierlair/MyFiles/github/biogeme/docs/source/examples/swissmetro/plot_b09nested.py:85: DeprecationWarning: 'modelName' is deprecated. Please use 'model_name' instead.
  the_biogeme.modelName = "b09nested"

Calculate the null log likelihood for reporting.

the_biogeme.calculate_null_loglikelihood(av)

-6964.662979192191

Estimate the parameters

results = the_biogeme.estimate()

*** Initial values of the parameters are obtained from the file __b09nested.iter
Parameter values restored from __b09nested.iter
Starting values for the algorithm: {'asc_train': -0.5119573878979035, 'b_time': -0.8987202255038353, 'b_cost': -0.8566967912527499, 'nest_parameter': 2.053866579484938, 'asc_car': -0.16713665097004932}
Optimization algorithm: BFGS with simple bounds [simple_bounds_BFGS].
Optimization algorithm: hybrid Newton/BFGS with simple bounds [simple_bounds]
** Optimization: BFGS with trust region for simple bounds
Optimization algorithm has converged.
Relative gradient: 5.681064121356373e-06
Cause of termination: Relative gradient = 5.7e-06 <= 6.1e-06
Number of function evaluations: 1
Number of gradient evaluations: 1
Number of hessian evaluations: 0
Algorithm: BFGS with trust region for simple bound constraints
Number of iterations: 0
Optimization time: 0:00:00.398498
Calculate second derivatives and BHHH
File b09nested~01.html has been generated.
File b09nested~01.yaml has been generated.

print(results.short_summary())

Results for model b09nested
Nbr of parameters:              5
Sample size:                    6768
Excluded data:                  3960
Null log likelihood:            -6964.663
Final log likelihood:           -5236.9
Likelihood ratio test (null):           3455.526
Rho square (null):                      0.248
Rho bar square (null):                  0.247
Akaike Information Criterion:   10483.8
Bayesian Information Criterion: 10517.9

pandas_results = get_pandas_estimated_parameters(estimation_results=results)
display(pandas_results)

             Name     Value  Robust std err.  Robust t-stat.  Robust p-value
0       asc_train -0.511957         0.079115       -6.471071    9.731105e-11
1          b_time -0.898720         0.107109       -8.390695    0.000000e+00
2          b_cost -0.856697         0.060033      -14.270350    0.000000e+00
3  nest_parameter  2.053867         0.164162       12.511219    0.000000e+00
4         asc_car -0.167137         0.054529       -3.065110    2.175902e-03

We calculate the correlation between the error terms of the alternatives.

corr = nests.correlation(
    parameters=results.get_beta_values(),
    alternatives_names={1: 'Train', 2: 'Swissmetro', 3: 'Car'},
)
print(corr)

               Train  Swissmetro       Car
Train       1.000000         0.0  0.762941
Swissmetro  0.000000         1.0  0.000000
Car         0.762941         0.0  1.000000