Struct SGBT

Source

pub struct SGBT<L: Loss = SquaredLoss> { /* private fields */ }

Available on crate feature alloc only.

Expand description

Streaming Gradient Boosted Trees ensemble.

The primary entry point for training and prediction. Generic over L: Loss so the loss function’s gradient/hessian calls are monomorphized (inlined) into the boosting hot loop – no virtual dispatch overhead.

The default type parameter L = SquaredLoss means SGBT::new(config) creates a regression model without specifying the loss type explicitly.

§Examples

use irithyll::{SGBTConfig, SGBT};

// Regression with squared loss (default):
let config = SGBTConfig::builder().n_steps(10).build().unwrap();
let model = SGBT::new(config);
```ignore

```text
use irithyll::{SGBTConfig, SGBT};
use irithyll::loss::logistic::LogisticLoss;

// Classification with logistic loss -- no Box::new()!
let config = SGBTConfig::builder().n_steps(10).build().unwrap();
let model = SGBT::with_loss(config, LogisticLoss);

Implementations§

Source §

impl SGBT<SquaredLoss>

Source

pub fn new(config: SGBTConfig) -> Self

Create a new SGBT ensemble with squared loss (regression).

This is the most common constructor. For classification or custom losses, use with_loss.

Source §

impl<L: Loss> SGBT<L>

Source

pub fn with_loss(config: SGBTConfig, loss: L) -> Self

Create a new SGBT ensemble with a specific loss function.

The loss is stored by value (monomorphized), giving zero-cost gradient/hessian dispatch.

use irithyll::{SGBTConfig, SGBT};
use irithyll::loss::logistic::LogisticLoss;

let config = SGBTConfig::builder().n_steps(10).build().unwrap();
let model = SGBT::with_loss(config, LogisticLoss);

Source

pub fn train_one(&mut self, sample: &impl Observation)

Train on a single observation.

Accepts any type implementing Observation, including Sample, SampleRef, or tuples like (&[f64], f64) for zero-copy training.

Source

pub fn train_batch<O: Observation>(&mut self, samples: &[O])

Train on a batch of observations.

Source

pub fn train_batch_with_callback<O: Observation, F: FnMut(usize)>( &mut self, samples: &[O], interval: usize, callback: F, )

Train on a batch with periodic callback for cooperative yielding.

The callback is invoked every interval samples with the number of samples processed so far. This allows long-running training to yield to other tasks in an async runtime, update progress bars, or perform periodic checkpointing.

§Example

use irithyll::{SGBTConfig, SGBT};

let config = SGBTConfig::builder().n_steps(10).build().unwrap();
let mut model = SGBT::new(config);
let data: Vec<(Vec<f64>, f64)> = Vec::new(); // your data

model.train_batch_with_callback(&data, 1000, |processed| {
    println!("Trained {} samples", processed);
});

Source

pub fn train_batch_subsampled<O: Observation>( &mut self, samples: &[O], max_samples: usize, )

Train on a random subsample of a batch using reservoir sampling.

When max_samples < samples.len(), selects a representative subset using Algorithm R (Vitter, 1985) – a uniform random sample without replacement. The selected samples are then trained in their original order to preserve sequential dependencies.

This is ideal for large replay buffers where training on the full dataset is prohibitively slow but a representative subset gives equivalent model quality (e.g., 1M of 4.3M samples with R²=0.997).

When max_samples >= samples.len(), all samples are trained.

Source

pub fn train_batch_subsampled_with_callback<O: Observation, F: FnMut(usize)>( &mut self, samples: &[O], max_samples: usize, interval: usize, callback: F, )

Train on a batch with both subsampling and periodic callbacks.

Combines reservoir subsampling with cooperative yield points. Ideal for long-running daemon training where you need both efficiency (subsampling) and cooperation (yielding).

Source

pub fn predict(&self, features: &[f64]) -> f64

Predict the raw output for a feature vector.

Always uses sigmoid-blended soft routing with auto-calibrated per-feature bandwidths derived from median split threshold gaps. Features that have never been split on use hard routing (bandwidth = infinity).

Source

pub fn predict_smooth(&self, features: &[f64], bandwidth: f64) -> f64

Predict using sigmoid-blended soft routing with an explicit bandwidth.

Uses a single bandwidth for all features. For auto-calibrated per-feature bandwidths, use predict() which always uses smooth routing.

Source

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

Per-feature auto-calibrated bandwidths used by predict().

Empty before the first training sample. Each entry corresponds to a feature index; f64::INFINITY means that feature has no splits and uses hard routing.

Source

pub fn predict_interpolated(&self, features: &[f64]) -> f64

Predict with parent-leaf linear interpolation.

Blends each leaf prediction with its parent’s preserved prediction based on sample count, preventing stale predictions from fresh leaves.

Source

pub fn predict_sibling_interpolated(&self, features: &[f64]) -> f64

Predict with sibling-based interpolation for feature-continuous predictions.

At each split node near the threshold boundary, blends left and right subtree predictions linearly based on distance from the threshold. Uses auto-calibrated bandwidths as the interpolation margin. Predictions vary continuously as features change, eliminating step-function artifacts.

Source

pub fn predict_graduated(&self, features: &[f64]) -> f64

Predict with graduated active-shadow blending.

Smoothly transitions between active and shadow trees during replacement, eliminating prediction dips. Requires shadow_warmup to be configured. When disabled, equivalent to predict().

Source

pub fn predict_graduated_sibling_interpolated(&self, features: &[f64]) -> f64

Predict with graduated blending + sibling interpolation (premium path).

Combines graduated active-shadow handoff (no prediction dips during tree replacement) with feature-continuous sibling interpolation (no step-function artifacts near split boundaries).

Source

pub fn predict_transformed(&self, features: &[f64]) -> f64

Predict with loss transform applied (e.g., sigmoid for logistic loss).

Source

pub fn predict_proba(&self, features: &[f64]) -> f64

Predict probability (alias for predict_transformed).

Source

pub fn predict_with_confidence(&self, features: &[f64]) -> (f64, f64)

Predict with confidence estimation.

Returns (prediction, confidence) where confidence = 1 / sqrt(sum_variance). Higher confidence indicates more certain predictions (leaves have seen more hessian mass). Confidence of 0.0 means the model has no information.

This enables execution engines to modulate aggressiveness:

High confidence + favorable prediction → act immediately
Low confidence → fall back to simpler models or wait for more data

The variance per tree is estimated as 1 / (H_sum + lambda) at the leaf where the sample lands. The ensemble variance is the sum of per-tree variances (scaled by learning_rate²), and confidence is the reciprocal of the standard deviation.

Source