Sampling

class_e.sampling

LatinHyperCube

LatinHyperCube(
    param_ranges: Iterable[Parameter],
    seed: int | None = None,
)

sample

sample(n: int) -> Tuple[np.ndarray, List[str]]

Draw n samples and map to parameter ranges.

Returns:

Name	Type	Description
samples	(n, d) array
names	list[str]

LatinHyperSphere

LatinHyperSphere(
    param_ranges: Iterable[Parameter],
    seed: int | None = None,
    sampling_type: str = "surface",
)

Latin Hyper Sphere sampler that generates points uniformly distributed on the surface of a hypersphere, then maps them to parameter space while maintaining Latin Hypercube stratification properties.

This is useful when parameters have natural correlations or when you want to avoid extreme parameter combinations that may be unphysical.

Initialize the Latin Hyper Sphere sampler.

Parameters:

Name	Type	Description	Default
param_ranges	Iterable[Parameter]	Parameter ranges to sample from	required
seed	int	Random seed for reproducibility	None
sampling_type	str	Type of sampling: 'surface' (on sphere surface) or 'volume' (within sphere)	'surface'

sample

sample(n: int) -> Tuple[np.ndarray, List[str]]

Draw n samples from the hypersphere and map to parameter ranges.

Returns:

Name	Type	Description
samples	(n, d) array	Parameter samples
names	list[str]	Parameter names

dict_to_ranges staticmethod

dict_to_ranges(
    bounds: Dict[str, Tuple[float, float]],
) -> List[Parameter]

Convert dictionary of bounds to list of Parameter objects.

CovarianceAwareLatinHyperCube

CovarianceAwareLatinHyperCube(
    param_ranges: Iterable[Parameter],
    covariance: ndarray,
    mean: ndarray | None = None,
    n_sigma: float = 3.0,
    seed: int | None = None,
    clip_to_bounds: bool = True,
)

Latin Hypercube sampler that uses a covariance matrix from previous MCMC runs to generate samples that respect parameter correlations and uncertainties.

This is particularly useful for: - Training emulators focused on observationally relevant parameter regions - Respecting known parameter degeneracies (e.g., from Planck) - Efficient sampling in high-dimensional spaces - Avoiding unphysical parameter combinations

Initialize covariance-aware sampler.

Parameters:

Name	Type	Description	Default
param_ranges	Iterable[Parameter]	Parameter ranges (used for bounds and parameter names)	required
covariance	(ndarray, shape(d, d))	Covariance matrix from MCMC runs	required
mean	(ndarray, shape(d))	Mean/best-fit parameter values. If None, uses center of param_ranges	None
n_sigma	float	Sample within \(n_\sigma\) standard deviations	3.0
seed	int	Random seed for reproducibility	None
clip_to_bounds	bool	Whether to clip samples to stay within parameter bounds	True

sample

sample(n: int) -> Tuple[np.ndarray, List[str]]

Draw n correlated samples using the covariance matrix.

Returns:

Name	Type	Description
samples	(n, d) array	Parameter samples respecting covariance structure
names	list[str]	Parameter names

get_principal_components

get_principal_components() -> Tuple[np.ndarray, np.ndarray]

Get principal components (eigenvectors) and their uncertainties (\(\sqrt{\lambda_i}\), the square roots of the eigenvalues).

Returns:

Name	Type	Description
eigenvalues	(ndarray, shape(d))	Eigenvalues of covariance matrix (variances along principal axes)
eigenvectors	(ndarray, shape(d, d))	Eigenvectors (principal axes), each column is an eigenvector

get_correlation_matrix

get_correlation_matrix() -> np.ndarray

Convert covariance to correlation matrix.

Returns:

Name	Type	Description
correlation	(ndarray, shape(d, d))	Correlation matrix with values in [-1, 1]

dict_to_ranges staticmethod

dict_to_ranges(
    bounds: Dict[str, Tuple[float, float]],
) -> List[Parameter]

Convert dictionary of bounds to list of Parameter objects.

Sobol

Sobol(
    param_ranges: Iterable[Parameter],
    seed: int | None = None,
    scramble: bool = True,
)

Scrambled Sobol sequence sampler.

Balance properties of the sequence only hold for N = 2^m samples; other N are allowed but emit a warning.

sample

sample(n: int) -> Tuple[np.ndarray, List[str]]

Draw n samples and map to parameter ranges.

create_sampler

create_sampler(
    param_ranges: Iterable[Parameter],
    seed: int | None = None,
    method: str = "lhc",
    **kwargs,
) -> (
    LatinHyperCube
    | LatinHyperSphere
    | CovarianceAwareLatinHyperCube
    | Sobol
)

Factory function to create LHC, LHS, Sobol, or covariance-aware sampler.

Parameters:

Name	Type	Description	Default
param_ranges	Iterable[ParamRange]	Parameter ranges to sample from	required
seed	int	Random seed for reproducibility	None
method	str	Sampling method: - 'lhc': Latin Hypercube - 'lhs': Latin Hyper Sphere - 'cov': Covariance-aware Latin Hypercube - 'sobol': Scrambled Sobol sequence	'lhc'
**kwargs		Additional arguments passed to the sampler: - For 'lhs': sampling_type ('surface' or 'volume') - For 'cov': covariance, mean, n_sigma, clip_to_bounds	{}

Returns:

Name	Type	Description
sampler	LatinHypercubeSampler, LatinHyperSphereSampler, or CovarianceAwareLatinHypercubeSampler