metaheuristic_designer.operators.operator_functions.probability_distributions module

class Distribution(rng=None)

Bases: ABC

Abstract base class for all probability distributions.

Defines the interface that every distribution must implement: a sample method to generate random variates and an optional estimate_parameters method to compute heuristic parameters from data.

Methods

estimate_parameters(data_matrix, **kwargs)	Compute heuristic distribution parameters from a data matrix.
sample(shape, rng)	Draw random samples from the distribution.

Parameters:

rng (int | Generator | None)

abstract sample(shape, rng)

Draw random samples from the distribution.

Return type:

ndarray[tuple[int, ...], floating] | ndarray[tuple[int, ...], integer] | ndarray[tuple[int, ...], uint8 | bool]

Parameters:

shapetuple

Shape of the requested output array.

rngRNGLike

Random number generator.

Returns:

TensorLike

Array of samples with the requested shape.

Parameters:

• shape (tuple)

• rng (int | Generator)

estimate_parameters(data_matrix, **kwargs)

Compute heuristic distribution parameters from a data matrix.

This method is optional and may be overridden by subclasses. The default implementation does nothing and returns None.

Parameters:

data_matrixnp.ndarray

2-D array of shape (N, M) containing the data used for estimation.

**kwargs

Additional keyword arguments that may influence the estimation.

Returns:

None

class ScipyUnivarDistribution(distribution_cls, rng, **kwargs)

Bases: Distribution

Wraps a SciPy univariate distribution.

Parameters:

distribution_clstype

A SciPy distribution class (e.g., scipy.stats.norm).

**kwargs

Parameters forwarded to the distribution constructor.

Methods

estimate_parameters(data_matrix, **kwargs)	Compute heuristic distribution parameters from a data matrix.
sample(shape)	Draw random samples.

sample(shape)

Draw random samples.

Return type:

ndarray[tuple[int, ...], floating] | ndarray[tuple[int, ...], integer] | ndarray[tuple[int, ...], uint8 | bool]

Parameters:

shapetuple

Desired output shape, e.g., (N, M).

rngRNGLike

Random number generator.

Returns:

np.ndarray

Array of independent samples of the requested shape.

Parameters:

shape (tuple)

class ScipyMultivarDistribution(distribution_cls, rng=None, **kwargs)

Bases: Distribution

Wraps a SciPy multivariate distribution.

Parameters:

distribution_clstype

A SciPy multivariate distribution class (e.g., scipy.stats.multivariate_normal).

**kwargs

Parameters forwarded to the distribution constructor.

Methods

estimate_parameters(data_matrix, **kwargs)	Compute heuristic distribution parameters from a data matrix.
sample(shape)	Draw random samples.

sample(shape)

Draw random samples.

For a multivariate distribution, shape[1] is ignored; the output shape is determined by the number of individuals (shape[0]) and the dimension of the distribution.

Return type:

ndarray[tuple[int, ...], floating] | ndarray[tuple[int, ...], integer] | ndarray[tuple[int, ...], uint8 | bool]

Parameters:

shapetuple

Requested shape; only shape[0] is used.

rngRNGLike

Random number generator.

Returns:

np.ndarray

Array of shape (shape[0], dim).

Parameters:

shape (tuple)

class multivariate_categorical(categories, weight_matrix, rng)

Bases: Distribution

Multivariate categorical distribution with per-row probability weights.

Parameters:

categoriesarray-like

List of category values.

weight_matrixnp.ndarray

2-D array of shape (N, K) containing non-negative weights for each of the K categories in each row. Weights are normalised row-wise before sampling.

Methods

estimate_parameters(data_matrix, **kwargs)	Compute heuristic distribution parameters from a data matrix.
sample(shape)	Draw random samples.

sample(shape)

Draw random samples.

Return type:

ndarray[tuple[int, ...], floating] | ndarray[tuple[int, ...], integer] | ndarray[tuple[int, ...], uint8 | bool]

Parameters:

shapetuple

Requested shape; if None the number of rows is taken from self.cumsum_matrix.shape[0]. Otherwise the first element gives the number of rows, and additional dimensions are appended.

rngRNGLike

Random number generator.

Returns:

np.ndarray

Array of categorical samples with shape determined by shape.

Parameters:

shape (tuple)

uniform_param_fix(min=None, max=None, **kwargs)

Convert min/max arguments to loc/scale for a uniform distribution.

Parameters:

minfloat or array-like, optional

Lower bound of the uniform interval.

maxfloat or array-like, optional

Upper bound of the uniform interval.

**kwargsdict

Remaining keyword arguments (e.g., loc, scale).

Returns:

dict

