mixle.stats.rankings.ewens module

Ewens distribution over permutations – the canonical cycle-structure (random-permutation) law.

A permutation is weighted by its number of cycles:

p(sigma) = theta^{cycles(sigma)} / Z, Z = theta (theta + 1) … (theta + n - 1) = Gamma(theta+n)/Gamma(theta).

theta = 1 is uniform over the n! permutations; theta -> 0 concentrates on single n-cycles (few cycles); large theta concentrates on the identity (every point a fixed cycle). This is the permutation form of the Ewens sampling formula (population genetics, random-permutation theory); its induced partition by cycle sizes is what ChineseRestaurantProcessDistribution models.

Sufficient statistic: the cycle count, computed from the shared Cayley kernel (cycles = n - cayley_distance(sigma, identity)). Sampling is an exact numba Chinese-restaurant / Feller construction; theta is fit by matching the mean cycle count E[cycles] = sum_i theta/(theta+i).

Data type: List[int] – a permutation of 0..n-1 read as a function i -> sigma[i] (cycles of that map are what the model scores).

class EwensDistribution(dim, theta=1.0, name=None, keys=None)

Bases: SequenceEncodableProbabilityDistribution

Ewens distribution over permutations of 0..n-1 with cycle-weight parameter theta > 0.

Parameters:

• dim (int)

• theta (float)

• name (str | None)

• keys (str | None)

classmethod compute_capabilities()

Declare the NumPy and numba execution path used by Ewens kernels.

density(x)

Return the probability of one permutation.

Parameters:

x (Sequence[int])

Return type:

float

log_density(x)

Return the log-probability of one permutation.

Parameters:

x (Sequence[int])

Return type:

float

seq_log_density(x)

Return vectorized log-probabilities for encoded permutations.

Parameters:

x (ndarray)

Return type:

ndarray

sampler(seed=None)

Return an exact Ewens permutation sampler.

Parameters:

seed (int | None)

Return type:

EwensSampler

estimator(pseudo_count=None)

Return a cycle-count moment estimator for this dimension.

Parameters:

pseudo_count (float | None)

Return type:

EwensEstimator

dist_to_encoder()

Return the permutation encoder used by vectorized methods.

Return type:

EwensDataEncoder

class EwensSampler(dist, seed=None)

Bases: DistributionSampler

Exact Ewens draws via the numba Chinese-restaurant construction.

Parameters:

• dist (EwensDistribution)

• seed (int | None)

sample(size=None)

Draw one permutation or size iid permutations.

Parameters:

size (int | None)

Return type:

list[int] | list[list[int]]

class EwensAccumulator(dim, keys=None)

Bases: SequenceEncodableStatisticAccumulator

Accumulate the total (weighted) cycle count and observation weight.

Parameters:

• dim (int)

• keys (str | None)

update(x, weight, estimate)

Update cycle-count statistics from one weighted permutation.

Parameters:

• x (Sequence[int])

• weight (float)

• estimate (Any)

Return type:

None

initialize(x, weight, rng)

Initialize cycle-count statistics from one weighted permutation.

Parameters:

• x (Sequence[int])

• weight (float)

• rng (RandomState | None)

Return type:

None

seq_update(x, weights, estimate)

Update cycle-count statistics from encoded permutations.

Parameters:

• x (ndarray)

• weights (ndarray)

• estimate (Any)

Return type:

None

seq_initialize(x, weights, rng)

Initialize cycle-count statistics from encoded permutations.

Parameters:

• x (ndarray)

• weights (ndarray)

• rng (RandomState | None)

Return type:

None

combine(suff_stat)

Merge cycle-count totals and observation weight from another accumulator.

Return type:

EwensAccumulator

value()

Return total weighted cycle count and total observation weight.

from_value(x)

Restore accumulator state from value output.

Return type:

EwensAccumulator

key_merge(stats_dict)

Merge this accumulator into stats_dict under its configured key.

Parameters:

stats_dict (dict[str, Any])

Return type:

None

key_replace(stats_dict)

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

Parameters:

stats_dict (dict[str, Any])

Return type:

None

acc_to_encoder()

Return the encoder compatible with Ewens cycle-count statistics.

Return type:

EwensDataEncoder

class EwensAccumulatorFactory(dim, keys=None)

Bases: StatisticAccumulatorFactory

Create accumulators for Ewens cycle-count statistics.

Parameters:

• dim (int)

• keys (str | None)

make()

Create an empty Ewens accumulator.

Return type:

EwensAccumulator

class EwensEstimator(dim, theta=None, name=None, keys=None)

Bases: ParameterEstimator

Fit theta by matching the mean cycle count E[cycles] = sum_i theta/(theta+i).

Parameters:

• dim (int)

• theta (float | None)

• name (str | None)

• keys (str | None)

accumulator_factory()

Return a factory for Ewens sufficient-statistic accumulators.

Return type:

EwensAccumulatorFactory

estimate(nobs, suff_stat)

Estimate theta by matching the accumulated mean cycle count.

Parameters:

nobs (float | None)

Return type:

EwensDistribution

class EwensDataEncoder(dim=None)

Bases: DataSequenceEncoder

Encode a sequence of permutations of 0,…,n-1 into an (N, n) integer array.

Parameters:

dim (int | None)

seq_encode(x)

Validate and encode permutations as a dense integer matrix.

Parameters:

x (Sequence[Sequence[int]])

Return type:

ndarray