mixle.stats.directional.wrapped_cauchy module

Wrapped Cauchy distribution – a heavy-tailed circular law on angles.

Wrapping a Cauchy around the circle gives the wrapped Cauchy, the circular analogue of the Cauchy and a heavier-tailed alternative to the von Mises. With mean direction mu and mean-resultant length rho in [0, 1),

f(theta; mu, rho) = (1 - rho^2) / (2 pi (1 + rho^2 - 2 rho cos(theta - mu))),

uniform on the circle at rho = 0 and increasingly peaked at mu as rho -> 1. Its first trigonometric moment is exactly rho e^{i mu}, so the mean direction and concentration are estimated in closed form from the mean resultant (the circular analogue of the sample mean). It samples exactly: rho corresponds to wrapping a Cauchy of scale gamma = -log rho.

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

class WrappedCauchyDistribution(mu, rho, name=None, keys=None)

Bases: SequenceEncodableProbabilityDistribution

Wrapped Cauchy distribution with mean direction mu and concentration rho in [0, 1).

Parameters:

• mu (float)

• rho (float)

• name (str | None)

• keys (str | None)

density(x)

Return the probability density at a single angle (radians).

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

classmethod compute_capabilities()

Describe backend support for generated wrapped-Cauchy kernels.

classmethod compute_declaration()

Return the structured compute declaration for wrapped Cauchy distributions.

static backend_legacy_sufficient_statistics(x, params, engine)

Per-row circular moments in accumulator order (sum_cos, sum_sin, count).

Parameters:

• x (Any)

• params (dict[str, Any])

• engine (Any)

Return type:

tuple[Any, …]

static backend_log_density_from_params(cos_t, sin_t, cos_mu, sin_mu, rho, engine)

Engine-neutral wrapped-Cauchy log-density from pre-computed observation/parameter trig.

Parameters:

• cos_t (Any)

• sin_t (Any)

• cos_mu (Any)

• sin_mu (Any)

• rho (Any)

• engine (Any)

Return type:

Any

backend_seq_log_density(x, engine)

Engine-neutral vectorized log-density for encoded (cos, sin) data.

Parameters:

• x (Any)

• engine (Any)

Return type:

Any

classmethod backend_stacked_params(dists, engine)

Stacked wrapped-Cauchy parameters (trig computed host-side) for a homogeneous mixture kernel.

Parameters:

• dists (Sequence[WrappedCauchyDistribution])

• engine (Any)

Return type:

dict[str, Any]

classmethod backend_stacked_log_density(x, params, engine)

Return an (n, k) matrix of wrapped-Cauchy log densities.

Parameters:

• x (Any)

• params (dict[str, Any])

• engine (Any)

Return type:

Any

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)

Stacked circular moments (sum_cos, sum_sin, count) using engine-resident arrays.

Parameters:

• x (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:

WrappedCauchySampler

estimator(pseudo_count=None)

Return a closed-form (mean-resultant) estimator for mu and rho.

Parameters:

pseudo_count (float | None)

Return type:

WrappedCauchyEstimator

dist_to_encoder()

Return the data encoder used by this distribution (cos/sin of the angle).

Return type:

WrappedCauchyDataEncoder

class WrappedCauchySampler(dist, seed=None)

Bases: DistributionSampler

Draw angles by wrapping a Cauchy of scale -log rho around the circle.

Parameters:

• dist (WrappedCauchyDistribution)

• seed (int | None)

sample(size=None)

Draw one angle or an array of iid angles.

Parameters:

size (int | None)

Return type:

float | ndarray

class WrappedCauchyAccumulator(name=None, keys=None)

Bases: SequenceEncodableStatisticAccumulator

Accumulate the weighted circular resultant (sum cos, sum sin, count).

Parameters:

• name (str | None)

• keys (str | None)

update(x, weight, estimate)

Accumulate one weighted circular resultant contribution.

Parameters:

• x (float)

• weight (float)

• estimate (WrappedCauchyDistribution | None)

Return type:

None

initialize(x, weight, rng)

Initialize statistics from one angle.

Parameters:

• x (float)

• weight (float)

• rng (RandomState | None)

Return type:

None

seq_update(x, weights, estimate)

Accumulate circular-resultant statistics from encoded cos/sin values.

Parameters:

• x (tuple[ndarray, ndarray])

• weights (ndarray)

• estimate (Any)

Return type:

None

seq_initialize(x, weights, rng)

Initialize statistics from encoded angles.

Parameters:

• x (tuple[ndarray, ndarray])

• weights (ndarray)

• rng (RandomState | None)

Return type:

None

combine(suff_stat)

Merge another wrapped-Cauchy sufficient-statistic tuple.

Parameters:

suff_stat (tuple[float, float, float])

Return type:

WrappedCauchyAccumulator

value()

Return cosine sum, sine sum, and total weight.

Return type:

tuple[float, float, float]

from_value(x)

Replace accumulator contents from circular-resultant statistics.

Parameters:

x (tuple[float, float, float])

Return type:

WrappedCauchyAccumulator

key_merge(stats_dict)

Merge keyed statistics into stats_dict when keys are configured.

Parameters:

stats_dict (dict[str, Any])

Return type:

None

key_replace(stats_dict)

Replace this accumulator from keyed statistics when available.

Parameters:

stats_dict (dict[str, Any])

Return type:

None

acc_to_encoder()

Return the encoder used by this accumulator.

Return type:

WrappedCauchyDataEncoder

class WrappedCauchyAccumulatorFactory(name=None, keys=None)

Bases: StatisticAccumulatorFactory

Factory for WrappedCauchyAccumulator.

Parameters:

• name (str | None)

• keys (str | None)

make()

Create a fresh wrapped-Cauchy accumulator.

Return type:

WrappedCauchyAccumulator

class WrappedCauchyEstimator(rho_max=1.0 - 1.0e-8, name=None, keys=None)

Bases: ParameterEstimator

Estimate mu and rho from the mean resultant (the first trigonometric moment).

Parameters:

• rho_max (float)

• name (str | None)

• keys (str | None)

accumulator_factory()

Return an accumulator factory for circular-resultant statistics.

Return type:

WrappedCauchyAccumulatorFactory

estimate(nobs, suff_stat)

Estimate mean direction and concentration from the mean resultant.

Parameters:

• nobs (float | None)

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

Return type:

WrappedCauchyDistribution

class WrappedCauchyDataEncoder

Bases: DataSequenceEncoder

Encode angles as their cosine and sine.

seq_encode(x)

Encode angles as cosine and sine arrays.

Parameters:

x (Sequence[float])

Return type:

tuple[ndarray, ndarray]