mixle.stats.directional.von_mises module

Create, estimate, and sample from a von Mises distribution on the circle (angular data).

Defines the VonMisesDistribution, VonMisesSampler, VonMisesAccumulatorFactory, VonMisesAccumulator, VonMisesEstimator, and the VonMisesDataEncoder classes for use with mixle.

Data type: (float): an angle in radians. The VonMisesDistribution with mean direction mu and concentration kappa >= 0 has log-density

log(f(theta; mu, kappa)) = kappa * cos(theta - mu) - log(2*pi*I_0(kappa)),

the circular analogue of a Gaussian (kappa = 0 is uniform on the circle; large kappa concentrates near mu). This is the one-dimensional companion to von_mises_fisher (the von Mises-Fisher distribution on a sphere).

It is a two-parameter exponential family with sufficient statistics (cos theta, sin theta):

log(f) = eta1*cos(theta) + eta2*sin(theta) + log_const,

eta1 = kappa*cos(mu), eta2 = kappa*sin(mu), log_const = -log(2*pi*I_0(kappa)).

The natural parameters and normalizer are precomputed (the Bessel term I_0 lives only in the scalar log_const), so the per-row score is linear in the encoded cos/sin fields and lowers cleanly to generated NumPy, Torch, and Numba kernels.

Reference: Mardia & Jupp, Directional Statistics (Wiley, 2000).

class VonMisesDistribution(mu, kappa, name=None, keys=None)

Bases: SequenceEncodableProbabilityDistribution

Von Mises distribution on the circle with mean direction mu and concentration kappa >= 0.

Parameters:

• mu (float)

• kappa (float)

• name (str | None)

• keys (str | None)

classmethod compute_capabilities()

classmethod compute_declaration()

static backend_legacy_sufficient_statistics(x, params, engine)

Return per-row (count, cos, sin) sufficient statistics in accumulator order.

Parameters:

• x (tuple[Any, Any])

• params (dict[str, Any])

• engine (Any)

Return type:

tuple[Any, …]

static exp_family_sufficient_statistics(x, engine)

Return von Mises sufficient statistics T(x) = (cos x, sin x).

Parameters:

• x (tuple[Any, Any])

• engine (Any)

Return type:

tuple[Any, …]

static exp_family_natural_parameters(params, engine)

Return von Mises natural parameters eta = (kappa cos mu, kappa sin mu).

Parameters:

• params (dict[str, Any])

• engine (Any)

Return type:

tuple[Any, …]

static exp_family_log_partition(params, engine)

Return von Mises log partition A = log(2 pi I_0(kappa)) = -log_const.

Parameters:

• params (dict[str, Any])

• engine (Any)

Return type:

Any

static exp_family_from_natural(eta)

Return the von Mises with natural parameters eta = (kappa cos mu, kappa sin mu).

Parameters:

eta (Any)

Return type:

VonMisesDistribution

static backend_log_density_from_params(cos_t, sin_t, eta1, eta2, log_const, engine)

Engine-neutral von Mises log-density from natural parameters (linear in cos/sin).

Parameters:

• cos_t (Any)

• sin_t (Any)

• eta1 (Any)

• eta2 (Any)

• log_const (Any)

• engine (Any)

Return type:

Any

density(x)

Return the probability density at a single angle.

Parameters:

x (float)

Return type:

float

log_density(x)

Return the log-density at a single angle (radians).

Parameters:

x (float)

Return type:

float

seq_log_density(x)

Return vectorized log-density values for sequence-encoded (cos, sin) observations.

Parameters:

x (tuple[ndarray, ndarray])

Return type:

ndarray

backend_seq_log_density(x, engine)

Engine-neutral vectorized log-density for encoded data.

Parameters:

• x (tuple[Any, Any])

• engine (Any)

Return type:

Any

classmethod backend_stacked_params(dists, engine)

Return stacked natural parameters for a homogeneous mixture kernel.

Parameters:

• dists (Sequence[VonMisesDistribution])

• engine (Any)

Return type:

dict[str, Any]

classmethod backend_stacked_log_density(x, params, engine)

Return an (n, k) matrix of von Mises log densities.

Parameters:

• x (tuple[Any, Any])

