Note
Go to the end to download the full example code.
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
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
Version of Biogeme.
print(get_text())
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)
We set the seed so that the outcome of random operations is always the same.
np.random.seed(90267)
Uniform draws¶
Uniform [0,1]. The output is transformed into a data frame just for the display.
draws = get_uniform(sample_size=3, number_of_draws=10, symmetric=False)
display(pd.DataFrame(draws))
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]
draws = get_uniform(sample_size=3, number_of_draws=10, symmetric=True)
display(pd.DataFrame(draws))
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]
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.
latin_hypercube = get_latin_hypercube_draws(sample_size=3, number_of_draws=10)
display(pd.DataFrame(latin_hypercube))
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]
The same method can be used to generate draws from U[-1,1]
latin_hypercube = get_latin_hypercube_draws(
sample_size=5, number_of_draws=10, symmetric=True
)
display(pd.DataFrame(latin_hypercube))
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]
The user can provide her own series of U[0,1] draws.
my_unif = np.random.uniform(size=30)
display(pd.DataFrame(my_unif))
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
latin_hypercube = get_latin_hypercube_draws(
sample_size=3, number_of_draws=10, symmetric=False, uniform_numbers=my_unif
)
display(pd.DataFrame(latin_hypercube))
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]
The uniform draws can also be arranged in a two-dimension array
my_unif = get_uniform(sample_size=3, number_of_draws=10)
display(pd.DataFrame(my_unif))
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]
latin_hypercube = get_latin_hypercube_draws(
sample_size=3, number_of_draws=10, uniform_numbers=my_unif
)
display(pd.DataFrame(latin_hypercube))
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]
Halton draws¶
One Halton sequence.
halton = get_halton_draws(sample_size=2, number_of_draws=10, base=3)
display(pd.DataFrame(halton))
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]
Several Halton sequences.
halton = get_halton_draws(sample_size=3, number_of_draws=10)
display(pd.DataFrame(halton))
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]
Shuffled Halton sequences.
halton = get_halton_draws(sample_size=3, number_of_draws=10, shuffled=True)
display(pd.DataFrame(halton))
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]
The above sequences were generated using the default base: 2. It is possible to generate sequences using different prime numbers.
halton = get_halton_draws(sample_size=1, number_of_draws=10, base=3)
display(pd.DataFrame(halton))
0 1 2 ... 7 8 9
0 0.333333 0.666667 0.111111 ... 0.888889 0.037037 0.37037
[1 rows x 10 columns]
It is also possible to skip the first items of the sequence. This is desirable in the context of Monte-Carlo integration.
halton = get_halton_draws(sample_size=1, number_of_draws=10, base=3, skip=10)
display(pd.DataFrame(halton))
0 1 2 ... 7 8 9
0 0.703704 0.148148 0.481481 ... 0.074074 0.407407 0.740741
[1 rows x 10 columns]
Antithetic draws¶
Antithetic draws can be generated from any function generating uniform draws.
draws = get_antithetic(get_uniform, sample_size=3, number_of_draws=10)
display(pd.DataFrame(draws))
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]
Antithetic MLHS
draws = get_antithetic(get_latin_hypercube_draws, sample_size=3, number_of_draws=10)
display(pd.DataFrame(draws))
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]
Antithetic Halton.
draws = get_antithetic(get_halton_draws, sample_size=1, number_of_draws=10)
display(pd.DataFrame(draws))
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
As antithetic Halton draws may be correlated, it is a good idea to skip the first draws.
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)
draws = get_antithetic(uniform_halton, sample_size=3, number_of_draws=10)
display(pd.DataFrame(draws))
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
Normal draws¶
Generate pseudo-random numbers from a normal distribution N(0,1) using the Algorithm AS241 Appl. Statist. (1988) Vol. 37, No. 3 by Wichura
draws = get_normal_wichura_draws(sample_size=3, number_of_draws=10)
display(pd.DataFrame(draws))
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]
The antithetic version actually generates half of the draws and complete them with their antithetic version
draws = get_normal_wichura_draws(sample_size=3, number_of_draws=10, antithetic=True)
display(pd.DataFrame(draws))
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]
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.
my_unif = get_latin_hypercube_draws(sample_size=3, number_of_draws=5)
display(pd.DataFrame(my_unif))
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
draws = get_normal_wichura_draws(
sample_size=3, number_of_draws=10, uniform_numbers=my_unif, antithetic=True
)
display(pd.DataFrame(draws))
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]
The same with Halton draws.
my_unif = get_halton_draws(sample_size=2, number_of_draws=5, base=3, skip=10)
display(pd.DataFrame(my_unif))
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
draws = get_normal_wichura_draws(
number_of_draws=10, sample_size=2, uniform_numbers=my_unif, antithetic=True
)
display(pd.DataFrame(draws))
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]
Biogeme provides a list of native draws
the_description = description_of_native_draws()
for name, description in the_description.items():
print(f'{name}: {description}')
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
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))
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]
Total running time of the script: (0 minutes 0.053 seconds)