.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "auto_examples/programmers/plot_tools.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_tools.py>`
        to download the full example code.

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

.. _sphx_glr_auto_examples_programmers_plot_tools.py:


biogeme.tools
=============

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: Sat Dec  2 13:09:42 2023

.. GENERATED FROM PYTHON SOURCE LINES 15-26

.. code-block:: Python


    import numpy as np
    import pandas as pd

    import biogeme.biogeme_logging as blog
    import biogeme.exceptions as excep
    import biogeme.tools.derivatives
    import biogeme.tools.primes
    from biogeme.function_output import FunctionOutput
    from biogeme.version import get_text








.. GENERATED FROM PYTHON SOURCE LINES 27-28

Version of Biogeme.

.. GENERATED FROM PYTHON SOURCE LINES 28-30

.. 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 31-34

.. code-block:: Python

    logger = blog.get_screen_logger(level=blog.INFO)









.. GENERATED FROM PYTHON SOURCE LINES 35-44

Define a function and its derivatives:

.. math:: f = \log(x_0) + \exp(x_1),

.. math:: g = \left( \begin{array}{c}\frac{1}{x_0} \\
    \exp(x_1)\end{array}\right),

.. math:: h=\left(\begin{array}{cc} -\frac{1}{x_0^2} & 0 \\ 0 &
    \exp(x_1)\end{array}\right).

.. GENERATED FROM PYTHON SOURCE LINES 44-61

.. code-block:: Python

    def my_function(x: np.ndarray) -> FunctionOutput:
        """Implementation of the test function.

        :param x: point at which the function and its derivatives must be evaluated.
        """
        f = np.log(x[0]) + np.exp(x[1])
        g = np.empty(2)
        g[0] = 1.0 / x[0]
        g[1] = np.exp(x[1])
        h = np.empty((2, 2))
        h[0, 0] = -1.0 / x[0] ** 2
        h[0, 1] = 0.0
        h[1, 0] = 0.0
        h[1, 1] = np.exp(x[1])
        return FunctionOutput(function=f, gradient=g, hessian=h)









.. GENERATED FROM PYTHON SOURCE LINES 62-66

Evaluate the function at the point

.. math:: x = \left( \begin{array}{c}1.1 \\ 1.1 \end{array}\right).


.. GENERATED FROM PYTHON SOURCE LINES 66-69

.. code-block:: Python

    x = np.array([1.1, 1.1])
    the_output = my_function(x)








.. GENERATED FROM PYTHON SOURCE LINES 70-72

.. code-block:: Python

    the_output.function





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

 .. code-block:: none


    np.float64(3.099476203750758)



.. GENERATED FROM PYTHON SOURCE LINES 73-74

We use the `DataFrame` for a nicer display.

.. GENERATED FROM PYTHON SOURCE LINES 74-76

.. code-block:: Python

    pd.DataFrame(the_output.gradient)






.. 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>0</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>0.909091</td>
        </tr>
        <tr>
          <th>1</th>
          <td>3.004166</td>
        </tr>
      </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 77-79

.. code-block:: Python

    pd.DataFrame(the_output.hessian)






.. 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>0</th>
          <th>1</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>-0.826446</td>
          <td>0.000000</td>
        </tr>
        <tr>
          <th>1</th>
          <td>0.000000</td>
          <td>3.004166</td>
        </tr>
      </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 80-81

Calculates an approximation of the gradient by finite differences.

.. GENERATED FROM PYTHON SOURCE LINES 81-83

.. code-block:: Python

    g_fd = biogeme.tools.derivatives.findiff_g(my_function, x)








.. GENERATED FROM PYTHON SOURCE LINES 84-86

.. code-block:: Python

    pd.DataFrame(g_fd)






.. 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>0</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>0.909091</td>
        </tr>
        <tr>
          <th>1</th>
          <td>3.004166</td>
        </tr>
      </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 87-88

Check the precision of the approximation

.. GENERATED FROM PYTHON SOURCE LINES 88-90

.. code-block:: Python

    pd.DataFrame(the_output.gradient - g_fd)






.. 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>0</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>4.185955e-08</td>
        </tr>
        <tr>
          <th>1</th>
          <td>-1.645947e-07</td>
        </tr>
      </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 91-92

