mixle.stats.rankings.spearman_rho module

Spearman-rho distribution over full item orderings.

Observations use the ranking convention shared by the other ranking families: x[rank] = item. The location parameter is a (possibly fractional) mean rank vector, sigma[item] = expected rank. Use ItemOrdering and RankVector when a boundary needs to make that distinction explicit.

For an ordering x, let r be its inverse rank vector. Then

p(x) = exp(-rho * sum_item (r[item] - sigma[item])**2) / Z.

The normalizer is the permanent of the rank-by-item log-weight matrix. It is computed by exact subset dynamic programming under an explicit dimension budget; no factorial permutation array is materialized or globally cached. Sampling uses exact conditional permanents and enumeration uses lazy k-best assignment search.

class ItemOrdering(values)

Bases: Sequence[int]

A permutation whose entry at each rank is the item occupying that rank.

Parameters:

values (tuple[int, ...])

to_rank_vector()

Return the inverse permutation, indexed by item.

Return type:

RankVector

class RankVector(values)

Bases: Sequence[int]

A permutation whose entry for each item is that item’s rank.

Parameters:

values (tuple[int, ...])

to_item_ordering()

Return the inverse permutation, indexed by rank.

Return type:

ItemOrdering

class SpearmanRankingFitDiagnostics(concentration_algorithm, converged, iterations, boundary_solution, regularized, pseudo_count)

Bases: object

Concentration-fit and regularization evidence attached to an estimate.

Parameters:

• concentration_algorithm (str)

• converged (bool)

• iterations (int)

• boundary_solution (bool)

• regularized (bool)

• pseudo_count (float)

class SpearmanRankingDistribution(sigma, rho=1.0, name=None, keys=None, max_dim=_DEFAULT_MAX_DIM, fit_diagnostics=None, *, _sigma_already_centered=False, _sigma_raw_scale_hint=None)

Bases: SequenceEncodableProbabilityDistribution

Exact finite Spearman law over item orderings under a dimension budget.

Known limitation: direct construction from a raw location vector (this class’s sigma argument – see the module docstring’s “possibly fractional mean rank vector”) whose entries share an extremely large common offset – beyond _TRUSTED_SIGMA_RAW_SCALE_CEILING in spearman_rho.py, roughly the range of a 32-bit integer (~2.1e9) – succeeds here, but the one-time float64 cancellation __init__ performs while centering it can leave a residual that a later restore (__pysp_setstate__) cannot always distinguish from genuine state corruption, and may then reject with a ValueError even though it was built validly. The original, pre-centering magnitude is not recoverable from the restored, already-centered state, so this is an accepted, documented limit rather than a bug to silently work around – see the comment above _validate_location in this module for the full reasoning and exact boundary.

Parameters:

• sigma (Sequence[float] | np.ndarray)

• rho (float)

• name (str | None)

• keys (str | None)

• max_dim (int)

• fit_diagnostics (SpearmanRankingFitDiagnostics | None)

• _sigma_already_centered (bool)

• _sigma_raw_scale_hint (float | None)

classmethod compute_capabilities()

Declare generated NumPy and Torch scoring support.

classmethod compute_declaration()

Return the generated-compute declaration.

static backend_legacy_sufficient_statistics(x, params, engine)

Return row-wise count and item-indexed rank-vector statistics.

Parameters:

• x (Any)

• params (dict[str, Any])

• engine (Any)

Return type:

tuple[Any, …]

static backend_log_density_from_params(x, sigma, rho, log_const, engine)

Score item orderings after explicit conversion to rank vectors.

Callers arrive under two shape conventions. backend_seq_log_density passes the natural ones – ranks (n, d) against a single sigma (d,). The generated scorer in mixle.stats.compute.declarations pre-aligns both sides instead: data picks up a component axis ((n, 1, d)) and every parameter a leading row axis ((1, k, d)), so the two already broadcast. Inserting a component axis unconditionally, as this did, double-counts it on that path and returns an (n, 1, k) score where the contract is (n, k). Only add the axis when the ranks really are still two-dimensional.

Parameters:

• x (Any)

• sigma (Any)

• rho (Any)

• log_const (Any)

• engine (Any)

Return type:

Any

property sigma: ndarray

Return an ownership-safe copy of the canonical mean rank vector.

density(x)

Return the probability of an item ordering.

Parameters:

x (Sequence[int] | ItemOrdering)

Return type:

float

log_density(x)

Return the log-probability of one x[rank] = item ordering.

Parameters:

x (Sequence[int] | ItemOrdering)

Return type:

float

seq_log_density(x)

Return vectorized log-probabilities for item orderings.

Parameters:

x (ndarray)

Return type:

ndarray

backend_seq_log_density(x, engine)

Engine-neutral vectorized scoring for encoded item orderings.

Parameters:

• x (ndarray)

• engine (Any)

Return type:

Any

classmethod backend_stacked_params(dists, engine)

Stack equal-dimensional Spearman parameters.

Parameters:

