.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "auto_examples/programmers/plot_nests.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_auto_examples_programmers_plot_nests.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_auto_examples_programmers_plot_nests.py:


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.

:author: Michel Bierlaire
:date: Wed Nov 29 18:35:06 2023

.. GENERATED FROM PYTHON SOURCE LINES 15-26

.. code-block:: Python


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









.. GENERATED FROM PYTHON SOURCE LINES 27-28

Version of Biogeme.

.. GENERATED FROM PYTHON SOURCE LINES 28-31

.. code-block:: Python

    print(get_text())






.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    biogeme 3.2.14 [2024-08-05]
    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)





.. GENERATED FROM PYTHON SOURCE LINES 32-35

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.

.. GENERATED FROM PYTHON SOURCE LINES 35-49

.. code-block:: Python

    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))









.. GENERATED FROM PYTHON SOURCE LINES 50-51

In this example, no parameter is involved,

.. GENERATED FROM PYTHON SOURCE LINES 51-53

.. code-block:: Python

    nests.correlation(parameters={})






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <div>
    <style scoped>
        .dataframe tbody tr th:only-of-type {
            vertical-align: middle;
        }

        .dataframe tbody tr th {
            vertical-align: top;
        }

        .dataframe thead th {
            text-align: right;
        }
    </style>
    <table border="1" class="dataframe">
      <thead>
        <tr style="text-align: right;">
          <th></th>
          <th>1</th>
          <th>2</th>
          <th>3</th>
          <th>4</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>1</th>
          <td>1.000000e+00</td>
          <td>8.237105e-12</td>
          <td>8.237105e-12</td>
          <td>8.237105e-12</td>
        </tr>
        <tr>
          <th>2</th>
          <td>8.237105e-12</td>
          <td>1.000000e+00</td>
          <td>8.237105e-12</td>
          <td>8.237105e-12</td>
        </tr>
        <tr>
          <th>3</th>
          <td>8.237105e-12</td>
          <td>8.237105e-12</td>
          <td>1.000000e+00</td>
          <td>8.237105e-12</td>
        </tr>
        <tr>
          <th>4</th>
          <td>8.237105e-12</td>
          <td>8.237105e-12</td>
          <td>8.237105e-12</td>
          <td>1.000000e+00</td>
        </tr>
      </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 54-56

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

.. GENERATED FROM PYTHON SOURCE LINES 56-58

.. code-block:: Python

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





.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    1.3549494859432798e-11



.. GENERATED FROM PYTHON SOURCE LINES 59-60

It is :math:`\pi^2/6`.

.. GENERATED FROM PYTHON SOURCE LINES 60-62

.. code-block:: Python

    np.pi**2 / 6





.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    1.6449340668482264



.. GENERATED FROM PYTHON SOURCE LINES 63-64

Second, a nested logit model

.. GENERATED FROM PYTHON SOURCE LINES 64-74

.. code-block:: Python

    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))








.. GENERATED FROM PYTHON SOURCE LINES 75-77

.. code-block:: Python

    nests.correlation(parameters={})






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <div>
    <style scoped>
        .dataframe tbody tr th:only-of-type {
            vertical-align: middle;
        }

        .dataframe tbody tr th {
            vertical-align: top;
        }

        .dataframe thead th {
            text-align: right;
        }
    </style>
    <table border="1" class="dataframe">
      <thead>
        <tr style="text-align: right;">
          <th></th>
          <th>1</th>
          <th>2</th>
          <th>3</th>
          <th>4</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>1</th>
          <td>1.000000</td>
          <td>0.555556</td>
          <td>0.00</td>
          <td>0.00</td>
        </tr>
        <tr>
          <th>2</th>
          <td>0.555556</td>
          <td>1.000000</td>
          <td>0.00</td>
          <td>0.00</td>
        </tr>
        <tr>
          <th>3</th>
          <td>0.000000</td>
          <td>0.000000</td>
          <td>1.00</td>
          <td>0.75</td>
        </tr>
        <tr>
          <th>4</th>
          <td>0.000000</td>
          <td>0.000000</td>
          <td>0.75</td>
          <td>1.00</td>
        </tr>
      </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 78-79

