mixle.stats.directional.bingham module

Bingham distribution on the 2-sphere (antipodally symmetric axial data).

The Bingham distribution models axes (unit vectors identified with their antipodes, x ~ -x) on S^2. Its density is

f(x) = c(Z)^{-1} exp( sum_i z_i * (m_i . x)^2 ),

where M = [m_1, m_2, m_3] is a 3 x 3 orthonormal orientation and z = (z_1, z_2, z_3) are the concentrations (defined only up to a common additive shift, since sum_i (m_i . x)^2 = 1; by convention the largest is taken to be 0). It is the antipodally symmetric analogue of the von Mises-Fisher / Kent laws and the standard model for undirected orientation data (crystallography, geology, principal axes). Equal concentrations give the uniform distribution on the sphere; a large gap concentrates mass on a great circle (girdle) or a pair of poles (bipolar).

Normalizer (reduced to a stable 1-D integral, verified to <1e-7 against arbitrary-precision integration over S^2):

c(Z) = 2 pi integral_0^pi exp(z_3 cos^2 t + (z_1+z_2)/2 sin^2 t) I_0((z_1-z_2)/2 sin^2 t) sin t dt.

Sampling is by exact angular-central-Gaussian-envelope rejection (Kent, Ganeiber & Mardia 2013); the orientation and concentrations are fit by maximum likelihood (the orientation is the eigenbasis of the scatter matrix; the concentrations solve the concave moment-matching problem d log c / d z_i = E[(m_i . x)^2]).

Reference: Bingham, “An antipodally symmetric distribution on the sphere”, Annals of Statistics 2 (1974); Kent, Ganeiber & Mardia, “A new method to simulate the Bingham and related distributions”, (2013); Mardia & Jupp, Directional Statistics (2000).

class BinghamDistribution(m, z, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Bingham distribution on S^2 with orientation m (3x3) and concentrations z (length 3).

Parameters:
density(x)[source]

Return the Bingham 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 (the same value at x and -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 Bingham log-density kernels.

backend_seq_log_density(x, engine)[source]

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

Parameters:
Return type:

Any

sampler(seed=None)[source]

Return an exact rejection sampler for this Bingham distribution.

Parameters:

seed (int | None)

Return type:

BinghamSampler

estimator(pseudo_count=None)[source]

Return a maximum-likelihood estimator for Bingham orientation and concentration.

Parameters:

pseudo_count (float | None)

Return type:

BinghamEstimator

dist_to_encoder()[source]

Return the unit-vector encoder used by vectorized methods.

Return type:

BinghamDataEncoder

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

Bases: DistributionSampler

Sample by angular-central-Gaussian-envelope rejection (Kent, Ganeiber & Mardia 2013).

Parameters:

  • dist (BinghamDistribution)

  • seed (int | None)

sample(size=None)[source]

Draw one axial unit vector or size iid vectors.

Parameters:

size (int | None)

Return type:

Any

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

Bases: SequenceEncodableStatisticAccumulator

Accumulate (count, sum_xx (3,3)) – the scatter matrix is sufficient for the Bingham fit.

Parameters:

  • name (str | None)

  • keys (str | None)

update(x, weight, estimate)[source]

Update scatter statistics from one weighted unit vector.

Parameters:

  • x (Any)

  • weight (float)

  • estimate (BinghamDistribution | None)

Return type:

None

initialize(x, weight, rng)[source]

Initialize scatter statistics from one weighted unit vector.

Parameters:
Return type:

None

seq_update(x, weights, estimate)[source]

Update scatter statistics from encoded unit vectors.

Parameters:
Return type:

None

seq_initialize(x, weights, rng)[source]

Initialize scatter statistics from encoded unit vectors.

Parameters:
Return type:

None

combine(suff_stat)[source]

Merge weighted count and scatter statistics.

Parameters:

suff_stat (tuple[float, ndarray])

Return type:

BinghamAccumulator

value()[source]

Return weighted count and scatter matrix.

Return type:

tuple[float, ndarray]

from_value(x)[source]

Restore weighted count and scatter matrix.

Parameters:

x (tuple[float, ndarray])

Return type:

BinghamAccumulator

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 Bingham scatter statistics.

Return type:

BinghamDataEncoder

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

Bases: StatisticAccumulatorFactory

Factory for BinghamAccumulator.

Parameters:

  • name (str | None)

  • keys (str | None)

make()[source]

Create an empty Bingham accumulator.

Return type:

BinghamAccumulator

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

Bases: ParameterEstimator

Maximum-likelihood Bingham fit: scatter eigenbasis + concave concentration moment-matching.

Parameters:

  • name (str | None)

  • keys (str | None)

estimate(nobs, suff_stat)[source]

Estimate orientation and concentrations from scatter statistics.

Parameters:
Return type:

BinghamDistribution

accumulator_factory()[source]

Return a factory for Bingham sufficient-statistic accumulators.

Return type:

BinghamAccumulatorFactory

class BinghamDataEncoder[source]

Bases: DataSequenceEncoder

Encode axial data as a normalized (n, 3) float array (sign is irrelevant: x ~ -x).

seq_encode(x)[source]

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

Parameters:

x (Sequence[Any])

Return type:

ndarray