Module gene_weighting 

Per-gene weighting helpers used by reporting / annotation pipelines.

compute_nb_fisher_weights derives bounded (0, 1] weights from the NB dispersion trend (see nb_dispersion) — high-mean / high-dispersion genes get attenuated, low-mean genes recover w_g = 1 in the Poisson limit. The same formula is applied inside DC-Poisson refinement so clustering and reporting stay consistent.

apply_gene_weights row-scales a (num_genes × K) matrix in place.

Originally lived in pinto/src/util/common.rs; moved here so senna / chickpea / other consumers don’t have to duplicate the implementation.

Functions

apply_gene_weights

Scale each row of sum_gk by its corresponding entry of weights. weights.len() must equal sum_gk.nrows().

compute_nb_fisher_weights

Fit the NB mean-variance trend on data_vec and return per-gene Fisher-info weights in row order (same as data_vec.row_names()).

compute_nb_fisher_weights_coarsened

Same as compute_nb_fisher_weights, but at the coarse feature level after FeatureCoarsening aggregation. Streams cells, coarsens each block via aggregate_sparse_csc (sum within group), then fits a fresh NB dispersion trend at D_coarse and computes per-meta-gene Fisher weights.

fisher_weights_from_pseudobulk

Fisher weights fitted on pseudobulks rather than on cells.

fisher_weights_from_stats

Fit a fresh NB dispersion trend on stats and return per-feature Fisher-info weights w_d ∈ (0, 1]. n_entities is the count divisor used to compute the mean entity size factor s̄ (typically the number of cells or pseudobulks the stats were accumulated over).

load_fisher_weights

Convenience wrapper: load {prefix}.fisher_weights.parquet. Returns Ok(None) when the file doesn’t exist so callers can fall back to recomputing via compute_nb_fisher_weights.

load_fisher_weights_coarse

Convenience wrapper: load {prefix}.fisher_weights_coarse.parquet. Returns Ok(None) when the file doesn’t exist (older models trained before coarse weights were saved).

load_per_gene_weights

Load a per-gene weight vector previously written by save_per_gene_weights. Returns (gene_names, weights).

save_fisher_weights

Convenience wrapper: write per-gene weights to the conventional {out_prefix}.fisher_weights.parquet path used by senna topic and chickpea fit-topic. Downstream consumers (e.g. senna annotate) look for this filename to reload weights instead of re-scanning all cells.

save_fisher_weights_coarse

Save coarse-resolution NB-Fisher weights computed at the encoder/ decoder’s D_coarse (post-feature-coarsening). Stored at {prefix}.fisher_weights_coarse.parquet keyed on synthetic coarse_<i> axis ids since coarse meta-genes have no biological names. Loaded by senna predict / senna eval-topic to re-attach the same per-feature multinomial-loss weights at inference.

save_per_gene_weights

Save a per-gene weight vector as a single-column parquet keyed on gene name. The output path is fully specified — callers control the filename. For the standard {out}.fisher_weights.parquet convention used by senna and chickpea, see save_fisher_weights.

Type Aliases

GeneWeights

(gene_names, per-gene weights) returned by the per-gene weight loaders.