Theoretical value for the correlation

.. GENERATED FROM PYTHON SOURCE LINES 79-82

.. code-block:: Python

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





.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    0.5555555555555556



.. GENERATED FROM PYTHON SOURCE LINES 83-87

.. code-block:: Python

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






.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    0.75



.. GENERATED FROM PYTHON SOURCE LINES 88-89

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

.. GENERATED FROM PYTHON SOURCE LINES 89-104

.. code-block:: Python



    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))









.. GENERATED FROM PYTHON SOURCE LINES 105-107

.. code-block:: Python

    nests.correlation(parameters={})





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    /Users/bierlair/venv312/lib/python3.12/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/venv312/lib/python3.12/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,


.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <div>
    <style scoped>
        .dataframe tbody tr th:only-of-type {
            vertical-align: middle;
        }

        .dataframe tbody tr th {
            vertical-align: top;
        }

        .dataframe thead th {
            text-align: right;
        }
    </style>
    <table border="1" class="dataframe">
      <thead>
        <tr style="text-align: right;">
          <th></th>
          <th>1</th>
          <th>2</th>
          <th>3</th>
          <th>4</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>1</th>
          <td>1.000000e+00</td>
          <td>5.555556e-01</td>
          <td>8.248444e-12</td>
          <td>8.248444e-12</td>
        </tr>
        <tr>
          <th>2</th>
          <td>5.555556e-01</td>
          <td>1.000000e+00</td>
          <td>8.248444e-12</td>
          <td>8.248444e-12</td>
        </tr>
        <tr>
          <th>3</th>
          <td>8.248444e-12</td>
          <td>8.248444e-12</td>
          <td>1.000000e+00</td>
          <td>7.500000e-01</td>
        </tr>
        <tr>
          <th>4</th>
          <td>8.248444e-12</td>
          <td>8.248444e-12</td>
          <td>7.500000e-01</td>
          <td>1.000000e+00</td>
        </tr>
      </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 108-111

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

.. GENERATED FROM PYTHON SOURCE LINES 111-123

.. code-block:: Python

    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))








.. GENERATED FROM PYTHON SOURCE LINES 124-125

.. code-block:: Python

    nests.correlation(parameters={})





.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <div>
    <style scoped>
        .dataframe tbody tr th:only-of-type {
            vertical-align: middle;
        }

        .dataframe tbody tr th {
            vertical-align: top;
        }

        .dataframe thead th {
            text-align: right;
        }
    </style>
    <table border="1" class="dataframe">
      <thead>
        <tr style="text-align: right;">
          <th></th>
          <th>1</th>
          <th>2</th>
          <th>3</th>
          <th>4</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>1</th>
          <td>1.000000e+00</td>
          <td>0.37618</td>
          <td>8.248444e-12</td>
          <td>8.248444e-12</td>
        </tr>
        <tr>
          <th>2</th>
          <td>3.761799e-01</td>
          <td>1.00000</td>
          <td>5.000000e-01</td>
          <td>5.000000e-01</td>
        </tr>
        <tr>
          <th>3</th>
          <td>8.248444e-12</td>
          <td>0.50000</td>
          <td>1.000000e+00</td>
          <td>7.500000e-01</td>
        </tr>
        <tr>
          <th>4</th>
          <td>8.248444e-12</td>
          <td>0.50000</td>
          <td>7.500000e-01</td>
          <td>1.000000e+00</td>
        </tr>
      </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />


.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (1 minutes 32.992 seconds)


.. _sphx_glr_download_auto_examples_programmers_plot_nests.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: plot_nests.ipynb <plot_nests.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: plot_nests.py <plot_nests.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: plot_nests.zip <plot_nests.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_