.. 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-25

.. code-block:: default

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









.. GENERATED FROM PYTHON SOURCE LINES 26-27

Version of Biogeme.

.. GENERATED FROM PYTHON SOURCE LINES 27-30

.. code-block:: default

    print(getText())






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

 .. code-block:: none

    biogeme 3.2.13 [2023-12-23]
    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 31-34

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 34-48

.. code-block:: default

    choice_set = ['i', 'j', 'k', 'm']
    mu_nest_1 = 1.0
    alphas_1 = {'i': 1, 'j': 1}
    nest_1 = OneNestForCrossNestedLogit(
        nest_param=mu_nest_1, dict_of_alpha=alphas_1, name='Nest 1'
    )
    mu_nest_2 = 1.0
    alphas_2 = {'j': 0.0, 'k': 1, 'm': 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 49-51

.. code-block:: default

    nests.correlation()






.. 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>i</th>
          <th>j</th>
          <th>k</th>
          <th>m</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>i</th>
          <td>1.000000e+00</td>
          <td>8.237105e-12</td>
          <td>8.237105e-12</td>
          <td>8.237105e-12</td>
        </tr>
        <tr>
          <th>j</th>
          <td>8.237105e-12</td>
          <td>1.000000e+00</td>
          <td>8.237105e-12</td>
          <td>8.237105e-12</td>
        </tr>
        <tr>
          <th>k</th>
          <td>8.237105e-12</td>
          <td>8.237105e-12</td>
          <td>1.000000e+00</td>
          <td>8.237105e-12</td>
        </tr>
        <tr>
          <th>m</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 52-54

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

.. GENERATED FROM PYTHON SOURCE LINES 54-56

.. code-block:: default

    nests.covariance('i', 'i')





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

 .. code-block:: none


    1.6449340668482264



.. GENERATED FROM PYTHON SOURCE LINES 57-58

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

.. GENERATED FROM PYTHON SOURCE LINES 58-60

.. code-block:: default

    np.pi**2 / 6





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

 .. code-block:: none


    1.6449340668482264



.. GENERATED FROM PYTHON SOURCE LINES 61-62

Second, a nested logit model

.. GENERATED FROM PYTHON SOURCE LINES 62-74

.. code-block:: default

    mu_nest_1 = 1.5
    alphas_1 = {'i': 1, 'j': 1}
    nest_1 = OneNestForNestedLogit(
        nest_param=mu_nest_1, list_of_alternatives=['i', 'j'], name='Nest 1'
    )
    mu_nest_2 = 2.0
    alphas_2 = {'k': 1, 'm': 1}
    nest_2 = OneNestForNestedLogit(
        nest_param=mu_nest_2, list_of_alternatives=['k', 'm'], 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:: default

    nests.correlation()






.. 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>i</th>
          <th>j</th>
          <th>k</th>
          <th>m</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>i</th>
          <td>1.000000</td>
          <td>0.555556</td>
          <td>0.00</td>
          <td>0.00</td>
        </tr>
        <tr>
          <th>j</th>
          <td>0.555556</td>
          <td>1.000000</td>
          <td>0.00</td>
          <td>0.00</td>
        </tr>
        <tr>
          <th>k</th>
          <td>0.000000</td>
          <td>0.000000</td>
          <td>1.00</td>
          <td>0.75</td>
        </tr>
        <tr>
          <th>m</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:: default

    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:: default

    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:: default



    mu_nest_1 = 1.5
    alphas_1 = {'i': 1, 'j': 1}
    nest_1 = OneNestForCrossNestedLogit(
        nest_param=mu_nest_1, dict_of_alpha=alphas_1, name='Nest 1'
    )
    mu_nest_2 = 2.0
    alphas_2 = {'j': 0.0, 'k': 1, 'm': 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:: default

    nests.correlation()





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

 .. code-block:: none

    /Users/bierlair/venv312/lib/python3.12/site-packages/scipy/integrate/_quadpack_py.py:1233: 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:1233: 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>i</th>
          <th>j</th>
          <th>k</th>
          <th>m</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>i</th>
          <td>1.000000e+00</td>
          <td>5.555556e-01</td>
          <td>8.248444e-12</td>
          <td>8.248444e-12</td>
        </tr>
        <tr>
          <th>j</th>
          <td>5.555556e-01</td>
          <td>1.000000e+00</td>
          <td>8.248444e-12</td>
          <td>8.248444e-12</td>
        </tr>
        <tr>
          <th>k</th>
          <td>8.248444e-12</td>
          <td>8.248444e-12</td>
          <td>1.000000e+00</td>
          <td>7.500000e-01</td>
        </tr>
        <tr>
          <th>m</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:: default

    mu_nest_1 = 1.5
    alphas_1 = {'i': 1, 'j': 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 = {'j': 0.5, 'k': 1, 'm': 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:: default

    nests.correlation()





.. 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>i</th>
          <th>j</th>
          <th>k</th>
          <th>m</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>i</th>
          <td>1.000000e+00</td>
          <td>0.37618</td>
          <td>8.248444e-12</td>
          <td>8.248444e-12</td>
        </tr>
        <tr>
          <th>j</th>
          <td>3.761799e-01</td>
          <td>1.00000</td>
          <td>5.000000e-01</td>
          <td>5.000000e-01</td>
        </tr>
        <tr>
          <th>k</th>
          <td>8.248444e-12</td>
          <td>0.50000</td>
          <td>1.000000e+00</td>
          <td>7.500000e-01</td>
        </tr>
        <tr>
          <th>m</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 37.085 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-python

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

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

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


.. only:: html

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

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