varstool.sampling package

general sampling functions

This module contains 6 different sampling methods, that are: 1. halton sequence 2. lating hypercube sampling (lhs) 3. progressive lating hypercube sampling (plhs) 4. sobol sequence 5. symetrical latin hypercube sampling (symlhs) 6. Generalized Star‐Based (gSTAR) Sampling 7. STAR sampling (starvars)

halton(sp: int, params: int, seed: Optional[int] = None, scramble: bool = True, skip: int = 1000, leap: int = 101) → ndarray

Generate quasi-random halton sequence numbers.

This function generates (scrambled) quasi-random halton sequence. In brief, it generalizes the Van der Corput’s sequence for multiple dimensions. The Halton sequence uses the base-two Van der Corput sequence for the first dimension, base-three for its second and base-\(n\) for its \(n^{th}\)-dimension.

Parameters

  • sp (int) – the number of sampling points

  • params (int) – the number of parameters/factors/variables

  • seed (int or None, optional) – seed number for randomization, defaults to None

  • scramble (bool, optional) – scrambling flag, defaults to False

  • skip (int, optional) – the number of points to skip from the beginning of the sequence, defaults to 1000

  • leap (int, optional) – the interval of picking values, defaults to 101

Returns

halton_seq – the halton sequence array

Return type

array_like

References

1

scipy.stats._qmc module

2

scipy.stats._sobol module

3

Halton, J.H. On the efficiency of certain quasi-random sequences of points in evaluating multi-dimensional integrals. Numer. Math. 2, 84–90 (1960). https://doi.org/10.1007/BF01386213

4

Owen, A.B. A randomized Halton algorithm in R (2017). arXiv:1706.02808v2

lhs(sp=None, params=1, seed=None, criterion=None, iterations=None)

Generate a latin-hypercube design.

Parameters

  • n (int) – the number of factors to generate samples for

  • samples (int) – the number of samples to generate for each factor, defaults to n

  • criterion (str) – allowable values are center or c, maximin or m, centermaximin or cm, and correlation or corr. If no value given, the design is simply randomized.

  • iterations (int) – The number of iterations in the maximin and correlations algorithms, default to 5

Returns

H – An n-by-samples design matrix that has been normalized so factor values are uniformly spaced between zero and one.

Return type

array_like

Example

A 3-factor design (defaults to 3 samples):

>>> lhs(3)
array([[ 0.40069325,  0.08118402,  0.69763298],
       [ 0.19524568,  0.41383587,  0.29947106],
       [ 0.85341601,  0.75460699,  0.360024  ]])

A 4-factor design with 6 samples:

>>> lhs(4, samples=6)
array([[ 0.27226812,  0.02811327,  0.62792445,  0.91988196],
       [ 0.76945538,  0.43501682,  0.01107457,  0.09583358],
       [ 0.45702981,  0.76073773,  0.90245401,  0.18773015],
       [ 0.99342115,  0.85814198,  0.16996665,  0.65069309],
       [ 0.63092013,  0.22148567,  0.33616859,  0.36332478],
       [ 0.05276917,  0.5819198 ,  0.67194243,  0.78703262]])

A 2-factor design with 5 centered samples:

>>> lhs(2, samples=5, criterion='center')
array([[ 0.3,  0.5],
       [ 0.7,  0.9],
       [ 0.1,  0.3],
       [ 0.9,  0.1],
       [ 0.5,  0.7]])

A 3-factor design with 4 samples where the minimum distance between all samples has been maximized:

>>> lhs(3, samples=4, criterion='maximin')
array([[ 0.02642564,  0.55576963,  0.50261649],
       [ 0.51606589,  0.88933259,  0.34040838],
       [ 0.98431735,  0.0380364 ,  0.01621717],
       [ 0.40414671,  0.33339132,  0.84845707]])

A 4-factor design with 5 samples where the samples are as uncorrelated as possible (within 10 iterations):

>>> lhs(4, samples=5, criterion='correlate', iterations=10)
plhs(sp: int, params: int, slices: int, seed: Optional[int] = None, iterations: int = 10, criterion: str = 'maximin') → Tuple[ndarray, ndarray]

