mixle.stats.rankings.low_rank_permutation module

Low-rank assignment (first-order Fourier) model over permutations.

A permutation Gibbs model that scores an ordering by a low-rank item-by-rank score matrix:

p(sigma) = exp( sum_r S[sigma[r], r] ) / Z, S = U V^T (rank r << n), Z = permanent(exp(S)).

This is the maximum-entropy distribution matching first-order (item-at-rank) marginals – the first-order term of the Fourier / coset expansion on the symmetric group – and the low-rank factorization S = U V^T is the structured, O(n r)-parameter version of the full MatchingDistribution. The normalizer is a permanent (#P-hard), so it is computed exactly by a numba Ryser kernel for n <= max_exact and approximated by a numba Sinkhorn / Bethe permanent beyond that (documented approximation). Fitting is a Sinkhorn-marginal gradient ascent on U, V toward the empirical item-by-rank marginals.

Data type: List[int] – a full ordering, a permutation of 0..n-1 with x[r] the item at rank r (best first).

class LowRankPermutationDistribution(u, v, name=None, keys=None, max_exact=12, sinkhorn_iter=200)

Bases: SequenceEncodableProbabilityDistribution

Permutation Gibbs model with a low-rank item-by-rank score matrix S = U V^T.

Parameters:

• u (np.ndarray)

• v (np.ndarray)

• name (str | None)

• keys (str | None)

• max_exact (int)

• sinkhorn_iter (int)

classmethod compute_capabilities()

Declare the NumPy and numba execution path used by low-rank permutation kernels.

density(x)

Return the probability of one ordering.

Parameters:

x (Sequence[int])

Return type:

float

log_density(x)

Return the log-probability of one ordering.

Parameters:

x (Sequence[int])

Return type:

float

seq_log_density(x)

Return vectorized log-probabilities for encoded orderings.

Parameters:

x (ndarray)

Return type:

ndarray

marginals()

Model first-order marginals P[item, rank] (Sinkhorn doubly-stochastic transport plan).

Return type:

ndarray

sampler(seed=None)

Return a Metropolis sampler for this low-rank assignment model.

Parameters:

seed (int | None)

Return type:

LowRankPermutationSampler

estimator(pseudo_count=None)

Return a Sinkhorn-marginal estimator with this dimension and rank.

Parameters:

pseudo_count (float | None)

Return type:

LowRankPermutationEstimator

dist_to_encoder()

Return the full-ranking encoder used by vectorized methods.

Return type:

LowRankPermutationDataEncoder

class LowRankPermutationSampler(dist, seed=None, burn=2000, thin=20)

Bases: DistributionSampler

Draw orderings via a numba Metropolis sampler on the assignment scores.

Parameters:

• dist (LowRankPermutationDistribution)

• seed (int | None)

• burn (int)

• thin (int)

sample(size=None)

Draw one ordering or size approximate iid orderings.

Parameters:

size (int | None)

Return type:

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

class LowRankPermutationAccumulator(dim, keys=None)

Bases: SequenceEncodableStatisticAccumulator

Accumulate the item-by-rank count matrix C[item, rank] – the first-order sufficient statistic.

Parameters:

• dim (int)

• keys (str | None)

update(x, weight, estimate)

Update item-by-rank counts from one weighted ordering.

Parameters:

• x (Sequence[int])

• weight (float)

• estimate (Any)

Return type:

None

initialize(x, weight, rng)

Initialize item-by-rank counts from one weighted ordering.

Parameters:

• x (Sequence[int])

• weight (float)

• rng (RandomState | None)

Return type:

None

seq_update(x, weights, estimate)

Update item-by-rank counts from encoded orderings.

Parameters:

• x (ndarray)

• weights (ndarray)

• estimate (Any)

Return type:

None

seq_initialize(x, weights, rng)

Initialize item-by-rank counts from encoded orderings.

Parameters:

• x (ndarray)

• weights (ndarray)

• rng (RandomState | None)

Return type:

None

combine(suff_stat)

Merge observation weight and item-by-rank count statistics.

Return type:

LowRankPermutationAccumulator

value()

Return accumulated observation weight and item-by-rank counts.

from_value(x)

Restore accumulator state from value output.

Return type:

LowRankPermutationAccumulator

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 item-by-rank sufficient statistics.

Return type:

LowRankPermutationDataEncoder

class LowRankPermutationAccumulatorFactory(dim, keys=None)

Bases: StatisticAccumulatorFactory

Create accumulators for low-rank permutation sufficient statistics.

Parameters:

• dim (int)

• keys (str | None)

make()

Create an empty low-rank permutation accumulator.

Return type:

LowRankPermutationAccumulator

class LowRankPermutationEstimator(dim, rank=2, max_exact=12, sinkhorn_iter=200, max_iter=300, lr=0.5, name=None, keys=None)

Bases: ParameterEstimator

Fit U, V by Sinkhorn-marginal gradient ascent toward the empirical item-by-rank marginals.

Parameters:

• dim (int)

• rank (int)

• max_exact (int)

• sinkhorn_iter (int)

• max_iter (int)

• lr (float)

• name (str | None)

• keys (str | None)

accumulator_factory()

Return a factory for low-rank permutation sufficient-statistic accumulators.

Return type:

LowRankPermutationAccumulatorFactory

estimate(nobs, suff_stat)

Estimate low-rank score factors from item-by-rank marginal counts.

Parameters:

nobs (float | None)

Return type:

LowRankPermutationDistribution

class LowRankPermutationDataEncoder(dim=None)

Bases: DataSequenceEncoder

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

Parameters:

dim (int | None)

seq_encode(x)

Validate and encode full orderings as a dense integer matrix.

Parameters:

x (Sequence[Sequence[int]])

Return type:

ndarray