Struct FragmentLengthDistribution 

pub struct FragmentLengthDistribution { /* private fields */ }

Tracks the observed distribution of fragment lengths.

Implementations

impl FragmentLengthDistribution

pub fn new( alpha: f64, max_val: usize, prior_mu: f64, prior_sigma: f64, kernel_n: usize, kernel_p: f64, bin_size: usize, ) -> Self

Construct a distribution.

• alpha – total pseudo-count mass (linear space).
• max_val – maximum representable length.
• prior_mu – Gaussian prior mean; if <= 0, a uniform prior is used.
• prior_sigma – Gaussian prior standard deviation.
• kernel_n – binomial kernel trials; must be even (after binning).
• kernel_p – binomial kernel success probability.
• bin_size – internal length binning (use 1 for no binning).

The prior is what the distribution believes before seeing any data; a paired-end run quickly overwhelms it with observations, while a single-end run (which observes no fragment lengths at all) keeps it.

pub fn default_for_paired() -> Self

salmon’s default fragment-length distribution: pseudo-count 1.0, max length 1000, no Gaussian prior (uniform), kernel n=4, p=0.5.

A uniform prior for paired-end data because the observations will supply the shape; the prior only has to avoid ruling anything out.

pub fn max_val(&self) -> usize

Largest representable raw length.

pub fn min_val(&self) -> usize

Smallest observed length; 1 when nothing has been observed (the sentinel initial value is the last bin).

pub fn add_val(&self, len: usize, mass: f64)

Add mass (log space) for an observed fragment of length len, spreading it over the smoothing kernel. Lock-free; safe to call from multiple threads. (Must not race with cache.)

pub fn pmf(&self, len: usize) -> f64

Logged probability of observing a fragment of length len.

pub fn refresh_online(&self)

Rebuild the online log-PMF snapshot from the current histogram (one pass over the length bins, with a single tot_mass read so the snapshot is internally consistent). Call at mini-batch boundaries during the online phase; no-op once the final cache has been taken. Cheap relative to mapping a batch, and decouples per-fragment reads from the concurrent add_val writes so identical lengths read identical values.

pub fn online_snapshot(&self) -> Arc<Vec<f64>>

Cheap (one Arc clone) immutable handle to the current online log-PMF snapshot. Capture once per fragment and index by raw length: every transcript of a given length then reads an identical value even if another thread refreshes the shared snapshot meanwhile. Empty until the first refresh_online (the pre-burn-in window, where this term is not folded into the eq-class weight anyway).

pub fn online_cmf_snapshot(&self) -> Arc<Vec<f64>>

Cheap (one Arc clone) immutable handle to the current online log-CMF snapshot, the cumulative companion to online_snapshot. Capture once per fragment for the ambiguous (orphan / single-end) fragment-length probability and the proper-pair length-conditioning. Empty until the first refresh_online.

pub fn cmf(&self, len: usize) -> f64

Logged cumulative mass up to and including len.

The uncached path re-sums from zero each call, which is why the online phase uses the precomputed snapshot instead.

pub fn tot_mass(&self) -> f64

Total observed mass (log space).

pub fn mean(&self) -> f64

Mean observed length.

Σ l·mass / Σ mass, which in log space is one subtraction of the two running accumulators.

pub fn sd(&self) -> f64

Standard deviation of the observed length distribution, computed from the cached normalized PMF (call after cache).

Two passes — mean, then squared deviations — rather than the one-pass E[X²] − E[X]² form, which loses precision when the two terms are close.

pub fn cache(&mut self)

Freeze the distribution and precompute normalized PMF/CMF for fast, allocation-free lookup. Call once after updates have stopped.

After this, every lookup is an array index; before it, each one does atomic loads and (for the CMF) a running sum.

pub fn from_log_pmf(log_pmf: &[f64]) -> Self

Reconstruct a cached distribution directly from a (log-space) PMF, e.g. one serialized into a RAD header during a previous run. log_pmf is indexed by raw length over [0, log_pmf.len()). The CMF, conditional means, mean and sd are all re-derived from it via cache, so a reconstructed distribution is interchangeable with the original for every read-side use. The masses need not be pre-normalized — cache normalizes them — but a normalized PMF round-trips exactly.

This is what makes a RAD requant reproduce the original run: the exact distribution is restored rather than re-estimated.

pub fn log_pmf(&self) -> &[f64]

The cached, normalized log-PMF over [0, max_val]. Requires cache.

pub fn conditional_means(&self) -> Vec<f64>

Cumulative conditional means E[L | L ≤ i] over [0, max_val], i.e. salmon’s correctionFactorsFromMass (DistributionUtils.cpp): cm[i] = (Σ_{l≤i} l·pmf[l]) / (Σ_{l≤i} pmf[l]).

Read cm[i] as: given a transcript of length i, how long is a typical fragment it can host? Subtracting that from the reference length is the smoothed effective length — the transcript loses the tail where no fragment of typical length could start.

These are the per-length correction factors computeSmoothedEffectiveLengths subtracts from the reference length to get the base effective length. The ratio is invariant to the PMF normalization, so the cached (normalized) PMF gives the same values as salmon’s 100·exp(logPMF) mass. Requires cache.

Trait Implementations

impl Debug for FragmentLengthDistribution

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.