Package documentation

class expandLHS.ExpandLHS(samples=None, *, N=None, P=None, **kwargs)

Class of the Latin Hypercube Sampling (LHS) Expansion algorithm.

The Latin Hypercube Sampling is a stratified sampling method that allows to generate N near-random samples in the P-dimensional hypercube [0, 1)^P. It is a space-filling sampling strategy that ensures the one-dimensional projection property, i.e. the samples are uniformly distributed in each one-dimension projection.

Given an initial LHS set of size N defined in the P-dimensional hypercube [0, 1)^P, this class expands the set adding new M samples. This procedure requires a new partition of the interval [0,1) in each dimension P that may result in loosing the LHS projection property. The case M = k * N, where k is a natural number, always preserves the LHS projection property. This code allows to compute a new metric D, with 0 < D <= 1, corresponding to the degree-of-LHS of a samples set, where D = 1 corresponds to a perfect LHS. This allows to quantify the impact of an epansion on the initial set. It is worth noticing that the degree does not depend on the sampling strategy, but only on the initial set and the new partition of the intervals.

Attributes:

Nint

Cardinality of the sample set.

Pint

Number of dimensions.

samplesnumpy.ndarray with shape (N, P)

Initial Latin Hypercube sample set.

Methods

_regridding([M, samples])	Regrid the Latin Hypercube samples by adding M new intervals in each dimension.
_count_samples([M, samples])	Count the number of samples in each of the (N + M) x P intervals.
_LHSinLHS_sampling(M, voids)	Generate new samples within the voids of the current sample set preserving as much as possible the properties of a Latin Hypercube.
_LHSinLHS_optimized(M, voids, criterion, ...)	Generate new samples within the voids of the current sample set preserving as much as possible the properties of a Latin Hypercube.
degree([M])	Compute the degree-of-LHS of the current sample set when expanded to size N + M, assuming M new samples will be generated.
optimal_expansion(radius[, verbose])	Find the optimal expansion size ---the expansion that has the higher degree-of-LHS in a given range.
__call__([M, seed, optimize, trials, tol])	Build the Latin Hypercube expansion of size M.

__call__(M=1, *, seed=None, optimize=None, trials=1000, tol=0.0001)

Build the Latin Hypercube expansion of size M.

The optional argument ‘optimize’ allows to find an optimal set of new samples with lower centered discrepancy (space filling metric) or higher geometric discrepancy (pairwise minimum distance). Both these metrics are implemented in Scipy.stats.qmc. The code produce a number of possible expansion equal to ‘trials’. It is not garanteed that the final sample will be the absolute minimum of the discrepancy or the absolute maximum of the geometric discrepancy for the given sample. The optimization through geometric discrepancy could fail if the minimum pairwise distance is set by the initial set.

Parameters:

Mint (optional)

Number of new samples to generate. Defaults to 1.

seedint | None (optional)

Seed for the random number generator. Defaults to None.

optimizestr | None (optional)

Optimization criterion, the available options are centered discrepancy and geometric discrepancy

trialsint (optional)

number of trials for the optimal expansion set. Defoult to 1000.

tolfloat (optional)

Tolerance for the optimization. Defaults to 1e-4.

Returns:

expansionnumpy.ndarray(N + M, P)

Expanded Latin Hypercube sample set.

degree(M=1)

Compute the degree-of-LHS of the current sample set when expanded to size N + M, assuming M new samples will be generated. If M = 0, compute the degree of the initial set.

Parameters:

Mint

Number of new intervals to add. Defaults to 1.

Returns:

lhs_degreefloat

Degree of the Latin Hypercube Sampling, with 0 < D <= 1. A perfect Latin Hypercube has degree D = 1.

optimal_expansion(radius, verbose=False)

Find the optimal expansion size —the expansion that has the higher degree-of-LHS in a given range.

Parameters:

radiusint | (int, int)

Range of values to consider for the expansion. If a single value is provided, it is interpreted as [1, upper bound] If a tuple is provided, it is interpreted as [lower bound, upper bound]. Both the lower bound and the upper bound are included.

verbosebool

If False return the expansion size with the highest degree, if True returns all the expansion sizes within radius. Defaults to False.

Returns:

expansionslist of tuples(int, float) or float

List of expansion sizes and their corresponding degree-of-LHS. If verbose is True, returns a list of tuples with the expansion size and the corresponding degree-of-LHS. The tuple with expansion size equal 0 is the degree of the current set (=1 for a perfect Latin Hypercube). If verbose is False, returns the expansion size with the highest degree-of-LHS.