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
property cov: ndarray
density(x)[source]

Return the probability density or mass at a single observation.

Concrete default: exponentiate log_density (the abstract method subclasses must provide). Leaves with a cheaper closed form may override this.

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-density values for sequence-encoded observations.

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 for drawing observations from this distribution.

Parameters:

seed (int | None)

Return type:

AitchisonNormalSampler

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:

pseudo_count (float | None)

Return type:

AitchisonNormalEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for 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 type:

StatisticAccumulatorFactory

estimate(nobs, suff_stat)[source]
Return type:

AitchisonNormalDistribution