mixle.stats.directional.kent module¶

Kent (Fisher-Bingham FB5) distribution on the 2-sphere.

The Kent distribution is the elliptical analogue of the von Mises-Fisher law on S^2 (unit vectors in R^3). Its density at a unit vector x is

f(x) = c(kappa, beta)^{-1} exp( kappa * (g1 . x) + beta * [(g2 . x)^2 - (g3 . x)^2] ),

where G = [g1, g2, g3] is a 3 x 3 orthonormal orientation (g1 the mean direction, g2 the major axis, g3 the minor axis), kappa > 0 is the concentration and 0 <= 2 beta < kappa the ovalness. beta = 0 recovers von Mises-Fisher (circular contours); beta -> kappa/2 gives highly elliptical (girdle-like) contours. It is the standard model for asymmetric clusters of orientations (palaeomagnetism, structural geology, spherical data).

Normalizer (verified to 1e-12 against arbitrary-precision integration over S^2):

c(kappa, beta) = 2 pi sum_{j>=0} [Gamma(j+1/2)/Gamma(j+1)] beta^{2j} (2/kappa)^{2j+1/2} I_{2j+1/2}(kappa),

evaluated in log space with exponentially scaled Bessel functions for numerical stability. Sampling is by exact von Mises-Fisher-envelope rejection; kappa, beta and the orientation are fit by Kent’s moment method (mean direction + tangential scatter eigenvectors) followed by a maximum-likelihood refinement of (kappa, beta).

Reference: Kent, “The Fisher-Bingham distribution on the sphere”, J. Royal Statistical Society B 44 (1982); Mardia & Jupp, Directional Statistics (2000), ch. 9.

class KentDistribution(gamma, kappa, beta, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Kent (FB5) distribution on S^2 with orientation gamma (3x3), concentration and ovalness.

Parameters:

gamma (ndarray)
kappa (float)
beta (float)
name (str | None)
keys (str | None)

density(x)[source]

Return the Kent density at one unit 3-vector.

Parameters:: x (Any)
Return type:: float

log_density(x)[source]

Return the log-density at a unit 3-vector x.

Parameters:: x (Any)
Return type:: float

seq_log_density(x)[source]

Return vectorized log-density for a sequence-encoded (n, 3) array of unit vectors.

Parameters:: x (ndarray)
Return type:: ndarray

classmethod compute_capabilities()[source]: Declare NumPy/Torch scoring capabilities for Kent log-density kernels.

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for (N, 3) unit vectors.

Parameters:

x (Any)
engine (Any)

Return type:

Any

sampler(seed=None)[source]

Return an exact rejection sampler for this Kent distribution.

Parameters:: seed (int | None)
Return type:: KentSampler

estimator(pseudo_count=None)[source]

Return Kent’s moment/ML estimator for orientation, concentration, and ovalness.

Parameters:: pseudo_count (float | None)
Return type:: KentEstimator

dist_to_encoder()[source]

Return the unit-vector encoder used by vectorized methods.

Return type:: KentDataEncoder

class KentSampler(dist, seed=None)[source]

Bases: DistributionSampler

Sample by von Mises-Fisher-envelope rejection (exact).

Parameters:

dist (KentDistribution)
seed (int | None)

sample(size=None)[source]

Draw one unit vector or size iid unit vectors.

Parameters:: size (int | None)
Return type:: Any

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

Bases: SequenceEncodableStatisticAccumulator

Accumulate (count, sum_x (3,), sum_xx (3,3)) – the sufficient statistics for the moment fit.

Parameters:

name (str | None)
keys (str | None)

update(x, weight, estimate)[source]

Update first- and second-moment statistics from one weighted vector.

Parameters:

x (Any)
weight (float)
estimate (KentDistribution | None)

Return type:

None

initialize(x, weight, rng)[source]

Initialize moment statistics from one weighted vector.

Parameters:

x (Any)
weight (float)
rng (RandomState | None)

Return type:

None

seq_update(x, weights, estimate)[source]

Update moment statistics from encoded unit vectors.

Parameters:

x (ndarray)
weights (ndarray)
estimate (Any)

Return type:

None

seq_initialize(x, weights, rng)[source]

Initialize moment statistics from encoded unit vectors.

Parameters:

x (ndarray)
weights (ndarray)
rng (RandomState | None)

Return type:

None

combine(suff_stat)[source]

Merge weighted count, vector sum, and scatter matrix statistics.

Parameters:: suff_stat (tuple[float, ndarray, ndarray])
Return type:: KentAccumulator

value()[source]

Return weighted count, vector sum, and scatter matrix.

Return type:: tuple[float, ndarray, ndarray]

from_value(x)[source]

Restore weighted count, vector sum, and scatter matrix.

Parameters:: x (tuple[float, ndarray, ndarray])
Return type:: KentAccumulator

key_merge(stats_dict)[source]

Merge this accumulator into stats_dict under its configured key.

Parameters:: stats_dict (dict[str, Any])
Return type:: None

key_replace(stats_dict)[source]

Replace this accumulator’s state from keyed statistics when present.

Parameters:: stats_dict (dict[str, Any])
Return type:: None

acc_to_encoder()[source]

Return the encoder compatible with Kent moment statistics.

Return type:: KentDataEncoder

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

Bases: StatisticAccumulatorFactory

Factory for KentAccumulator.

Parameters:

name (str | None)
keys (str | None)

make()[source]

Create an empty Kent accumulator.

Return type:: KentAccumulator

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

Bases: ParameterEstimator

Kent’s moment estimator for the orientation, with an ML refinement of (kappa, beta).

Parameters:

name (str | None)
keys (str | None)

accumulator_factory()[source]

Return a factory for Kent sufficient-statistic accumulators.

Return type:: KentAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate orientation, concentration, and ovalness from moment statistics.

Parameters:

nobs (float | None)
suff_stat (tuple[float, ndarray, ndarray])

Return type:

KentDistribution

class KentDataEncoder[source]

Bases: DataSequenceEncoder

Encode unit vectors as a normalized (n, 3) float array.

seq_encode(x)[source]

Normalize and encode observations as an (n, 3) array.

Parameters:: x (Sequence[Any])
Return type:: ndarray