Optimize SLHS samples based on [1] and [2]

This function is a Progressive Latin Hypercube Sampling (PLHS) using an optimal Sliced Lating Hypercube Sampling design (SLHS) in the frame of a greedy approach.

Parameters

  • sp (int) – number of sampling points

  • params (int) – number of parameters/factors/variables

  • slices (int) – the number of slices

  • seed (int, optional) – seed number for randomization

  • iterations (int, optional) – number of iterations, defaults to 10

  • criterion (str, optional) – the criterion for assessing the quality of sample points the available options are: ‘maximin’ and ‘correlation’, defaults to 'maximin'

Returns

plhs_sample_x – the final slhs sample array based on criterion

Return type

array_like

References

1

Ba, S., Myers, W.R., Brenneman, W.A., 2015. Optimal sliced Latin hypercube designs. Technometrics 57 (4), 479e487. http://dx.doi.org/10.1080/00401706.2014.957867

2

Sheikholeslami, R., & Razavi, S. (2017). Progressive Latin Hypercube Sampling: An efficient approach for robust sampling-based analysis of environmental models. Environmental modelling & software, 93, 109-126

sobol_sequence(sp: int, params: int, seed: Optional[int] = None, scramble: bool = True, skip: int = 1000, leap: int = 101) → ndarray

Sobol’ sequences are low-discrepancy, quasi-random numbers. The code is taken from the scipy dev-1.7 [1].

Parameters

  • sp (int) – the number of sampling points

  • params (int) – the number of parameters/factors/variables

  • seed (int, optional) – randomization seed number, defaults to None

  • scramble (bool, optional) – scrambling the produced array, defaults to True

  • skip (int, optional) – the number of points to skip, defaults to 1000

  • leap (int, optional) – the interval of picking values, defaults to 101

Returns

sobol_seq – the sobol sequence

Return type

array_like

Notes

There are many versions of Sobol’ sequences depending on their “direction numbers”. This code uses direction numbers from [4]. Hence, the maximum number of dimension is 21201. The direction numbers have been precomputed with search criterion 6 and can be retrieved at https://web.maths.unsw.edu.au/~fkuo/sobol/

References

1

scipy.stats._qmcs

2

scipy.stats.qmc.Sobol

3

I. M. Sobol. The distribution of points in a cube and the accurate evaluation of integrals. Zh. Vychisl. Mat. i Mat. Phys., 7:784-802, 1967.

4

S. Joe and F. Y. Kuo. Constructing sobol sequences with better two-dimensional projections. SIAM Journal on Scientific Computing, 30(5):2635-2654, 2008.

symlhs(sp: int, params: int, seed: Optional[int] = None, criterion: str = 'maximin', iterations: int = 10) → ndarray

Generate symmetrical LHS of sp datapoints in the params-dimensional hypercube of [0,1]; developed based on [1].

Parameters

  • sp (int) – the number of sampling points

  • params (int) – the number of parameters/variables/factors

  • seed (int or None) – the seed number for randomization, defaults to None

  • criterion (str, optional) – method for evaluation of the generated sampled array, options are 'maximin' and 'correlation', defaults to 'maximin'

  • iterations (int, optional) – number of iterations to get the optimal sampled array, defaults to 10

Returns

symlhs_sample – the returned symmetrical LHS sampled array

Return type

array_like

References

1

K.Q. Ye, W. Li, A. Sudjianto Algorithmic construction of optimal symmetric Latin hypercube designs J. Stat. Plan. Infer., 90 (1) (2000), pp. 145-159, doi: 10.1016/S0378-3758(00)00105-1

generalized star-based (gSTAR) sampling functions

g_star(parameters: Dict[Union[str, int], Tuple[Union[float, str]]], star_centres: ndarray, seed: int, sampler: str, slice_size: int, num_stars: int, corr_mat: ndarray, num_dir_samples: int, num_factors: int, report_verbose: bool, fictive_mat_flag: bool, dist_sample_file: Optional[str] = None) → Tuple[Union[DataFrame, Series], ndarray, ndarray]

