biogeme.nests

Examples of use of several functions.

This is designed for programmers who need examples of use of the functions of the module. The examples are designed to illustrate the syntax. They do not correspond to any meaningful model.

Michel Bierlaire Sun Jun 29 2025, 18:04:39

import numpy as np
from IPython.core.display_functions import display

from biogeme.nests import (
    NestsForCrossNestedLogit,
    NestsForNestedLogit,
    OneNestForCrossNestedLogit,
    OneNestForNestedLogit,
)
from biogeme.version import get_text

Version of Biogeme.

print(get_text())

biogeme 3.3.1 [2025-09-03]
Home page: http://biogeme.epfl.ch
Submit questions to https://groups.google.com/d/forum/biogeme
Michel Bierlaire, Transport and Mobility Laboratory, Ecole Polytechnique Fédérale de Lausanne (EPFL)

Covariance and correlation between two alternatives of a cross-nested logit model. Here, we test a logit model by setting the nest parameters to 1.0. We expect the identify matrix as correlation.

choice_set = [1, 2, 3, 4]
mu_nest_1 = 1.0
alphas_1 = {1: 1, 2: 1}
nest_1 = OneNestForCrossNestedLogit(
    nest_param=mu_nest_1, dict_of_alpha=alphas_1, name='Nest 1'
)
mu_nest_2 = 1.0
alphas_2 = {2: 0.0, 3: 1, 4: 1}
nest_2 = OneNestForCrossNestedLogit(
    nest_param=mu_nest_2, dict_of_alpha=alphas_2, name='Nest 2'
)
nests = NestsForCrossNestedLogit(choice_set=choice_set, tuple_of_nests=(nest_1, nest_2))

In this example, no parameter is involved,

display(nests.correlation(parameters={}))

              1             2             3             4
1  1.000000e+00  8.237105e-12  8.237105e-12  8.237105e-12
2  8.237105e-12  1.000000e+00  8.237105e-12  8.237105e-12
3  8.237105e-12  8.237105e-12  1.000000e+00  8.237105e-12
4  8.237105e-12  8.237105e-12  8.237105e-12  1.000000e+00

Entries of the covariance matrix can also be obtained. Here, we report the variance for alternative i.

display(nests.covariance(i=1, j=1, parameters={}))

1.6449340668482264

It is \(\pi^2/6\).

display(np.pi**2 / 6)

1.6449340668482264

Second, a nested logit model

mu_nest_1 = 1.5
nest_1 = OneNestForNestedLogit(
    nest_param=mu_nest_1, list_of_alternatives=[1, 2], name='Nest 1'
)
mu_nest_2 = 2.0
nest_2 = OneNestForNestedLogit(
    nest_param=mu_nest_2, list_of_alternatives=[3, 4], name='Nest 2'
)
nests = NestsForNestedLogit(choice_set=choice_set, tuple_of_nests=(nest_1, nest_2))

display(nests.correlation(parameters={}))

          1         2     3     4
1  1.000000  0.555556  0.00  0.00
2  0.555556  1.000000  0.00  0.00
3  0.000000  0.000000  1.00  0.75
4  0.000000  0.000000  0.75  1.00

Theoretical value for the correlation

correl_nest_1 = 1 - (1 / mu_nest_1**2)
display(correl_nest_1)

0.5555555555555556

correl_nest_2 = 1 - (1 / mu_nest_2**2)
display(correl_nest_2)

0.75

The same nested logit model, coded as a cross-nested logit

mu_nest_1 = 1.5
alphas_1 = {1: 1, 2: 1}
nest_1 = OneNestForCrossNestedLogit(
    nest_param=mu_nest_1, dict_of_alpha=alphas_1, name='Nest 1'
)
mu_nest_2 = 2.0
alphas_2 = {2: 0.0, 3: 1, 4: 1}
nest_2 = OneNestForCrossNestedLogit(
    nest_param=mu_nest_2, dict_of_alpha=alphas_2, name='Nest 2'
)
nests = NestsForCrossNestedLogit(choice_set=choice_set, tuple_of_nests=(nest_1, nest_2))

display(nests.correlation(parameters={}))

/Users/bierlair/python_envs/venv313/lib/python3.13/site-packages/scipy/integrate/_quadpack_py.py:1260: IntegrationWarning: The integral is probably divergent, or slowly convergent.
  quad_r = quad(f, low, high, args=args, full_output=self.full_output,
/Users/bierlair/python_envs/venv313/lib/python3.13/site-packages/scipy/integrate/_quadpack_py.py:1260: IntegrationWarning: The algorithm does not converge.  Roundoff error is detected
  in the extrapolation table.  It is assumed that the requested tolerance
  cannot be achieved, and that the returned result (if full_output = 1) is
  the best which can be obtained.
  quad_r = quad(f, low, high, args=args, full_output=self.full_output,
              1             2             3             4
1  1.000000e+00  5.555556e-01  8.248444e-12  8.248444e-12
2  5.555556e-01  1.000000e+00  8.248444e-12  8.248444e-12
3  8.248444e-12  8.248444e-12  1.000000e+00  7.500000e-01
4  8.248444e-12  8.248444e-12  7.500000e-01  1.000000e+00

Finally, a cross-nested logit model, where alternative j is correlated with all the other alternatives, and belong to two different nests.

mu_nest_1 = 1.5
alphas_1 = {1: 1, 2: 0.5}
nest_1 = OneNestForCrossNestedLogit(
    nest_param=mu_nest_1, dict_of_alpha=alphas_1, name='Nest 1'
)
mu_nest_2 = 2.0
alphas_2 = {2: 0.5, 3: 1, 4: 1}
nest_2 = OneNestForCrossNestedLogit(
    nest_param=mu_nest_2, dict_of_alpha=alphas_2, name='Nest 2'
)
nests = NestsForCrossNestedLogit(choice_set=choice_set, tuple_of_nests=(nest_1, nest_2))

display(nests.correlation(parameters={}))

/Users/bierlair/python_envs/venv313/lib/python3.13/site-packages/scipy/integrate/_quadpack_py.py:1260: IntegrationWarning: The integral is probably divergent, or slowly convergent.
  quad_r = quad(f, low, high, args=args, full_output=self.full_output,
/Users/bierlair/python_envs/venv313/lib/python3.13/site-packages/scipy/integrate/_quadpack_py.py:1260: IntegrationWarning: The algorithm does not converge.  Roundoff error is detected
  in the extrapolation table.  It is assumed that the requested tolerance
  cannot be achieved, and that the returned result (if full_output = 1) is
  the best which can be obtained.
  quad_r = quad(f, low, high, args=args, full_output=self.full_output,
              1        2             3             4
1  1.000000e+00  0.37618  8.248444e-12  8.248444e-12
2  3.761799e-01  1.00000  5.000000e-01  5.000000e-01
3  8.248444e-12  0.50000  1.000000e+00  7.500000e-01
4  8.248444e-12  0.50000  7.500000e-01  1.000000e+00