Calculates an approximation of the Hessian by finite differences.

.. GENERATED FROM PYTHON SOURCE LINES 92-94

.. code-block:: Python

    h_fd = biogeme.tools.derivatives.findiff_h(my_function, x)








.. GENERATED FROM PYTHON SOURCE LINES 95-97

.. code-block:: Python

    pd.DataFrame(h_fd)






.. 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>0</th>
          <th>1</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>-0.826446</td>
          <td>0.000000</td>
        </tr>
        <tr>
          <th>1</th>
          <td>0.000000</td>
          <td>3.004166</td>
        </tr>
      </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 98-99

Check the precision of the approximation

.. GENERATED FROM PYTHON SOURCE LINES 99-101

.. code-block:: Python

    pd.DataFrame(the_output.hessian - h_fd)






.. 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>0</th>
          <th>1</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>-8.264656e-08</td>
          <td>0.000000e+00</td>
        </tr>
        <tr>
          <th>1</th>
          <td>0.000000e+00</td>
          <td>-1.645947e-07</td>
        </tr>
      </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 102-104

There is a function that checks the analytical derivatives by
comparing them to their finite difference approximation.

.. GENERATED FROM PYTHON SOURCE LINES 104-108

.. code-block:: Python

    f, g, h, gdiff, hdiff = biogeme.tools.derivatives.check_derivatives(
        my_function, x, names=None, logg=True
    )





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

 .. code-block:: none

    x               Gradient        FinDiff         Difference 
    x[0]            +9.090909E-01   +9.090909E-01   +4.185955E-08 
    x[1]            +3.004166E+00   +3.004166E+00   -1.645947E-07 
    Row             Col             Hessian FinDiff         Difference 
    x[0]            x[0]            -8.264463E-01   -8.264462E-01   -8.264656E-08 
    x[0]            x[1]            +0.000000E+00   +0.000000E+00   +0.000000E+00 
    x[1]            x[0]            +0.000000E+00   +0.000000E+00   +0.000000E+00 
    x[1]            x[1]            +3.004166E+00   +3.004166E+00   -1.645947E-07 




.. GENERATED FROM PYTHON SOURCE LINES 109-110

To help reading the reporting, it is possible to give names to variables.

.. GENERATED FROM PYTHON SOURCE LINES 112-116

.. code-block:: Python

    f, g, h, gdiff, hdiff = biogeme.tools.derivatives.check_derivatives(
        my_function, x, names=['First', 'Second'], logg=True
    )





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

 .. code-block:: none

    x               Gradient        FinDiff         Difference 
    First           +9.090909E-01   +9.090909E-01   +4.185955E-08 
    Second          +3.004166E+00   +3.004166E+00   -1.645947E-07 
    Row             Col             Hessian FinDiff         Difference 
    First           First           -8.264463E-01   -8.264462E-01   -8.264656E-08 
    First           Second          +0.000000E+00   +0.000000E+00   +0.000000E+00 
    Second          First           +0.000000E+00   +0.000000E+00   +0.000000E+00 
    Second          Second          +3.004166E+00   +3.004166E+00   -1.645947E-07 




.. GENERATED FROM PYTHON SOURCE LINES 117-119

.. code-block:: Python

    pd.DataFrame(gdiff)






.. 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>0</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>4.185955e-08</td>
        </tr>
        <tr>
          <th>1</th>
          <td>-1.645947e-07</td>
        </tr>
      </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 120-122

.. code-block:: Python

    hdiff





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

 .. code-block:: none


    array([[-8.26465610e-08,  0.00000000e+00],
           [ 0.00000000e+00, -1.64594663e-07]])



.. GENERATED FROM PYTHON SOURCE LINES 123-124

Prime numbers: calculate prime numbers lesser or equal to an upper bound.

.. GENERATED FROM PYTHON SOURCE LINES 124-127

.. code-block:: Python

    myprimes = biogeme.tools.primes.calculate_prime_numbers(10)
    myprimes





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

 .. code-block:: none


    [2, 3, 5, 7]



.. GENERATED FROM PYTHON SOURCE LINES 128-131

