biogeme.draws module

Generation of various types of draws.

author:: Michel Bierlaire
date:: Tue Jun 18 19:05:13 2019

biogeme.draws.getAntithetic(uniform_draws, sample_size, number_of_draws)[source]

Warning

This function is deprecated. Use get_antithetic() instead.

Return type:

ndarray

Parameters:

uniform_draws (Callable[[int, int], ndarray])
sample_size (int)
number_of_draws (int)

biogeme.draws.getHaltonDraws(sample_size, number_of_draws, symmetric=False, base=2, skip=0, shuffled=False)[source]

Warning

This function is deprecated. Use get_halton_draws() instead.

Parameters:

sample_size (int)
number_of_draws (int)
symmetric (bool)
base (int)
skip (int)
shuffled (bool)

biogeme.draws.getLatinHypercubeDraws(sample_size, number_of_draws, symmetric=False, uniformNumbers=None)[source]

Warning

This function is deprecated. Use get_latin_hypercube_draws() instead.

Parameters:

sample_size (int)
number_of_draws (int)
symmetric (bool)

biogeme.draws.getNormalWichuraDraws(sample_size, number_of_draws, uniform_numbers=None, antithetic=False)[source]

Warning

This function is deprecated. Use get_normal_wichura_draws() instead.

Parameters:

sample_size (int)
number_of_draws (int)
uniform_numbers (ndarray | None)
antithetic (bool)

biogeme.draws.getUniform(sample_size, number_of_draws, symmetric=False)[source]

Warning

This function is deprecated. Use get_uniform() instead.

Parameters:

sample_size (int)
number_of_draws (int)
symmetric (bool)

biogeme.draws.get_antithetic(uniform_draws, sample_size, number_of_draws)[source]

Returns antithetic uniform draws

Parameters:

uniform_draws (function) – function taking two arguments (sample_size, number_of_draws) and returning U[0, 1] draws
sample_size (int) – number of observations for which draws must be generated. If None, a one dimensional array will be generated. If it has a values k, then k series of draws will be generated
number_of_draws (int) – number of draws to generate.

Returns:

numpy array with the antithetic draws

Return type:

numpy.array

Example:

draws = dr.getAntithetic(dr.getUniform,
                         sample_size=3,
                         number_of_draws=10)

array([[0.48592363, 0.13648133, 0.35925946, 0.32431338, 0.32997936,
        0.51407637, 0.86351867, 0.64074054, 0.67568662, 0.67002064],
       [0.89261997, 0.0331808 , 0.30767182, 0.93433648, 0.17196124,
        0.10738003, 0.9668192 , 0.69232818, 0.06566352, 0.82803876],
       [0.81095587, 0.96171364, 0.40984817, 0.72177258, 0.16481096,
        0.18904413, 0.03828636, 0.59015183, 0.27822742, 0.83518904]])

biogeme.draws.get_halton_draws(sample_size, number_of_draws, symmetric=False, base=2, skip=0, shuffled=False)[source]

Generate Halton draws. Implementation by Cristian Arteaga, University of Nevada Las Vegas,

Parameters:

sample_size (int) – number of observations for which draws must be generated. If None, a one dimensional array will be generated. If it has a values k, then k series of draws will be generated
number_of_draws (int) – number of draws to generate.
symmetric (bool) – if True, draws from [-1: 1] are generated. If False, draws from [0: 1] are generated. Default: False
base (int) – generate Halton draws for a given basis. Ideally, it should be a prime number. Default: 2.
skip (int) – the number of elements of the sequence to be discarded.
shuffled (bool) – if True, each series is shuffled

Returns:

numpy array with the draws

Return type:

numpy.array

Example:

halton = dr.getHaltonDraws(sample_size=2, number_of_draws=10, base=3)
array([[0.33333333, 0.66666667, 0.11111111, 0.44444444, 0.77777778,
        0.22222222, 0.55555556, 0.88888889, 0.03703704, 0.37037037],
       [0.7037037 , 0.14814815, 0.48148148, 0.81481481, 0.25925926,
        0.59259259, 0.92592593, 0.07407407, 0.40740741, 0.74074074]])

Raises:

BiogemeError – if the number of draws is not positive.
BiogemeError – if the sample size is not positive.

Parameters:

sample_size (int)
number_of_draws (int)
symmetric (bool)
base (int)
skip (int)
shuffled (bool)

Return type:

ndarray

biogeme.draws.get_latin_hypercube_draws(sample_size, number_of_draws, symmetric=False, uniform_numbers=None)[source]

Implementation of the Modified Latin Hypercube Sampling proposed by Hess et al., (2006).

Parameters:

sample_size (int) – number of observations for which draws must be generated. If None, a one dimensional array will be generated. If it has a values k, then k series of draws will be generated
number_of_draws (int) – number of draws to generate.
symmetric (bool) – if True, draws from [-1: 1] are generated. If False, draws from [0: 1] are generated. Default: False
uniform_numbers (numpy.array) – numpy with uniformly distributed numbers. If None, the numpy uniform number generator is used.

