Struct RowSamplingMeasure 

pub struct RowSamplingMeasure { /* private fields */ }

A per-row sampling measure over n rows, normalized to sum to 1.

Built from a RowMetric via RowSamplingMeasure::from_metric. The weights are a proper probability measure (non-negative, finite, summing to 1) used for discovery/seeding oversampling only — see the module docs for the invariant that it touches no loss / gradient / criterion.

Implementations

impl RowSamplingMeasure

pub fn from_metric(metric: &RowMetric) -> Self

Build the enrichment measure from a RowMetric.

The per-row liveness is the Fisher mass tr(M_n) read from the metric’s validated PSD blocks. The result is normalized to a proper sampling measure. Degrades to the uniform measure (every row 1/n) when the metric is Euclidean, carries no usable mass (all rows ≤ 0), or yields any non-finite mass — never an error, mirroring RowMetric’s magic-by-default discipline.

This function reads only the metric’s geometry; it writes nothing into the metric, the loss, the gradient, or any criterion.

pub fn uniform(n: usize) -> Self

The uniform measure over n rows: every row weight 1 / n. The graceful fallback and the explicit “no behavioral harvest” measure.

pub fn from_masses( metric_provenance: MetricProvenance, masses: Vec<f64>, ) -> Self

Construct from raw per-row masses, normalizing to a proper measure. Falls back to uniform if the masses carry no usable signal.

Crate-visible so the two-tier harvest (gam_inference::harvest) can lift designed-subsample Fisher masses to a full-corpus measure through the same validation/normalization path.

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

The normalized per-row sampling weights (Σ == 1). Read-only; this is a sampling measure, never a loss weight.

pub fn provenance(&self) -> MeasureProvenance

The measure’s provenance — Uniform (graceful fallback / no harvest) or FisherMass (real behavioral enrichment).

pub fn n_rows(&self) -> usize

Number of rows the measure is defined over.

pub fn enrichment_order(&self, count: usize, seed: u64) -> Vec<usize>

Deterministic systematic-resampling enrichment ordering.

Returns a length-count vector of row indices drawn ∝ weights, using low-variance systematic resampling with a fixed, index-derived jitter — there is no clock randomness; the same (measure, count, seed) always yields the same ordering. Behaviorally-live rows therefore appear with multiplicity proportional to their Fisher mass, so a rare-but-live feature’s rows are oversampled relative to uniform.

Systematic resampling places count equally spaced pointers (j + u) / count, j = 0..count, against the cumulative weight CDF and emits the row each pointer lands in. The single offset u ∈ [0, 1) is a splitmix64-hash of seed (deterministic), giving an unbiased draw whose per-row expected count is count · weights[row] while guaranteeing every weight-≥ 1/count row appears at least once (the recall property the rare-feature control asserts).

The uniform fallback reproduces an even, deterministic round-robin over all rows — i.e. plain attention to every row, today’s behavior.

This ordering is consumed only by a discovery/seeding pass. The rows it names carry their ordinary, unmodified per-row objective.

Trait Implementations

impl Clone for RowSamplingMeasure

fn clone(&self) -> RowSamplingMeasure

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for RowSamplingMeasure

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

Formats the value using the given formatter.