A copy of kwargs with loc and scale set appropriately when both min and max are provided. min and max are removed from the dictionary.

normal_heuristic(population_matrix, loc=None, scale=None, **kwargs)

Heuristic parameter estimation for the normal distribution.

When loc or scale is the string "calculated", the sample mean or standard deviation (computed over axis 0) is used.

Parameters:

population_matrixnp.ndarray

2-D array of shape (N, M).

locNone, float, array-like, or "calculated"

Location parameter. If "calculated", it is replaced by the per-column mean.

scaleNone, float, array-like, or "calculated"

Scale parameter. If "calculated", it is replaced by the per-column standard deviation.

**kwargs

Additional keyword arguments passed through unchanged.

Returns:

dict

The updated kwargs with resolved loc and scale.

uniform_heuristic(population_matrix, loc=None, scale=None, **kwargs)

Heuristic parameter estimation for the uniform distribution.

When loc or scale is "calculated", the per-column minimum is used as loc, and max - min is used as scale.

Parameters:

population_matrixnp.ndarray

2-D array of shape (N, M).

locNone, float, array-like, or "calculated"

Lower bound. If "calculated", it is replaced by the per-column minimum.

scaleNone, float, array-like, or "calculated"

Interval length. If "calculated", it is set to max - min per column.

**kwargs

Additional keyword arguments passed through unchanged.

Returns:

dict

The updated kwargs with resolved loc and scale.

cauchy_heuristic(population_matrix, loc=None, scale=None, **kwargs)

Heuristic parameter estimation for the Cauchy distribution.

loc is estimated by the per-column median; scale is estimated by half the per-column interquartile range (IQR / 2).

Parameters:

population_matrixnp.ndarray

2-D array of shape (N, M).

locNone, float, array-like, or "calculated"

Location parameter. If "calculated", it is replaced by the per-column median.

scaleNone, float, array-like, or "calculated"

Scale parameter. If "calculated", it is estimated as scipy.stats.iqr(data, axis=0) / 2.

**kwargs

Additional keyword arguments passed through unchanged.

Returns:

dict

The updated kwargs with resolved loc and scale.

laplace_heuristic(population_matrix, loc=None, scale=None, **kwargs)

Heuristic parameter estimation for the Laplace distribution.

loc is estimated by the per-column median; scale is estimated by the median absolute deviation (MAD).

Parameters:

population_matrixnp.ndarray

2-D array of shape (N, M).

locNone, float, array-like, or "calculated"

Location parameter. If "calculated", it is replaced by the per-column median.

scaleNone, float, array-like, or "calculated"

Scale parameter. If "calculated", it is estimated using scipy.stats.median_abs_deviation along axis 0.

**kwargs

Additional keyword arguments passed through unchanged.

Returns:

dict

The updated kwargs with resolved loc and scale.

gamma_heuristic(population_matrix, a=None, scale=None, **kwargs)

Heuristic parameter estimation for the gamma distribution.

Uses method of moments: shape a = mean² / variance and scale = variance / mean.

Parameters:

population_matrixnp.ndarray

2-D array of shape (N, M).

aNone, float, array-like, or "calculated"

Shape parameter. If "calculated", it is computed as mean² / var.

scaleNone, float, array-like, or "calculated"

Scale parameter. If "calculated", it is computed as var / mean.

**kwargs

Additional keyword arguments passed through unchanged.

Returns:

dict

The updated kwargs with resolved a and scale.

expon_heuristic(population_matrix, scale=None, **kwargs)

Heuristic parameter estimation for the exponential distribution.

If scale is "calculated", it is set to the per-column mean minus loc (which defaults to 0).

Parameters:

population_matrixnp.ndarray

2-D array of shape (N, M).

scaleNone, float, array-like, or "calculated"

Scale parameter. If "calculated", scale = mean - loc.

**kwargs

Additional keyword arguments passed through unchanged; expected to contain loc if a non-zero shift is used.

Returns:

dict

The updated kwargs with resolved scale.

levy_stable_heuristic(population_matrix, loc=None, scale=None, **kwargs)

Heuristic parameter estimation for the Lévy-stable distribution.

loc is estimated by the per-column median; scale by the median absolute deviation (MAD). Note: this is a very rough approximation and should be used only when no better estimator is available.

Parameters:

population_matrixnp.ndarray

2-D array of shape (N, M).

locNone, float, array-like, or "calculated"

Location parameter. If "calculated", it is replaced by the per-column median.

scaleNone, float, array-like, or "calculated"

Scale parameter. If "calculated", it is estimated using scipy.stats.median_abs_deviation along axis 0.

**kwargs

