Struct Profiles 

pub struct Profiles {
    pub rows: Vec<Vec<(u32, f32)>>,
    pub size_factor: Vec<f32>,
    pub num_entities: usize,
    pub num_features: usize,
}

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

Materialized from either a sparse gene-sum format (from_gene_sums) or a projected centroid matrix (from_projection). Values are stored sorted by feature index within each row so downstream accumulators can rely on the invariant.

Fields

rows: Vec<Vec<(u32, f32)>>

size_factor: Vec<f32>

num_entities: usize

num_features: usize

Implementations

impl Profiles

pub fn from_gene_sums( gene_sums: &[Vec<(usize, f32)>], num_features: usize, ) -> Self

pub fn from_projection( basis: &DMatrix<f32>, entity_to_cells: &[Vec<usize>], ) -> Self

Build profiles from a dense projection.

basis is proj_dim × num_cells; each entity profile is the sum of basis columns over the cells constituting it. Gene weighting is not applied — projection dims aren’t gene-aligned.

The Poisson score needs nonnegative profiles, so the accumulated per-dimension sums must be >= 0 — a signed basis (e.g. a raw random projection) is rejected loudly rather than silently truncated.

pub fn weight_by_vec(&mut self, w: &[f32])

In-place reweighting by a caller-supplied per-feature weight vector. Used by Profiles::apply_feature_weighting for the NB Fisher-info path.

pub fn rescale_batches(&mut self, batch: &[usize], strata: Option<&[usize]>)

Divide each entity’s features by its batch’s estimated factor, then recompute the size factors.

batch[e] is the batch of entity e. A batch effect multiplies a feature’s rate in every entity of the batch, so entities of one batch fit a block by how much of that batch it holds, whatever its content, and a refinement on the raw profiles sorts them by batch.

The factors δ are fitted to y_eg ~ Poisson(s_e · λ[c(e), g] · δ[b(e), g]), c(e) the stratum of the entity (strata; one stratum without it), by alternating λ_cg = Σ_{e ∈ c} y_eg / Σ_b T_bc δ_bg and δ_bg = (O_bg + κ) / (E_bg + κ), with T_bc the mass of batch b in stratum c, O_bg the batch’s count of the feature and E_bg = Σ_c T_bc λ_cg the count expected of its strata. Three things hold a factor near one, where an entity is left as it is:

• the pseudo-count κ (BATCH_FACTOR_PSEUDO_COUNT): a feature with a few counts in a batch says little about its factor;
• the replication: a batch of n entities gets δ^((n − 1) / n), and a batch of one entity, whose profile cannot be told from a factor, is not touched;
• a bound of BATCH_FACTOR_BOUND either way.

What the strata are for

Without strata the expected count is the pooled profile’s, and the fit takes every difference between a batch and the pool for a technical factor. That holds only when the batches have the same composition. A batch that is mostly one cell type has that type’s features scaled down, and the type no longer looks the same in two batches that hold different shares of it. With strata that follow the composition (a coarse grouping of the entities), a batch is compared with what its own mix of strata would show, and a type found in one batch only is compared with itself and left alone. Differences in composition within a stratum are still taken for a batch factor.

pub fn apply_feature_weighting(&mut self, method: FeatureWeighting)

Apply the chosen feature weighting in place.

FeatureWeighting::None is a no-op; FeatureWeighting::FisherInfoNb fits an NB dispersion trend from the current profiles and reweights each feature by 1 / (1 + π_f · s̄ · φ(μ_f)).

pub fn nb_fisher_weights(&self) -> Vec<f32>

Compute per-feature Fisher-info weights under an NB trend fit from the current profile contents. Returned vector has length num_features and is suitable for Profiles::weight_by_vec.