.. code-block:: Python

    myprimes = biogeme.tools.primes.calculate_prime_numbers(100)
    myprimes





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

 .. code-block:: none


    [2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47, 53, 59, 61, 67, 71, 73, 79, 83, 89, 97]



.. GENERATED FROM PYTHON SOURCE LINES 132-133

Calculate a given number of prime numbers.

.. GENERATED FROM PYTHON SOURCE LINES 133-136

.. code-block:: Python

    myprimes = biogeme.tools.primes.get_prime_numbers(7)
    myprimes





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

 .. code-block:: none


    [2, 3, 5, 7, 11, 13, 17]



.. GENERATED FROM PYTHON SOURCE LINES 137-138

Counting groups of data.

.. GENERATED FROM PYTHON SOURCE LINES 138-140

.. code-block:: Python

    alist = [1, 2, 2, 3, 3, 3, 4, 1, 1]








.. GENERATED FROM PYTHON SOURCE LINES 141-148

.. code-block:: Python

    df = pd.DataFrame(
        {
            'ID': [1, 1, 2, 3, 3, 1, 2, 3],
            'value': [1000, 2000, 3000, 4000, 5000, 5000, 10000, 20000],
        }
    )








.. GENERATED FROM PYTHON SOURCE LINES 149-151

.. code-block:: Python

    biogeme.tools.count_number_of_groups(df, 'ID')





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

 .. code-block:: none


    6



.. GENERATED FROM PYTHON SOURCE LINES 152-154

.. code-block:: Python

    biogeme.tools.count_number_of_groups(df, 'value')





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

 .. code-block:: none


    7



.. GENERATED FROM PYTHON SOURCE LINES 155-156

Likelihood ratio test.

.. GENERATED FROM PYTHON SOURCE LINES 156-159

.. code-block:: Python

    model1 = (-1340.8, 5)
    model2 = (-1338.49, 7)








.. GENERATED FROM PYTHON SOURCE LINES 160-162

A likelihood ratio test is performed. The function returns the
outcome of the test, the statistic, and the threshold.

.. GENERATED FROM PYTHON SOURCE LINES 162-164

.. code-block:: Python

    biogeme.tools.likelihood_ratio.likelihood_ratio_test(model1, model2)





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

 .. code-block:: none


    LRTuple(message='H0 cannot be rejected at level 5.0%', statistic=4.619999999999891, threshold=np.float64(5.99146454710798))



.. GENERATED FROM PYTHON SOURCE LINES 165-166

The default level of significance is 0.95. It can be changed.

.. GENERATED FROM PYTHON SOURCE LINES 166-170

.. code-block:: Python

    biogeme.tools.likelihood_ratio.likelihood_ratio_test(
        model1, model2, significance_level=0.9
    )





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

 .. code-block:: none


    LRTuple(message='H0 can be rejected at level 90.0%', statistic=4.619999999999891, threshold=np.float64(0.21072103131565265))



.. GENERATED FROM PYTHON SOURCE LINES 171-172

The order in which the models are presented is irrelevant.

.. GENERATED FROM PYTHON SOURCE LINES 172-174

.. code-block:: Python

    biogeme.tools.likelihood_ratio.likelihood_ratio_test(model2, model1)





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

 .. code-block:: none


    LRTuple(message='H0 cannot be rejected at level 5.0%', statistic=4.619999999999891, threshold=np.float64(5.99146454710798))



.. GENERATED FROM PYTHON SOURCE LINES 175-177

But the unrestricted model must have a higher loglikelihood than the
restricted one.

.. GENERATED FROM PYTHON SOURCE LINES 177-180

.. code-block:: Python

    model1 = (-1340.8, 7)
    model2 = (-1338.49, 5)








.. GENERATED FROM PYTHON SOURCE LINES 181-185

.. code-block:: Python

    try:
        biogeme.tools.likelihood_ratio.likelihood_ratio_test(model1, model2)
    except excep.BiogemeError as e:
        print(e)




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

 .. code-block:: none

    The unrestricted model (-1340.8, 7) has a lower log likelihood than the restricted one (-1338.49, 5)





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

   **Total running time of the script:** (0 minutes 0.012 seconds)


.. _sphx_glr_download_auto_examples_programmers_plot_tools.py:

.. only:: html

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

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

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

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

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

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

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


.. only:: html

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

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