[10] Simplex Methods#

pysht.simplex provides two tests of uniformity with respect to simplex volume and an equality-of-distributions test for compositional samples.

Question

Function

Calibration

Is a sample uniform against a Dirichlet alternative?

uniformity

Wilks approximation

Is nearest-neighbor geometry compatible with simplex uniformity?

ehy_uniformity

Monte Carlo simplex null

Do two or more compositional distributions agree?

alpha_energy_ksamp

exact or Monte Carlo label permutation

ehy_uniformity requires prespecified alpha and n_neighbors. It sums the first \(J\) nearest-neighbor contributions on the flat \((D-1)\)-dimensional simplex and uses the simplex’s Hausdorff-volume density. Its parameter domain is \(\alpha>0\), \(\alpha\ne1\), and \(1\le J<n\); zeros on the simplex boundary are allowed.

alpha_energy_ksamp requires one prespecified alpha in \([-1,1]\). At alpha=0 it uses the Aitchison metric and all components must be strictly positive. Structural zeros are accepted only for alpha>0. Automatic calibration="permutation" enumerates the complete fixed-size allocation orbit when it fits n_resamples, and otherwise uses Monte Carlo permutation. Repeated compositions are supported. For unresolved symmetries beyond the bounded canonical-orbit calculation, reordering components or observations can change a fixed seed’s Monte Carlo count; the statistic and the uniform permutation distribution remain the same. No data-selected alpha is offered because that would require joint calibration.

Dirichlet likelihood-ratio alternatives#

The model selector controls the alternative:

model

Alternative model

Wilks degrees of freedom

"symmetric"

one common positive concentration

1

"general"

one positive concentration per component

number of components

Inputs must lie in the strict simplex interior. Boundary zeros are not perturbed. The optimizer controls tolerance and max_iter are explicit and fail loudly when a finite maximum cannot be established.

See the simplex-uniformity validation ledger for the likelihood, independent optimization oracle, null calibration, and MLE boundary cases. The native additions have separate ledgers for EHY simplex uniformity and alpha-energy compositional equality.

Functions#

Goodness-of-fit tests for observations on a probability simplex.

pysht.simplex.alpha_energy_ksamp(*samples, alpha, calibration='permutation', n_resamples=9_999, rng=None)[source]#

Test equality of compositional distributions with alpha-energy.

alpha is fixed before labels are inspected and must lie in [-1, 1]. At zero the transform is the isometric log-ratio metric (represented in centered log-ratio coordinates); it therefore requires strictly positive components. Structural zeros are supported only when alpha > 0.

Parameters:

  • samples (ArrayLike)

  • alpha (float)

  • calibration (str)

  • n_resamples (int)

  • rng (int | integer | Generator | None)

Return type:

ResamplingTestResult

pysht.simplex.ehy_uniformity(x, *, alpha, n_neighbors, calibration='monte-carlo', n_resamples=9_999, rng=None)[source]#

Perform the EHY nearest-neighbor test of simplex uniformity.

Distances are intrinsic Euclidean distances on the flat (D-1)-dimensional simplex. Boundary compositions are allowed. The test rejects in the lower tail when 0 < alpha < 1 and in the upper tail when alpha > 1; alpha=1 is not an identifiable test.

Parameters:

  • x (ArrayLike)

  • alpha (float)

  • n_neighbors (int)

  • calibration (str)

  • n_resamples (int)

  • rng (int | integer | Generator | None)

Return type:

ResamplingTestResult

pysht.simplex.uniformity(x, *, model='symmetric', tolerance=1.0e-10, max_iter=200)[source]#

Test uniformity on a probability simplex with a Dirichlet LRT.

Parameters:
x

An (n, k) matrix whose rows lie in the strict interior of the probability simplex. At least two rows and two components are needed. Rows whose sums differ from one by no more than a documented floating-point tolerance are normalized before fitting.

model

"symmetric" fits one common Dirichlet concentration parameter; "general" fits one positive parameter per component.

tolerance

Positive convergence tolerance for the score equations.

max_iter

Positive maximum number of bracketing/root or Newton iterations.

Returns:
HypothesisTestResult

The likelihood-ratio statistic calibrated by Wilks’ chi-square approximation with one or k degrees of freedom.

Parameters:

  • x (ArrayLike)

  • model (str)

  • tolerance (float)

  • max_iter (int)

Return type:

HypothesisTestResult

Notes

The null is Dirichlet alpha=(1, ..., 1), the uniform distribution with respect to simplex volume. Boundary components are rejected instead of being silently perturbed. The general-model fit rejects identical rows, for which its concentration MLE is unbounded. The symmetric fit is unbounded only when every row is the simplex barycenter.