Additional keyword arguments passed through unchanged.

Returns:

dict

The updated kwargs with resolved loc and scale.

poisson_heuristic(population_matrix, mu=None, **kwargs)

Heuristic parameter estimation for the Poisson distribution.

If mu is "calculated", it is set to the per-column mean minus loc (default 0).

Parameters:

population_matrixnp.ndarray

2-D array of shape (N, M).

muNone, float, array-like, or "calculated"

Rate parameter. If "calculated", mu = mean - loc.

**kwargs

Additional keyword arguments passed through unchanged; expected to contain loc if a non-zero shift is used.

Returns:

dict

The updated kwargs with resolved mu.

bernoulli_heuristic(population_matrix, p=None, **kwargs)

Heuristic parameter estimation for the Bernoulli distribution.

If p is "calculated", it is estimated as the per-column mean (proportion of ones), adjusting for loc if given (default 0).

Parameters:

population_matrixnp.ndarray

2-D array of shape (N, M).

pNone, float, array-like, or "calculated"

Success probability. If "calculated", p = mean - loc.

**kwargs

Additional keyword arguments passed through unchanged.

Returns:

dict

The updated kwargs with resolved p.

binomial_heuristic(population_matrix, p=None, **kwargs)

Heuristic parameter estimation for the binomial distribution.

n must be provided externally. If p is "calculated", it is estimated as (mean - loc) / n.

Parameters:

population_matrixnp.ndarray

2-D array of shape (N, M).

pNone, float, array-like, or "calculated"

Success probability. If "calculated", p = (mean - loc) / n.

**kwargs

Additional keyword arguments passed through unchanged; must contain the integer n (number of trials) and optionally loc.

Returns:

dict

The updated kwargs with resolved p.

tikhinov_heuristic(population_matrix, loc=None, kappa=None, **kwargs)

Heuristic parameter estimation for the von Mises (circular) distribution.

loc is estimated as the circular mean (arctan2(mean sin, mean cos)). kappa is approximated from the mean resultant length R as kappa = R / (1 - R).

Parameters:

population_matrixnp.ndarray

2-D array of shape (N, M) of angles in radians.

locNone, float, array-like, or "calculated"

Mean direction. If "calculated", the per-column circular mean is used.

kappaNone, float, array-like, or "calculated"

Concentration parameter. If "calculated", it is approximated from the mean resultant length.

**kwargs

Additional keyword arguments passed through unchanged.

Returns:

dict

The updated kwargs with resolved loc and kappa.

multivariate_normal_heuristic(population_matrix, mean=None, cov=None, **kwargs)

Heuristic parameter estimation for the multivariate normal distribution.

mean is estimated as the per-column average. Automatic estimation of the full covariance matrix is not supported, use with caution.

Parameters:

population_matrixnp.ndarray

2-D array of shape (N, M).

meanNone, array-like, or "calculated"

Mean vector. If "calculated", it is set to the per-column mean.

covNone, array-like, or "calculated"

Covariance matrix. If "calculated", an error is raised because automatic estimation is not implemented.

**kwargs

Additional keyword arguments passed through unchanged.

Returns:

dict

The updated kwargs with resolved mean (and possibly cov).

Raises:

ValueError

If cov is "calculated", automatic covariance estimation is not supported.

dirichlet_heuristic(population_matrix, alpha=None, **kwargs)

Heuristic parameter estimation for the Dirichlet distribution.

Automatic estimation of the concentration parameter vector alpha is not supported.

Parameters:

population_matrixnp.ndarray

2-D array of shape (N, M).

alphaNone, array-like, or "calculated"

Concentration parameters. If "calculated", an error is raised.

**kwargs

Additional keyword arguments passed through unchanged.

Returns:

dict

The updated kwargs with resolved alpha.

Raises:

ValueError

If alpha is "calculated", automatic estimation is not supported.

tikhinov_fisher_heuristic(population_matrix, loc=None, kappa=None, **kwargs)

Heuristic parameter estimation for the von Mises-Fisher distribution.

loc is estimated by normalizing the mean vector of the data. kappa is approximated using the mean resultant length R and the dimension d: kappa = R * (d - R²) / (1 - R²).

Parameters:

population_matrixnp.ndarray

2-D array of shape (N, d) where each row is a point on the d-dimensional sphere.

locNone, array-like, or "calculated"

Mean direction (unit vector). If "calculated", it is set to the normalized sample mean.

kappaNone, float, or "calculated"

Concentration parameter. If "calculated", it is approximated from the mean resultant length.

**kwargs

Additional keyword arguments passed through unchanged.

Returns:

dict

The updated kwargs with resolved loc and kappa.