• dists (Sequence[SpearmanRankingDistribution])

• engine (Any)

Return type:

dict[str, Any]

classmethod backend_stacked_log_density(x, params, engine)

Return an observation-by-component score matrix.

Parameters:

• x (ndarray)

• params (dict[str, Any])

• engine (Any)

Return type:

Any

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)

Return component-stacked item-indexed rank-vector statistics.

Parameters:

• x (ndarray)

• weights (Any)

• params (dict[str, Any])

• engine (Any)

Return type:

tuple[Any, Any]

sampler(seed=None)

Return an exact conditional-permanent sampler.

Parameters:

seed (int | None)

Return type:

SpearmanRankingSampler

estimator(pseudo_count=None)

Return an estimator preserving the dimension and resource budget.

Parameters:

pseudo_count (float | None)

Return type:

SpearmanRankingEstimator

dist_to_encoder()

Return the item-ordering encoder.

Return type:

SpearmanRankingDataEncoder

enumerator()

Return a lazy descending-probability enumerator.

Return type:

SpearmanRankingEnumerator

support_size()

Return the number of full item orderings.

Return type:

int

class SpearmanRankingEnumerator(dist)

Bases: DistributionEnumerator

Enumerate item orderings by increasing rank-to-item assignment cost.

Parameters:

dist (SpearmanRankingDistribution)

class SpearmanRankingSampler(dist, seed=None)

Bases: DistributionSampler

Draw exact Spearman item orderings using conditional permanents.

Parameters:

• dist (SpearmanRankingDistribution)

• seed (int | None)

sample(size=None, *, batched=True)

Draw one item ordering or size iid item orderings.

Parameters:

• size (int | None)

• batched (bool)

Return type:

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

class SpearmanRankingAccumulator(dim, name=None, keys=None)

Bases: SequenceEncodableStatisticAccumulator

Accumulate item-indexed rank-vector sums from item orderings.

Parameters:

• dim (int)

• name (str | None)

• keys (str | None)

update(x, weight, estimate)

Update from one item ordering.

Parameters:

• x (Sequence[int] | ItemOrdering)

• weight (float)

• estimate (SpearmanRankingDistribution | None)

Return type:

None

initialize(x, weight, rng)

Initialize from one item ordering.

Parameters:

• x (Sequence[int])

• weight (float)

• rng (RandomState | None)

Return type:

None

seq_update(x, weights, estimate)

Update from encoded item orderings.

Parameters:

• x (ndarray)

• weights (ndarray)

• estimate (SpearmanRankingDistribution | None)

Return type:

None

seq_initialize(x, weights, rng)

Initialize from encoded item orderings.

Parameters:

• x (ndarray)

• weights (ndarray)

• rng (RandomState | None)

Return type:

None

combine(suff_stat)

Merge validated rank-vector statistics.

Parameters:

suff_stat (tuple[float, ndarray])

Return type:

SpearmanRankingAccumulator

value()

Return an ownership-safe sufficient-statistic snapshot.

Return type:

tuple[float, ndarray]

from_value(x)

Restore validated rank-vector statistics.

Parameters:

x (tuple[float, ndarray])

Return type:

SpearmanRankingAccumulator

acc_to_encoder()

Return an encoder with the matching item count.

Return type:

SpearmanRankingDataEncoder

class SpearmanRankingAccumulatorFactory(dim, name=None, keys=None)

Bases: StatisticAccumulatorFactory

Create Spearman ranking accumulators.

Parameters:

• dim (int)

• name (str | None)

• keys (str | None)

make()

Return a fresh accumulator.

Return type:

SpearmanRankingAccumulator

class SpearmanRankingEstimator(dim, rho=None, pseudo_count=None, suff_stat=None, name=None, keys=None, max_rho=1.0e6, max_dim=_DEFAULT_MAX_DIM)

Bases: ParameterEstimator

Estimate consensus mean ranks and nonnegative Spearman concentration.

Parameters:

• dim (int)

• rho (float | None)

• pseudo_count (float | None)

• suff_stat (tuple[float, np.ndarray] | None)

• name (str | None)

• keys (str | None)

• max_rho (float)

• max_dim (int)

accumulator_factory()

Return a factory for item-ordering sufficient statistics.

Return type:

SpearmanRankingAccumulatorFactory

estimate(nobs, suff_stat)

Estimate a distribution from validated item-indexed rank sums.

Parameters:

• nobs (float | None)

• suff_stat (tuple[float, ndarray])

Return type:

SpearmanRankingDistribution

class SpearmanRankingDataEncoder(dim=None)

Bases: DataSequenceEncoder

Validate and encode full x[rank] = item orderings.

Parameters:

dim (int | None)

seq_encode(x)

Return a dense, support-checked item-ordering matrix.

Parameters:

x (Sequence[Sequence[int] | ItemOrdering])

Return type:

ndarray

row_count(x)

Return the number of encoded item orderings.

Parameters:

x (ndarray)

Return type:

int