Struct FeatureHistogram 

pub struct FeatureHistogram {
    pub grad_sums: Vec<f64>,
    pub hess_sums: Vec<f64>,
    pub counts: Vec<u64>,
    pub edges: BinEdges,
    /* private fields */
}

Available on crate feature alloc only.

Histogram for a single feature: accumulates grad/hess/count per bin. SoA layout for cache efficiency during split-point evaluation.

Fields

grad_sums: Vec<f64>

Gradient sums per bin.

When decay_scale != 1.0, these are stored in un-decayed coordinates. Multiply by decay_scale to recover effective (decayed) values.

hess_sums: Vec<f64>

Hessian sums per bin (same scaling convention as grad_sums).

counts: Vec<u64>

Sample counts per bin (never decayed).

edges: BinEdges

Bin edges for this feature.

Implementations

impl FeatureHistogram

pub fn new(edges: BinEdges) -> Self

Create a new zeroed histogram with the given bin edges.

pub fn accumulate(&mut self, value: f64, gradient: f64, hessian: f64)

Accumulate a single sample into the appropriate bin.

Finds the bin for value using the stored edges, then adds the gradient, hessian, and increments the count for that bin.

pub fn total_gradient(&self) -> f64

Sum of all gradient accumulators across bins.

Accounts for any pending lazy decay by multiplying by decay_scale.

pub fn total_hessian(&self) -> f64

Sum of all hessian accumulators across bins.

Accounts for any pending lazy decay by multiplying by decay_scale.

pub fn total_count(&self) -> u64

Total sample count across all bins.

pub fn n_bins(&self) -> usize

Number of bins in this histogram.

pub fn accumulate_with_decay( &mut self, value: f64, gradient: f64, hessian: f64, alpha: f64, )

Accumulate with lazy forward decay: O(1) per sample.

Implements the forward decay scheme (Cormode et al. 2009) using a deferred scaling technique. Instead of decaying all bins on every sample, we track a running decay_scale and store new samples in un-decayed coordinates. The actual bin values are materialized only when read (see materialize_decay()).

Mathematically equivalent to eager decay: a gradient g added at epoch t contributes g * alpha^(T - t) at read time T.

The counts array is NOT decayed – it tracks the raw sample count for the Hoeffding bound computation.

pub fn materialize_decay(&mut self)

Apply the pending decay factor to all bins and reset the scale.

After calling this, grad_sums and hess_sums contain the true decayed values and can be passed directly to split evaluation. O(n_bins) – called at split evaluation time, not per sample.

pub fn reset(&mut self)

Reset all accumulators to zero, preserving the bin edges.

pub fn subtract(&self, child: &FeatureHistogram) -> FeatureHistogram

Histogram subtraction trick: self - child = sibling.

When building a tree, if you know the parent histogram and one child’s histogram, you can derive the other child by subtraction rather than re-scanning the data. This halves the histogram-building cost at each split.

Scale-aware: if either operand has pending lazy decay, the effective (decayed) values are used. The result has decay_scale = 1.0.

The returned histogram uses edges cloned from self.

Trait Implementations

impl Clone for FeatureHistogram

fn clone(&self) -> FeatureHistogram

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for FeatureHistogram

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

Formats the value using the given formatter.