.. DO NOT EDIT. .. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY. .. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE: .. "auto_examples/programmers/plot_draws.py" .. LINE NUMBERS ARE GIVEN BELOW. .. only:: html .. note:: :class: sphx-glr-download-link-note :ref:`Go to the end ` to download the full example code. .. rst-class:: sphx-glr-example-title .. _sphx_glr_auto_examples_programmers_plot_draws.py: biogeme.draws ============= 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, 06:41:25 .. GENERATED FROM PYTHON SOURCE LINES 17-32 .. code-block:: Python import numpy as np import pandas as pd from IPython.core.display_functions import display from biogeme.draws import ( description_of_native_draws, get_antithetic, get_halton_draws, get_latin_hypercube_draws, get_normal_wichura_draws, get_uniform, native_random_number_generators, ) from biogeme.version import get_text .. GENERATED FROM PYTHON SOURCE LINES 33-34 Version of Biogeme. .. GENERATED FROM PYTHON SOURCE LINES 34-36 .. code-block:: Python print(get_text()) .. rst-class:: sphx-glr-script-out .. code-block:: none 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) .. GENERATED FROM PYTHON SOURCE LINES 37-38 We set the seed so that the outcome of random operations is always the same. .. GENERATED FROM PYTHON SOURCE LINES 38-40 .. code-block:: Python np.random.seed(90267) .. GENERATED FROM PYTHON SOURCE LINES 41-43 Uniform draws ------------- .. GENERATED FROM PYTHON SOURCE LINES 45-46 Uniform [0,1]. The output is transformed into a data frame just for the display. .. GENERATED FROM PYTHON SOURCE LINES 46-49 .. code-block:: Python draws = get_uniform(sample_size=3, number_of_draws=10, symmetric=False) display(pd.DataFrame(draws)) .. rst-class:: sphx-glr-script-out .. code-block:: none 0 1 2 ... 7 8 9 0 0.406996 0.952091 0.393300 ... 0.282152 0.294621 0.294378 1 0.719719 0.976471 0.860015 ... 0.259457 0.246732 0.608131 2 0.914063 0.253449 0.299638 ... 0.848053 0.775280 0.234141 [3 rows x 10 columns] .. GENERATED FROM PYTHON SOURCE LINES 50-53 .. code-block:: Python draws = get_uniform(sample_size=3, number_of_draws=10, symmetric=True) display(pd.DataFrame(draws)) .. rst-class:: sphx-glr-script-out .. code-block:: none 0 1 2 ... 7 8 9 0 0.541595 -0.613439 0.410899 ... -0.499704 -0.941578 0.433283 1 -0.395955 0.442475 0.265263 ... -0.620988 0.553554 -0.213905 2 -0.797249 0.439322 0.127049 ... 0.536699 0.022698 -0.761527 [3 rows x 10 columns] .. GENERATED FROM PYTHON SOURCE LINES 54-57 LatinHypercube: the Modified Latin Hypercube Sampling (MLHS, Hess et al., 2006) provides U[0,1] draws from a perturbed grid, designed for Monte-Carlo integration. .. GENERATED FROM PYTHON SOURCE LINES 59-62 .. code-block:: Python latin_hypercube = get_latin_hypercube_draws(sample_size=3, number_of_draws=10) display(pd.DataFrame(latin_hypercube)) .. rst-class:: sphx-glr-script-out .. code-block:: none 0 1 2 ... 7 8 9 0 0.325211 0.630001 0.177462 ... 0.088749 0.155039 0.539467 1 0.986429 0.028337 0.585812 ... 0.350411 0.955311 0.702116 2 0.744942 0.884753 0.046556 ... 0.251115 0.204371 0.481789 [3 rows x 10 columns] .. GENERATED FROM PYTHON SOURCE LINES 63-64 The same method can be used to generate draws from U[-1,1] .. GENERATED FROM PYTHON SOURCE LINES 66-71 .. code-block:: Python latin_hypercube = get_latin_hypercube_draws( sample_size=5, number_of_draws=10, symmetric=True ) display(pd.DataFrame(latin_hypercube)) .. rst-class:: sphx-glr-script-out .. code-block:: none 0 1 2 ... 7 8 9 0 -0.487827 0.946583 -0.290890 ... 0.060902 -0.703703 -0.660290 1 -0.119771 0.903854 0.518566 ... 0.014049 0.592416 0.333544 2 -0.536467 -0.602720 0.421731 ... -0.406895 0.652804 0.186110 3 0.149259 -0.053414 -0.356505 ... 0.312416 -0.747227 0.112625 4 -0.914200 0.238546 0.738524 ... 0.460820 0.362292 0.852471 [5 rows x 10 columns] .. GENERATED FROM PYTHON SOURCE LINES 72-73 The user can provide her own series of U[0,1] draws. .. GENERATED FROM PYTHON SOURCE LINES 73-76 .. code-block:: Python my_unif = np.random.uniform(size=30) display(pd.DataFrame(my_unif)) .. rst-class:: sphx-glr-script-out .. code-block:: none 0 0 0.061760 1 0.201607 2 0.779832 3 0.602527 4 0.696678 5 0.764274 6 0.568655 7 0.371194 8 0.233237 9 0.023673 10 0.339896 11 0.060995 12 0.221347 13 0.476015 14 0.866055 15 0.350926 16 0.644284 17 0.904649 18 0.857553 19 0.132332 20 0.408866 21 0.415191 22 0.502339 23 0.498379 24 0.612381 25 0.675059 26 0.349810 27 0.033002 28 0.145176 29 0.237861 .. GENERATED FROM PYTHON SOURCE LINES 77-82 .. code-block:: Python latin_hypercube = get_latin_hypercube_draws( sample_size=3, number_of_draws=10, symmetric=False, uniform_numbers=my_unif ) display(pd.DataFrame(latin_hypercube)) .. rst-class:: sphx-glr-script-out .. code-block:: none 0 1 2 ... 7 8 9 0 0.783279 0.092661 0.407378 ... 0.300789 0.245706 0.218955 1 0.002059 0.750078 0.554809 ... 0.040054 0.680296 0.938173 2 0.511698 0.449200 0.637744 ... 0.713840 0.344663 0.495535 [3 rows x 10 columns] .. GENERATED FROM PYTHON SOURCE LINES 83-84 The uniform draws can also be arranged in a two-dimension array .. GENERATED FROM PYTHON SOURCE LINES 84-87 .. code-block:: Python my_unif = get_uniform(sample_size=3, number_of_draws=10) display(pd.DataFrame(my_unif)) .. rst-class:: sphx-glr-script-out .. code-block:: none 0 1 2 ... 7 8 9 0 0.429347 0.603875 0.896565 ... 0.224726 0.904498 0.097305 1 0.091637 0.288086 0.133953 ... 0.982264 0.660052 0.075265 2 0.336336 0.374114 0.464009 ... 0.109902 0.945957 0.756240 [3 rows x 10 columns] .. GENERATED FROM PYTHON SOURCE LINES 88-93 .. code-block:: Python latin_hypercube = get_latin_hypercube_draws( sample_size=3, number_of_draws=10, uniform_numbers=my_unif ) display(pd.DataFrame(latin_hypercube)) .. rst-class:: sphx-glr-script-out .. code-block:: none 0 1 2 ... 7 8 9 0 0.181712 0.800272 0.903663 ... 0.544630 0.599409 0.125153 1 0.677878 0.991875 0.748800 ... 0.158992 0.014312 0.635842 2 0.096552 0.296817 0.053463 ... 0.376270 0.964865 0.622002 [3 rows x 10 columns] .. GENERATED FROM PYTHON SOURCE LINES 94-96 Halton draws ------------ .. GENERATED FROM PYTHON SOURCE LINES 98-99 One Halton sequence. .. GENERATED FROM PYTHON SOURCE LINES 99-102 .. code-block:: Python halton = get_halton_draws(sample_size=2, number_of_draws=10, base=3) display(pd.DataFrame(halton)) .. rst-class:: sphx-glr-script-out .. code-block:: none 0 1 2 ... 7 8 9 0 0.333333 0.666667 0.111111 ... 0.888889 0.037037 0.370370 1 0.703704 0.148148 0.481481 ... 0.074074 0.407407 0.740741 [2 rows x 10 columns] .. GENERATED FROM PYTHON SOURCE LINES 103-104 Several Halton sequences. .. GENERATED FROM PYTHON SOURCE LINES 104-107 .. code-block:: Python halton = get_halton_draws(sample_size=3, number_of_draws=10) display(pd.DataFrame(halton)) .. rst-class:: sphx-glr-script-out .. code-block:: none 0 1 2 3 ... 6 7 8 9 0 0.50000 0.25000 0.75000 0.12500 ... 0.87500 0.06250 0.56250 0.31250 1 0.81250 0.18750 0.68750 0.43750 ... 0.53125 0.28125 0.78125 0.15625 2 0.65625 0.40625 0.90625 0.09375 ... 0.84375 0.21875 0.71875 0.46875 [3 rows x 10 columns] .. GENERATED FROM PYTHON SOURCE LINES 108-109 Shuffled Halton sequences. .. GENERATED FROM PYTHON SOURCE LINES 109-112 .. code-block:: Python halton = get_halton_draws(sample_size=3, number_of_draws=10, shuffled=True) display(pd.DataFrame(halton)) .. rst-class:: sphx-glr-script-out .. code-block:: none 0 1 2 3 ... 6 7 8 9 0 0.25000 0.12500 0.28125 0.46875 ... 0.09375 0.31250 0.81250 0.21875 1 0.71875 0.78125 0.50000 0.37500 ... 0.87500 0.90625 0.40625 0.65625 2 0.84375 0.18750 0.43750 0.56250 ... 0.68750 0.15625 0.06250 0.75000 [3 rows x 10 columns] .. GENERATED FROM PYTHON SOURCE LINES 113-115 The above sequences were generated using the default base: 2. It is possible to generate sequences using different prime numbers. .. GENERATED FROM PYTHON SOURCE LINES 115-118 .. code-block:: Python halton = get_halton_draws(sample_size=1, number_of_draws=10, base=3) display(pd.DataFrame(halton)) .. rst-class:: sphx-glr-script-out .. code-block:: none 0 1 2 ... 7 8 9 0 0.333333 0.666667 0.111111 ... 0.888889 0.037037 0.37037 [1 rows x 10 columns] .. GENERATED FROM PYTHON SOURCE LINES 119-121 It is also possible to skip the first items of the sequence. This is desirable in the context of Monte-Carlo integration. .. GENERATED FROM PYTHON SOURCE LINES 121-124 .. code-block:: Python halton = get_halton_draws(sample_size=1, number_of_draws=10, base=3, skip=10) display(pd.DataFrame(halton)) .. rst-class:: sphx-glr-script-out .. code-block:: none 0 1 2 ... 7 8 9 0 0.703704 0.148148 0.481481 ... 0.074074 0.407407 0.740741 [1 rows x 10 columns] .. GENERATED FROM PYTHON SOURCE LINES 125-127 Antithetic draws ---------------- .. GENERATED FROM PYTHON SOURCE LINES 129-130 Antithetic draws can be generated from any function generating uniform draws. .. GENERATED FROM PYTHON SOURCE LINES 130-133 .. code-block:: Python draws = get_antithetic(get_uniform, sample_size=3, number_of_draws=10) display(pd.DataFrame(draws)) .. rst-class:: sphx-glr-script-out .. code-block:: none 0 1 2 ... 7 8 9 0 0.422126 0.471794 0.148715 ... 0.851285 0.261399 0.958948 1 0.512323 0.765719 0.501317 ... 0.498683 0.853532 0.441461 2 0.417705 0.778921 0.752020 ... 0.247980 0.956797 0.744472 [3 rows x 10 columns] .. GENERATED FROM PYTHON SOURCE LINES 134-135 Antithetic MLHS .. GENERATED FROM PYTHON SOURCE LINES 135-138 .. code-block:: Python draws = get_antithetic(get_latin_hypercube_draws, sample_size=3, number_of_draws=10) display(pd.DataFrame(draws)) .. rst-class:: sphx-glr-script-out .. code-block:: none 0 1 2 ... 7 8 9 0 0.078073 0.313795 0.158663 ... 0.841337 0.984815 0.578188 1 0.478287 0.769973 0.244302 ... 0.755698 0.387797 0.093254 2 0.949357 0.561688 0.722550 ... 0.277450 0.649560 0.192475 [3 rows x 10 columns] .. GENERATED FROM PYTHON SOURCE LINES 139-140 Antithetic Halton. .. GENERATED FROM PYTHON SOURCE LINES 140-144 .. code-block:: Python draws = get_antithetic(get_halton_draws, sample_size=1, number_of_draws=10) display(pd.DataFrame(draws)) .. rst-class:: sphx-glr-script-out .. code-block:: none 0 1 2 3 4 5 6 7 8 9 0 0.5 0.25 0.75 0.125 0.625 0.5 0.75 0.25 0.875 0.375 .. GENERATED FROM PYTHON SOURCE LINES 145-147 As antithetic Halton draws may be correlated, it is a good idea to skip the first draws. .. GENERATED FROM PYTHON SOURCE LINES 147-152 .. code-block:: Python def uniform_halton(sample_size: int, number_of_draws: int) -> np.ndarray: """Function generating uniform draws for the antithetic draws""" return get_halton_draws(number_of_draws, sample_size, skip=100) .. GENERATED FROM PYTHON SOURCE LINES 153-156 .. code-block:: Python draws = get_antithetic(uniform_halton, sample_size=3, number_of_draws=10) display(pd.DataFrame(draws)) .. rst-class:: sphx-glr-script-out .. code-block:: none 0 1 2 3 4 5 0 0.648438 0.398438 0.898438 0.351562 0.601562 0.101562 1 0.085938 0.585938 0.335938 0.914062 0.414062 0.664062 2 0.835938 0.210938 0.710938 0.164062 0.789062 0.289062 3 0.460938 0.960938 0.054688 0.539062 0.039062 0.945312 4 0.554688 0.304688 0.804688 0.445312 0.695312 0.195312 .. GENERATED FROM PYTHON SOURCE LINES 157-159 Normal draws ------------ .. GENERATED FROM PYTHON SOURCE LINES 161-164 Generate pseudo-random numbers from a normal distribution N(0,1) using the Algorithm AS241 Appl. Statist. (1988) Vol. 37, No. 3 by Wichura .. GENERATED FROM PYTHON SOURCE LINES 164-167 .. code-block:: Python draws = get_normal_wichura_draws(sample_size=3, number_of_draws=10) display(pd.DataFrame(draws)) .. rst-class:: sphx-glr-script-out .. code-block:: none 0 1 2 ... 7 8 9 0 0.468384 0.309445 -0.727051 ... -0.898517 1.043511 -0.527998 1 1.928242 0.392652 -1.698057 ... 0.757420 -0.111766 -0.253738 2 -1.628487 0.809681 -0.477319 ... 1.831441 -1.492897 0.730499 [3 rows x 10 columns] .. GENERATED FROM PYTHON SOURCE LINES 168-170 The antithetic version actually generates half of the draws and complete them with their antithetic version .. GENERATED FROM PYTHON SOURCE LINES 170-173 .. code-block:: Python draws = get_normal_wichura_draws(sample_size=3, number_of_draws=10, antithetic=True) display(pd.DataFrame(draws)) .. rst-class:: sphx-glr-script-out .. code-block:: none 0 1 2 ... 7 8 9 0 -0.397450 -0.397369 1.096720 ... -1.096720 0.516517 -0.252910 1 -0.318315 0.481563 0.992685 ... -0.992685 -0.364958 -0.601621 2 -0.086190 0.780599 -0.178448 ... 0.178448 -0.164590 0.035292 [3 rows x 10 columns] .. GENERATED FROM PYTHON SOURCE LINES 174-178 The user can provide her own series of U[0,1] draws. In this example, we use the MLHS procedure to generate these draws. Note that, if the antithetic version is used, only half of the requested draws must be provided. .. GENERATED FROM PYTHON SOURCE LINES 178-181 .. code-block:: Python my_unif = get_latin_hypercube_draws(sample_size=3, number_of_draws=5) display(pd.DataFrame(my_unif)) .. rst-class:: sphx-glr-script-out .. code-block:: none 0 1 2 3 4 0 0.730781 0.974142 0.544797 0.090617 0.654064 1 0.528956 0.221999 0.009099 0.420511 0.877654 2 0.154954 0.848118 0.760657 0.335545 0.326175 .. GENERATED FROM PYTHON SOURCE LINES 182-187 .. code-block:: Python draws = get_normal_wichura_draws( sample_size=3, number_of_draws=10, uniform_numbers=my_unif, antithetic=True ) display(pd.DataFrame(draws)) .. rst-class:: sphx-glr-script-out .. code-block:: none 0 1 2 ... 7 8 9 0 0.615176 1.945487 0.112528 ... -0.112528 1.336963 -0.396315 1 0.072645 -0.765461 -2.361127 ... 2.361127 0.200585 -1.163339 2 -1.015414 1.028396 0.708416 ... -0.708416 0.424651 0.450501 [3 rows x 10 columns] .. GENERATED FROM PYTHON SOURCE LINES 188-189 The same with Halton draws. .. GENERATED FROM PYTHON SOURCE LINES 189-192 .. code-block:: Python my_unif = get_halton_draws(sample_size=2, number_of_draws=5, base=3, skip=10) display(pd.DataFrame(my_unif)) .. rst-class:: sphx-glr-script-out .. code-block:: none 0 1 2 3 4 0 0.703704 0.148148 0.481481 0.814815 0.259259 1 0.592593 0.925926 0.074074 0.407407 0.740741 .. GENERATED FROM PYTHON SOURCE LINES 193-198 .. code-block:: Python draws = get_normal_wichura_draws( number_of_draws=10, sample_size=2, uniform_numbers=my_unif, antithetic=True ) display(pd.DataFrame(draws)) .. rst-class:: sphx-glr-script-out .. code-block:: none 0 1 2 ... 7 8 9 0 0.535083 -1.044409 -0.046436 ... 0.046436 -0.895780 0.645631 1 0.234219 1.446104 -1.446104 ... 1.446104 0.234219 -0.645631 [2 rows x 10 columns] .. GENERATED FROM PYTHON SOURCE LINES 199-200 Biogeme provides a list of native draws .. GENERATED FROM PYTHON SOURCE LINES 200-204 .. code-block:: Python the_description = description_of_native_draws() for name, description in the_description.items(): print(f'{name}: {description}') .. rst-class:: sphx-glr-script-out .. code-block:: none UNIFORM: Uniform U[0, 1] UNIFORM_ANTI: Antithetic uniform U[0, 1] UNIFORM_HALTON2: Halton draws with base 2, skipping the first 10 UNIFORM_HALTON3: Halton draws with base 3, skipping the first 10 UNIFORM_HALTON5: Halton draws with base 5, skipping the first 10 UNIFORM_MLHS: Modified Latin Hypercube Sampling on [0, 1] UNIFORM_MLHS_ANTI: Antithetic Modified Latin Hypercube Sampling on [0, 1] UNIFORMSYM: Uniform U[-1, 1] UNIFORMSYM_ANTI: Antithetic uniform U[-1, 1] UNIFORMSYM_HALTON2: Halton draws on [-1, 1] with base 2, skipping the first 10 UNIFORMSYM_HALTON3: Halton draws on [-1, 1] with base 3, skipping the first 10 UNIFORMSYM_HALTON5: Halton draws on [-1, 1] with base 5, skipping the first 10 UNIFORMSYM_MLHS: Modified Latin Hypercube Sampling on [-1, 1] UNIFORMSYM_MLHS_ANTI: Antithetic Modified Latin Hypercube Sampling on [-1, 1] NORMAL: Normal N(0, 1) draws NORMAL_ANTI: Antithetic normal draws NORMAL_HALTON2: Normal draws from Halton base 2 sequence NORMAL_HALTON3: Normal draws from Halton base 3 sequence NORMAL_HALTON5: Normal draws from Halton base 5 sequence NORMAL_MLHS: Normal draws from Modified Latin Hypercube Sampling NORMAL_MLHS_ANTI: Antithetic normal draws from Modified Latin Hypercube Sampling .. GENERATED FROM PYTHON SOURCE LINES 205-214 .. code-block:: Python draw_type = 'NORMAL_HALTON2' the_native_draws = native_random_number_generators the_generator = the_native_draws[draw_type].generator draws = the_generator( sample_size=2, number_of_draws=10, ) print(f'Draws of type {draw_type}') display(pd.DataFrame(draws)) .. rst-class:: sphx-glr-script-out .. code-block:: none Draws of type NORMAL_HALTON2 0 1 2 ... 7 8 9 0 0.887147 -0.887147 0.488776 ... -0.579132 0.776422 -1.009990 1 0.402250 -0.237202 1.318011 ... -0.776422 0.579132 -0.078412 [2 rows x 10 columns] .. rst-class:: sphx-glr-timing **Total running time of the script:** (0 minutes 0.053 seconds) .. _sphx_glr_download_auto_examples_programmers_plot_draws.py: .. only:: html .. container:: sphx-glr-footer sphx-glr-footer-example .. container:: sphx-glr-download sphx-glr-download-jupyter :download:`Download Jupyter notebook: plot_draws.ipynb ` .. container:: sphx-glr-download sphx-glr-download-python :download:`Download Python source code: plot_draws.py ` .. container:: sphx-glr-download sphx-glr-download-zip :download:`Download zipped: plot_draws.zip ` .. only:: html .. rst-class:: sphx-glr-signature `Gallery generated by Sphinx-Gallery `_