• params (dict[str, Any])

• engine (Any)

Return type:

Any

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)

Return stacked sufficient statistics using engine-resident arrays.

Parameters:

• x (tuple[Any, Any])

• weights (Any)

• params (dict[str, Any])

• engine (Any)

Return type:

tuple[Any, Any, Any]

sampler(seed=None)

Return a sampler for drawing angles from this distribution.

Parameters:

seed (int | None)

Return type:

VonMisesSampler

estimator(pseudo_count=None)

Return an estimator for fitting this distribution from data.

Parameters:

pseudo_count (float | None)

Return type:

VonMisesEstimator

dist_to_encoder()

Return the data encoder used by this distribution for vectorized methods.

Return type:

VonMisesDataEncoder

class VonMisesSampler(dist, seed=None)

Bases: DistributionSampler

Draw iid angles from a von Mises distribution.

Parameters:

• dist (VonMisesDistribution)

• seed (int | None)

sample(size=None)

Draw size iid angles in (-pi, pi] (a float when size is None).

Parameters:

size (int | None)

Return type:

float | ndarray

class VonMisesAccumulator(keys=None)

Bases: SequenceEncodableStatisticAccumulator

Accumulate weighted count and circular moments (sum of cos / sin) for von Mises estimation.

Parameters:

keys (str | None)

update(x, weight, estimate)

Parameters:

• x (float)

• weight (float)

• estimate (VonMisesDistribution | None)

Return type:

None

initialize(x, weight, rng)

Parameters:

• x (float)

• weight (float)

• rng (RandomState | None)

Return type:

None

seq_update(x, weights, estimate)

Parameters:

• x (tuple[ndarray, ndarray])

• weights (ndarray)

• estimate (VonMisesDistribution | None)

Return type:

None

seq_initialize(x, weights, rng)

Parameters:

• x (tuple[ndarray, ndarray])

• weights (ndarray)

• rng (RandomState | None)

Return type:

None

combine(suff_stat)

Parameters:

suff_stat (tuple[float, float, float])

Return type:

VonMisesAccumulator

value()

Return type:

tuple[float, float, float]

from_value(x)

Parameters:

x (tuple[float, float, float])

Return type:

VonMisesAccumulator

key_merge(stats_dict)

Pool this accumulator’s statistics into stats_dict under its merge key.

The structural default implements the common single-key pattern: store the accumulator under self.keys the first time the key is seen, else combine into the one already there. Accumulators with several named keys (e.g. an HMM’s init/trans/state keys) or a non-accumulator stats payload override this. A keys of None (the default) is a no-op.

Parameters:

stats_dict (dict[str, Any])

Return type:

None

key_replace(stats_dict)

Replace this accumulator’s statistics from the pooled stats_dict entry (see key_merge).

Parameters:

stats_dict (dict[str, Any])

Return type:

None

acc_to_encoder()

Return type:

VonMisesDataEncoder

class VonMisesAccumulatorFactory(keys=None)

Bases: StatisticAccumulatorFactory

Factory for VonMisesAccumulator.

Parameters:

keys (str | None)

make()

Return type:

VonMisesAccumulator

class VonMisesEstimator(pseudo_count=None, suff_stat=None, name=None, keys=None)

Bases: ParameterEstimator

Maximum-likelihood estimator for the von Mises mean direction and concentration.

The MLE is mu = atan2(sum sin, sum cos) and kappa = A^{-1}(R) where R is the mean resultant length and A(kappa) = I_1(kappa) / I_0(kappa).

Parameters:

• pseudo_count (float | None)

• suff_stat (tuple[float, float] | None)

• name (str | None)

• keys (str | None)

accumulator_factory()

Return type:

VonMisesAccumulatorFactory

estimate(nobs, suff_stat)

Parameters:

• nobs (float | None)

• suff_stat (tuple[float, float, float])

Return type:

VonMisesDistribution

class VonMisesDataEncoder

Bases: DataSequenceEncoder

Encode angle observations as (cos, sin) pairs.

seq_encode(x)

Encode the iid observation sequence x for vectorized evaluation.

Parameters:

x (Sequence[float])

Return type:

tuple[ndarray, ndarray]