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 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

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.

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

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.

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

This is the lowest-level driver. Pass NoGuard to get the unguarded behavior; most callers should prefer the convenience wrappers refine_with_candidates / refine_with_proposer / refine_with_proposer_guarded.

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.