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

.. code-block:: default


    import numpy as np
    import pandas as pd
    from biogeme.version import getText
    from biogeme import tools
    import biogeme.biogeme_logging as blog
    import biogeme.exceptions as excep








.. GENERATED FROM PYTHON SOURCE LINES 24-25

Version of Biogeme.

.. GENERATED FROM PYTHON SOURCE LINES 25-27

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

.. code-block:: default

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









.. GENERATED FROM PYTHON SOURCE LINES 32-41

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 41-58

.. code-block:: default

    def my_function(x: np.ndarray) -> tuple[float, np.ndarray, np.ndarray]:
        """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 f, g, H









.. GENERATED FROM PYTHON SOURCE LINES 59-63

Evaluate the function at the point

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


.. GENERATED FROM PYTHON SOURCE LINES 63-66

.. code-block:: default

    x = np.array([1.1, 1.1])
    f, g, H = my_function(x)








.. GENERATED FROM PYTHON SOURCE LINES 67-69

.. code-block:: default

    f





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

 .. code-block:: none


    3.099476203750758



.. GENERATED FROM PYTHON SOURCE LINES 70-71

We use the `DataFrame` for a nicer display.

.. GENERATED FROM PYTHON SOURCE LINES 71-73

.. code-block:: default

    pd.DataFrame(g)






.. 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 74-76

.. code-block:: default

    pd.DataFrame(H)






.. 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 77-78

Calculates an approximation of the gradient by finite differences.

.. GENERATED FROM PYTHON SOURCE LINES 78-80

.. code-block:: default

    g_fd = tools.findiff_g(my_function, x)








.. GENERATED FROM PYTHON SOURCE LINES 81-83

.. code-block:: default

    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 84-85

Check the precision of the approximation

.. GENERATED FROM PYTHON SOURCE LINES 85-87

.. code-block:: default

    pd.DataFrame(g - 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 88-89

Calculates an approximation of the Hessian by finite differences.

.. GENERATED FROM PYTHON SOURCE LINES 89-91

.. code-block:: default

    H_fd = tools.findiff_H(my_function, x)








.. GENERATED FROM PYTHON SOURCE LINES 92-94

.. code-block:: default

    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 95-96

Check the precision of the approximation

.. GENERATED FROM PYTHON SOURCE LINES 96-98

.. code-block:: default

    pd.DataFrame(H - 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 99-101

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

.. GENERATED FROM PYTHON SOURCE LINES 101-103

.. code-block:: default

    f, g, h, gdiff, hdiff = tools.checkDerivatives(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 104-105

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

.. GENERATED FROM PYTHON SOURCE LINES 107-111

.. code-block:: default

    f, g, h, gdiff, hdiff = tools.checkDerivatives(
        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 112-114

.. code-block:: default

    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 115-117

.. code-block:: default

    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 118-119

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

.. GENERATED FROM PYTHON SOURCE LINES 119-122

.. code-block:: default

    myprimes = tools.calculate_prime_numbers(10)
    myprimes





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

 .. code-block:: none


    [2, 3, 5, 7]



.. GENERATED FROM PYTHON SOURCE LINES 123-126

.. code-block:: default

    myprimes = tools.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 127-128

Calculate a given number of prime numbers.

.. GENERATED FROM PYTHON SOURCE LINES 128-131

.. code-block:: default

    myprimes = tools.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 132-133

Counting groups of data.

.. GENERATED FROM PYTHON SOURCE LINES 133-135

.. code-block:: default

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








.. GENERATED FROM PYTHON SOURCE LINES 136-143

.. code-block:: default

    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 144-146

.. code-block:: default

    tools.countNumberOfGroups(df, 'ID')





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

 .. code-block:: none


    6



.. GENERATED FROM PYTHON SOURCE LINES 147-149

.. code-block:: default

    tools.countNumberOfGroups(df, 'value')





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

 .. code-block:: none


    7



.. GENERATED FROM PYTHON SOURCE LINES 150-151

Likelihood ratio test.

.. GENERATED FROM PYTHON SOURCE LINES 151-154

.. code-block:: default

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








.. GENERATED FROM PYTHON SOURCE LINES 155-157

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

.. GENERATED FROM PYTHON SOURCE LINES 157-159

.. code-block:: default

    tools.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=5.991464547107979)



.. GENERATED FROM PYTHON SOURCE LINES 160-161

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

.. GENERATED FROM PYTHON SOURCE LINES 161-163

.. code-block:: default

    tools.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=0.21072103131565265)



.. GENERATED FROM PYTHON SOURCE LINES 164-165

The order in which the models are presented is irrelevant.

.. GENERATED FROM PYTHON SOURCE LINES 165-167

.. code-block:: default

    tools.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=5.991464547107979)



.. GENERATED FROM PYTHON SOURCE LINES 168-170

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

.. GENERATED FROM PYTHON SOURCE LINES 170-173

.. code-block:: default

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








.. GENERATED FROM PYTHON SOURCE LINES 174-178

.. code-block:: default

    try:
        tools.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.010 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-python

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

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

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


.. only:: html

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

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