Module hvg 

Highly-variable-gene (HVG) selection.

Two surfaces:

• select_hvg / select_hvg_with_indices / select_hvg_by_stats — dense-matrix scoring via NB dispersion trend (σ²(μ) = μ + φ(μ)·μ²), ranking genes by excess dispersion above the trend.
• select_hvg_streaming — sparse streaming wrapper that computes per-gene (mean, variance) of raw counts directly from CSC chunks (one accumulator per block of columns, merged in block order, so the sums do not depend on the thread schedule), then delegates to select_hvg_by_stats.

Used by senna and chickpea to reweight the random-projection basis so the sketch geometry reflects variable biology rather than housekeeping signal.

Structs

HvgCliArgs

Shared CLI args for HVG gating of the random projection.

HvgSelection

HVG selection result used by SVD / topic / indexed-topic / joint-* pipelines to subset or weight the feature axis.

MustTrainFeatures

A force-include list of feature names loaded from --must-train-features: features that must enter the fit whether or not they make the HVG cut.

Functions

load_must_train

Load the --must-train-features list, but only when a feature selection is actually running.

load_must_train_union

load_must_train over the union of several lists — an explicit force-train list plus, say, the marker panel the run will later be annotated with. Same no-op guard: with selection off, nothing can be promoted, so say so rather than appear to work.

select_hvg

Select top N highly variable genes by NB excess dispersion.

select_hvg_by_stats

Select top-N HVG indices from pre-computed per-gene means and variances. Returns indices sorted ascending.

select_hvg_streaming

Stream cells through the sparse backend to compute per-gene mean and variance of raw expression, then select the top n_features HVGs via the shared NB-trend scoring routine.

select_hvg_with_indices

Select HVGs and return both the subset matrix and the selected indices.

union_indices

Merge extra into selected in place (both become ascending + deduped). Returns how many indices were genuinely added.