mixle.stats.multivariate.composition module

Compositional data analysis: Aitchison logratio transforms and the logratio-normal distribution.

Geochemistry (and many earth-science) measurements are compositions – vectors of non-negative parts that sum to a constant (element abundances, mineral fractions, isotope splits). Ordinary statistics on them is wrong: they live on the simplex, not in real space. Aitchison’s logratio transforms (clr/ilr) map the simplex isometrically to real coordinates where standard multivariate-Gaussian modelling applies; the isometric logratio (ilr) uses an orthonormal basis so distances/covariances are preserved.

AitchisonNormalDistribution is the logratio-normal – ilr(x) ~ N(mean, cov) – as a first-class mixle distribution: it follows the Distribution / Sampler / Estimator / Accumulator / DataEncoder contract by delegating the Gaussian to MultivariateGaussianDistribution after the ilr transform, so it composes with the rest of the library (mixtures, the unified estimate/ sample entry points, …) like any other leaf.

closure(x, total=1.0)[source]

Normalize each row to sum to total (project onto the simplex).

Parameters:
Return type:

ndarray

clr(x)[source]

Centered logratio: clr(x)_i = log(x_i) - mean_j log(x_j). Maps the simplex to the zero-sum hyperplane in R^D (the parts stay labelled, but the result is singular – use ilr for modelling).

Parameters:

x (ndarray)

Return type:

ndarray

clr_inv(y)[source]

Inverse clr (softmax onto the simplex).

Parameters:

y (ndarray)

Return type:

ndarray

ilr(x, basis=None)[source]

Isometric logratio: D-part composition -> D-1 real coordinates (orthonormal, so Euclidean distance in ilr space equals Aitchison distance on the simplex).

Parameters:
Return type:

ndarray

ilr_inv(y, basis=None)[source]

Inverse isometric logratio: D-1 real coordinates -> D-part composition on the simplex.

Parameters:
Return type:

ndarray

ilr_basis(d)[source]

A (D, D-1) orthonormal contrast basis (Helmert) for the isometric logratio of D parts.

Parameters:

d (int)

Return type:

ndarray

class AitchisonNormalDistribution(mean, cov, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

A logratio-normal distribution on the simplex: ilr(x) ~ N(mean, cov).

The natural Gaussian for compositions – modelled in the orthonormal ilr coordinates, interpreted on the simplex. mean (length D-1) and cov ((D-1, D-1)) are the ilr-space parameters of a D-part composition; everything Gaussian is delegated to a MultivariateGaussianDistribution.

Parameters:

  • mean (np.ndarray)

  • cov (np.ndarray)

  • name (str | None)

  • keys (str | None)

property mean: ndarray

Return the Gaussian mean in ilr coordinates.

property cov: ndarray

Return the Gaussian covariance in ilr coordinates.

density(x)[source]

Return the density of one composition under the ilr-space Gaussian.

Parameters:

x (ndarray)

Return type:

float

log_density(x)[source]

Log-density at a single composition (the ilr-space Gaussian log-density).

Parameters:

x (ndarray)

Return type:

float

seq_log_density(x)[source]

Return vectorized log-densities for ilr-encoded compositions.

Return type:

ndarray

mean_composition()[source]

The center of the distribution as a composition (the ilr-mean mapped back to the simplex).

Return type:

ndarray

sampler(seed=None)[source]

Return a sampler that draws in ilr space and maps back to the simplex.

Parameters:

seed (int | None)

Return type:

AitchisonNormalSampler

estimator(pseudo_count=None)[source]

Return an estimator that fits a Gaussian in ilr coordinates.

Parameters:

pseudo_count (float | None)

Return type:

AitchisonNormalEstimator

dist_to_encoder()[source]

Return the ilr-transform encoder used by vectorized methods.

Return type:

AitchisonNormalDataEncoder

class AitchisonNormalEstimator(name=None, keys=None)[source]

Bases: ParameterEstimator

Maximum-likelihood estimator: the Gaussian MLE in ilr coordinates (delegated to MVN).

Parameters:

  • name (str | None)

  • keys (str | None)

accumulator_factory()[source]

Return an accumulator factory that delegates to the Gaussian estimator.

Return type:

StatisticAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate a logratio-normal distribution from ilr-space sufficient statistics.

Return type:

AitchisonNormalDistribution