Module dc_poisson 

Degree-corrected Poisson refinement core.

Shared Poisson-scoring machinery for top-down multi-level refinement. Given per-entity sparse profiles (gene sums or a dense projection) and current group labels, refinement reassigns entities between groups by scoring moves under a Poisson likelihood with size-factor offsets. Candidate-set construction is delegated to CandidateProposer so different front-ends (cross-batch BBKNN, spatial KNN graph, …) can plug in their own neighborhood definition.

The partition handed in is kept as a partition: refinement makes its blocks purer without choosing how many there are or how large. Scores are built so that a block is not preferred for being large (see DcPoissonStats), an entity moves only on evidence beyond the noise of the block estimates, and member-count limits (RefineParams) keep every block near its starting size, small blocks trading members rather than losing them.

The name “DC-Poisson” is deliberate: we are not inferring a stochastic block model — the blocks are given externally (by a prior coarsening step) and we only score membership moves. Compare to the full DC-SBM where blocks themselves are latent variables.

Entry points:

• refine_with_candidates — lowest-level sweep driver given pre-built candidates.
• refine_with_proposer — generic driver that first asks a CandidateProposer.

See the BbknnProposer in refine_multilevel for the data_beans::alg front-end, and pinto’s GraphProposer for the spatial-graph front-end.

Structs

DcPoissonStats

Sufficient statistics with cached log quantities for O(K · nnz(row)) scoring.

NoGuard

Trivial guard that accepts every move. Zero-cost default used by the unguarded refine_with_candidates and refine_with_proposer.

Profiles

Sparse row-per-entity profile, owned by the refinement pass.

RefineContext

Shared sweep-driver context bundling the readonly inputs that every refine_with_* variant needs. Kept as a struct so the driver fns don’t exceed clippy’s argument-count threshold.

RefineParams

Parameters controlling the refinement pass.

Enums

FeatureWeighting

Per-feature weighting applied to the sparse profile before DC-Poisson scoring. All variants multiply each nonzero entry y_{e,f} by a scalar w_f and recompute per-row size factors; only the formula for w_f differs.

ProfileSource

Feature representation used to score entity → block moves.

Constants

BATCH_FACTOR_BOUND

Largest batch factor, and the reciprocal of the smallest.

BATCH_FACTOR_PSEUDO_COUNT

Pseudo-count κ in the observed and the expected count behind a batch factor (see Profiles::rescale_batches).

LOG_EPS

Additive floor to keep ln(.) finite when a block or feature has zero mass.

Traits

CandidateProposer

Propose candidate group labels each entity may move into on one sweep.

MoveGuard

Veto individual moves after they’ve been picked by the sweep.

Functions

argmax_log_restricted

Argmax over allowed indices.

argmax_log_restricted_from

Argmax over allowed indices that leaves current only for a strictly better block: a tie with the current label (an entity with no evidence scores every block alike) is not a move. With current outside allowed, ties go to the first allowed index.

compact_labels

Compact a label vector to dense 0..K ids, preserving relative order of first appearance. Returns the new labels and the new K. Generic over the key type so it serves both plain group ids (usize) and composite keys (e.g. (child, parent) pairs in project_to_refinement).

compute_log_probs_restricted

Log-probability of placing entity e into each of the allowed blocks.

compute_sibling_sets

For each entity, siblings at level = groups at level sharing the same parent group at level + 1.

intersect_with_siblings_fallback

Intersect a per-entity sibling set with a per-entity neighbor-group set, with sibling fallback when the intersection is empty and guaranteed inclusion of the entity’s current label so staying put is always a legal move.

refine_with_candidates

Unguarded variant of refine_with_candidates_guarded.

refine_with_candidates_guarded

Refine labels in place for one level by running Gibbs + greedy sweeps over profiles with the given pre-built candidates and a custom MoveGuard. Returns total accepted moves across all sweeps.

refine_with_proposer

Unguarded generic driver: ask proposer for candidates, then run the sweep with NoGuard.

refine_with_proposer_guarded

Generic driver: ask proposer for candidates, then run the guarded sweep.

sample_categorical_log_restricted

Gumbel-max categorical sampling over the allowed slots of log_probs, skipping non-finite entries. Falls back to current (the entity’s present label — always a legal “move”) when no allowed slot is finite, so a degenerate score vector can never produce an out-of-range label.