This function generates a Pandas Dataframe containing ‘’star_points’’ based on [3]

Parameters

  • parameters (dictionary) – dictionary containing parameter names, and their attributes

  • seed (int) – the seed number used in generating star points

  • num_stars (int) – number of star samples

  • corr_mat (np.array) – correlation matrix

  • num_dir_samples (int) – number of directional samples per star point

  • num_factors (int) – number of factors/parameters in model

  • report_verbose (boolean) – if True will use a loading bar when generating stars, does nothing if False

  • fictive_mat_flag (boolean) – if False will use correlation matrix as fictive matrix

  • dist_sample_file (str) – file name of file containing custom distribution data

Returns

  • star_points_df (array_like) – Pandas DataFrame containing the GVARS star points

  • x (array_like) – numpy array containing correlated star centres

  • cov_mat (array_like) – numpy array containing fictive correlation matrix

References

1

Razavi, S., & Gupta, H. V. (2016). A new framework for comprehensive, robust, and efficient global sensitivity analysis: 1. Theory. Water Resources Research, 52(1), 423-439. doi: 10.1002/2015WR017558

2

Razavi, S., & Gupta, H. V. (2016). A new framework for comprehensive, robust, and efficient global sensitivity analysis: 1. Application. Water Resources Research, 52(1), 423-439. doi: 10.1002/2015WR017559

3

Razavi, S., & Do, C. N. (2020). Correlation Effects? A Major but Often Neglected Component in Sensitivity and Uncertainty Analysis. Water Resources Research, 56(3). doi: /10.1029/2019WR025436

STAR sampling (starvars) functions

rangef(start, stop, step, fround=10)

Yields sequence of numbers from start (inclusive) to stop (inclusive) by step (increment) with rounding set to n digits.

Parameters

  • start (float or int) – start of sequence

  • stop (float or int) – end of sequence

  • step (float or int) – int or float increment (e.g. 1 or 0.001)

  • fround (int) – float rounding, n decimal places, defaults to 5

Yields

  • int – yielding the next value of the range sequence

  • Source

  • ——

  • The code is taken from the following link, thanks to Goran B.

  • https (//stackoverflow.com/a/49059292/5188208)

star(star_centres, delta_h: float = 0.1, parameters: list = [], rettype: str = 'dict', precision: int = 10) → ndarray

STAR sampling algorithm

This function generates star_points based on [1] for each sample set (i.e., each row consisting of star_centres). star_centres are the points along which in each direction the star_points are generated. The resolution of sampling is \(\Delta h\) (delta_h). This appraoch is a structured sampling straregy; read more in [2] and [3].

Parameters

  • star_centres (array_like) – the 2d array (n, m) containing sample sets, n is the number of sample sets and m is the number of parameters/factors/ variables

  • delta_h (float, optional) – sampling resolution, defaults to 0.1

  • parameters (list) – parameter names

  • rettype (str, optional) – 'dict' or 'dataframe', defaults to 'dict'

  • precision (int, optional) – the number of digits after the precision point, defaults to 10

Returns

star_points – np.array of star points, each element of this 4d array is a 3d np.array with each 2d array containing star points along each parameter/factor/variable.

Return type

array_like

References

1

Razavi, S., Sheikholeslami, R., Gupta, H. V., & Haghnegahdar, A. (2019). VARS-TOOL: A toolbox for comprehensive, efficient, and robust sensitivity and uncertainty analysis. Environmental modelling & software, 112, 95-107. doi: 10.1016/j.envsoft.2018.10.005

2

Razavi, S., & Gupta, H. V. (2016). A new framework for comprehensive, robust, and efficient global sensitivity analysis: 1. Theory. Water Resources Research, 52(1), 423-439. doi: 10.1002/2015WR017558

3

Razavi, S., & Gupta, H. V. (2016). A new framework for comprehensive, robust, and efficient global sensitivity analysis: 2. Application. Water Resources Research, 52(1), 423-439. doi: 10.1002/2015WR017559