mixle.stats.multivariate.composition module

Compositional transforms and a Jacobian-correct logratio-normal density.

Compositions are strictly positive vectors on the unit simplex. clr and ilr map positive rays to logratio coordinates; AitchisonNormalDistribution uses an ilr Gaussian and reports density with respect to ordinary Lebesgue measure on the first D-1 simplex coordinates. Consequently its score includes the absolute ilr change-of-variables Jacobian

|d ilr(x) / d(x_1,...,x_{D-1})| = 1 / (sqrt(D) * product_i x_i).

closure(x, total=1.0)

Normalize strictly positive finite rows to a positive finite total.

Parameters:

• x (ndarray)

• total (float)

Return type:

ndarray

clr(x)

Return centered logratios for strictly positive finite compositions.

Parameters:

x (ndarray)

Return type:

ndarray

clr_inv(y)

Map finite clr-coordinate rows to the unit simplex.

Parameters:

y (ndarray)

Return type:

ndarray

ilr(x, basis=None)

Map strictly positive D-part rows to D-1 ilr coordinates.

Parameters:

• x (ndarray)

• basis (ndarray | None)

Return type:

ndarray

ilr_inv(y, basis=None)

Map finite D-1 ilr rows to strictly positive unit compositions.

Parameters:

• y (ndarray)

• basis (ndarray | None)

Return type:

ndarray

ilr_basis(d)

Return the Helmert (D, D-1) orthonormal contrast basis.

Parameters:

d (int)

Return type:

ndarray

class AitchisonNormalDistribution(mean, cov, name=None, keys=None)

Bases: SequenceEncodableProbabilityDistribution

Logratio-normal density on ordinary unit-simplex coordinates.

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)

Return ordinary-coordinate simplex density.

Parameters:

x (ndarray)

Return type:

float

log_density(x)

Return density relative to the first D-1 simplex coordinates.

Parameters:

x (ndarray)

Return type:

float

seq_log_density(x)

Score an encoded (ilr coordinates, log Jacobian) payload.

Parameters:

x (tuple[ndarray, ndarray])

Return type:

ndarray

mean_composition()

Return the ilr-mean mapped to the unit simplex.

Return type:

ndarray

sampler(seed=None)

Return a push-forward sampler from the ilr Gaussian.

Parameters:

seed (int | None)

Return type:

AitchisonNormalSampler

estimator(pseudo_count=None)

Return an estimator preserving keys and optional current-model smoothing.

Parameters:

pseudo_count (float | None)

Return type:

AitchisonNormalEstimator

dist_to_encoder()

Return a fixed-width composition encoder.

Return type:

AitchisonNormalDataEncoder

class AitchisonNormalSampler(dist, seed=None)

Bases: DistributionSampler

Sample compositions by inverting Gaussian ilr draws.

Parameters:

• dist (AitchisonNormalDistribution)

• seed (int | None)

sample(size=None, *, batched=True)

Draw one composition or size iid compositions.

Parameters:

• size (int | None)

• batched (bool)

Return type:

ndarray

class AitchisonNormalDataEncoder(gaussian_encoder, n_parts)

Bases: DataSequenceEncoder

Encode simplex rows as ilr coordinates plus their log Jacobians.

Parameters:

• gaussian_encoder (DataSequenceEncoder)

• n_parts (int)

seq_encode(x)

Validate unit-simplex rows and encode coordinates with Jacobians.

Parameters:

x (Any)

Return type:

tuple[ndarray, ndarray]

row_count(x)

Return the number of aligned encoded rows.

Parameters:

x (tuple[ndarray, ndarray])

Return type:

int

class AitchisonNormalEstimator(dim=None, pseudo_count=None, suff_stat=(None, None), name=None, keys=None)

Bases: ParameterEstimator

Fit a Gaussian in ilr coordinates with explicit smoothing and keys.

Parameters:

• dim (int | None)

• pseudo_count (float | None)

• suff_stat (tuple[np.ndarray | None, np.ndarray | None])

• name (str | None)

• keys (str | None)

accumulator_factory()

Return a keyed accumulator factory delegated to the Gaussian estimator.

Return type:

StatisticAccumulatorFactory

estimate(nobs, suff_stat)

Estimate ilr Gaussian parameters from delegated sufficient statistics.

Parameters:

• nobs (float | None)

• suff_stat (Any)

Return type:

AitchisonNormalDistribution

class AitchisonNormalAccumulator(gaussian_acc, n_parts, keys=None)

Bases: SequenceEncodableStatisticAccumulator

Delegate ilr-coordinate moments while preserving wrapper key semantics.

Parameters:

• gaussian_acc (Any)

• n_parts (int | None)

• keys (str | None)

update(x, weight, estimate)

Update delegated Gaussian statistics from one raw composition.

Parameters:

• x (ndarray)

• weight (float)

• estimate (AitchisonNormalDistribution | None)

Return type:

None

initialize(x, weight, rng)

Initialize delegated statistics from one raw composition.

Parameters:

• x (ndarray)

• weight (float)

• rng (Any)

Return type:

None

seq_update(x, weights, estimate)

Update delegated moments from encoded ilr coordinates.

Parameters:

• x (tuple[ndarray, ndarray])

• weights (ndarray)

• estimate (AitchisonNormalDistribution | None)

Return type:

None

seq_initialize(x, weights, rng)

Initialize delegated moments from encoded ilr coordinates.

Parameters:

• x (tuple[ndarray, ndarray])

• weights (ndarray)

• rng (Any)

Return type:

None

combine(suff_stat)

Merge delegated Gaussian sufficient statistics.

Parameters:

suff_stat (Any)

Return type:

AitchisonNormalAccumulator

value()

Return delegated Gaussian sufficient statistics.

Return type:

Any

from_value(x)

Restore delegated Gaussian sufficient statistics.

Parameters:

x (Any)

Return type:

AitchisonNormalAccumulator

acc_to_encoder()

Return an encoder compatible with accumulated ilr dimension.

Return type:

AitchisonNormalDataEncoder