Returns:

numpy array with the draws

Return type:

numpy.array

Example:

latinHypercube = dr.getLatinHypercubeDraws(sample_size=3,
                                           number_of_draws=10)
array([[0.43362897, 0.5275741 , 0.09215663, 0.94056236, 0.34376868,
        0.87195551, 0.41495219, 0.71736691, 0.23198736, 0.145561  ],
       [0.30520544, 0.78082964, 0.83591146, 0.2733167 , 0.53890906,
        0.61607469, 0.00699715, 0.17179441, 0.7557228 , 0.39733102],
       [0.49676864, 0.67073483, 0.9788854 , 0.5726069 , 0.11894558,
        0.05515471, 0.2640275 , 0.82093696, 0.92034628, 0.64866597]])

Raises:

BiogemeError – if the number of draws is not positive.
BiogemeError – if the sample size is not positive.
BiogemeError – if the number of uniform draws is inconsistent.

Parameters:

sample_size (int)
number_of_draws (int)
symmetric (bool)
uniform_numbers (ndarray | None)

Return type:

ndarray

biogeme.draws.get_normal_wichura_draws(sample_size, number_of_draws, uniform_numbers=None, antithetic=False)[source]

Generate pseudo-random numbers from a normal distribution N(0, 1)

It uses the Algorithm AS241 by Wichura (1988) which produces the normal deviate z corresponding to a given lower tail area of p; z is accurate to about 1 part in \(10^{16}\).

Parameters:

sample_size (int) – number of observations for which draws must be generated. If None, a one dimensional array will be generated. If it has a values k, then k series of draws will be generated
number_of_draws (int) – number of draws to generate.
uniform_numbers (numpy.array) – numpy with uniformly distributed numbers. If None, the numpy uniform number generator is used.
antithetic (bool) – if True, only half of the draws are actually generated, and the series are completed with their antithetic version.

Returns:

numpy array with the draws

Return type:

numpy.array

Example:

draws = dr.getNormalWichuraDraws(sample_size=3, number_of_draws=10)
array(
    [[ 0.52418458, -1.04344204, -2.11642482,  0.48257162, -2.67188279,
      -1.89993283,  0.28251041, -0.38424425,  1.53182226,  0.30651874],
     [-0.7937038 , -0.07884121, -0.91005616, -0.98855175,  1.09405753,
      -0.5997651 , -1.70785113,  1.57571384, -0.33208723, -1.03510102],
     [-0.13853654,  0.92595498, -0.80136586,  1.68454196,  0.9955927 ,
      -0.28615154,  2.10635541,  0.0436191 , -0.25417774,  0.01026933]]
)

Raises:

BiogemeError – if the number of draws is not positive.
BiogemeError – if the sample size is not positive.

Parameters:

sample_size (int)
number_of_draws (int)
uniform_numbers (ndarray | None)
antithetic (bool)

biogeme.draws.get_uniform(sample_size, number_of_draws, symmetric=False)[source]

Uniform [0, 1] or [-1, 1] numbers

Parameters:

sample_size (int) – number of observations for which draws must be generated. If None, a one dimensional array will be generated. If it has a values k, then k series of draws will be generated
number_of_draws (int) – number of draws to generate.
symmetric (bool) – if True, draws from [-1: 1] are generated. If False, draws from [0: 1] are generated. Default: False

Returns:

numpy array with the draws

Return type:

numpy.array

Example:

draws = dr.getUniform(sample_size=3, number_of_draws=10, symmetric=False)
array(
    [[0.13053817, 0.63892308, 0.55031567, 0.26347854, 0.16730932,
      0.77745367, 0.48283887, 0.84247501, 0.20550219, 0.02373537],
     [0.68935846, 0.03363595, 0.36006669, 0.26709364, 0.54907706,
      0.22492104, 0.2494399 , 0.17323209, 0.52370401, 0.54091257],
     [0.40310204, 0.89916711, 0.86065005, 0.94277699, 0.09077065,
      0.40107731, 0.22554722, 0.47693135, 0.14058265, 0.17397031]]
)

draws = dr.getUniform(sample_size=3, number_of_draws=10, symmetric=True)
array(
    [[ 0.74403237, -0.27995692,  0.33997421, -0.89405035, -0.129761  ,
       0.86593325,  0.30657422,  0.82435619,  0.498482  ,  0.24561616],
     [-0.48239607, -0.29257815, -0.98342034,  0.68392813, -0.25379429,
       0.49359859, -0.26459883,  0.14569724, -0.68860467, -0.40903446],
     [ 0.93251627, -0.85166912,  0.58096917,  0.39289882, -0.65088635,
       0.40114744, -0.61327161,  0.08900539, -0.20985417,  0.67542226]]
)

Raises:

BiogemeError – if the number of draws is not positive.
BiogemeError – if the sample size is not positive.

Parameters:

sample_size (int)
number_of_draws (int)
symmetric (bool)

Return type:

ndarray