nexus-stats

Fixed-memory, zero-allocation streaming statistics for real-time systems.

Every primitive is O(1) per update, fixed memory after construction, and no_std compatible. Designed for event loops, trading systems, and anywhere you need statistics without latency jitter.

Quick Start

use nexus_stats::{Direction, detection::CusumF64, smoothing::EmaF64, statistics::WelfordF64};

// Detect latency shifts with CUSUM
let mut cusum = CusumF64::builder(100.0)  // target: 100μs baseline
    .slack(5.0)                            // sensitivity
    .threshold(50.0)                       // decision boundary
    .min_samples(20)                       // warmup
    .build().unwrap();

for latency in samples {
    match cusum.update(latency) {
        Some(Direction::Rising) => println!("latency degradation detected"),
        Some(Direction::Falling) => println!("latency recovered"),
        _ => {}
    }
}

// Smooth noisy measurements with EMA
let mut ema = EmaF64::builder()
    .span(20)          // ~20-sample smoothing window
    .min_samples(10)
    .build().unwrap();

if let Some(smoothed) = ema.update(sample) {
    // use smoothed value
}

// Track running statistics with Welford
let mut stats = WelfordF64::new();
stats.update(sample);
if let Some(mean) = stats.mean() {
    println!("mean={mean}, std_dev={}", stats.std_dev().unwrap());
}

Algorithms

60+ algorithms across 10 categories. See full documentation for deep-dives on each algorithm.

Change Detection

Smoothing & Filtering

Statistics

Regression

Multi-Armed Bandits (alloc, std|libm)

Signal Analysis

Information Theory (std|libm)

Monitoring

Frequency & Scoring

Utilities

Type Variants

Explicit concrete types — no generics to fight with. Float types use FMA intrinsics; integer types use bit-shift arithmetic.

Common API Patterns

All types follow consistent conventions:

• Builder pattern for config-driven types (CusumF64::builder(target))
• const fn new() for zero-config types (WelfordF64::new())
• Priming — returns None until min_samples reached
• is_primed() — check if enough data has been seen
• count() — total samples processed
• reset() — clear state for operational/admin reset
• seed() — skip warmup with pre-loaded baseline (CUSUM, EMA, AdaptiveThreshold)
• #[must_use] — compiler warns if you ignore return values

Documentation

Comprehensive documentation including:

• Which algorithm do I need? — decision tree
• Quick start recipes — copy-paste examples
• Parameter tuning guide — how to set alpha, slack, etc.
• Composing primitives — building monitors from parts
• 40 algorithm deep-dives with ASCII diagrams, domain examples, and performance data
• 10 use-case guides (latency, backpressure, anomaly detection, feed health, networking, gaming, SRE, capacity planning, industrial, rate management)

Performance

All measurements in CPU cycles (rdtsc), pinned to a single core. Batch of 64 updates per sample to amortize timing overhead.

cargo build --release --example perf_stats -p nexus-stats
taskset -c 0 ./target/release/examples/perf_stats

Data Quality & Error Policy

nexus-stats distinguishes two failure categories:

• Data errors (NaN, Inf) — All float update methods return Result<_, DataError>. The library rejects the input and leaves state unchanged. The caller declares the policy: .unwrap() to crash, log and continue, or trigger a circuit breaker.
• Programmer errors (wrong dimensions, out-of-range) — The library panics. Fix the code.

The library makes no assumptions about which policy is correct. Each system has different implications.

// Production: log and continue
if let Err(e) = stats.update(sample) {
    warn!("bad data: {e:?}");
}

// Testing: crash hard
stats.update(sample).unwrap();

Features

One of std or libm must be enabled. Update hot paths never use transcendentals — sqrt and exp are only used in queries (std_dev()) and construction (halflife()).

Sub-Crates

nexus-stats is split into five workspace crates for independent compilation and feature gating:

• nexus-stats-core — shared traits, error types, clock (Clock, WallClock, EpochClock), and builder infrastructure
• nexus-stats-smoothing — EMA, KAMA, Kalman, Holt, Spring, Slew, WindowedMedian
• nexus-stats-detection — CUSUM, MOSUM, Shiryaev-Roberts, MultiGate, RobustZScore, AdaptiveThreshold
• nexus-stats-regression — Linear, polynomial, exponential, logarithmic, power regression
• nexus-stats-control — DeadBand, Hysteresis, Debounce, LevelCrossing, PeakDetector, BoolWindow

The top-level nexus-stats crate re-exports everything. Use the sub-crates directly if you only need a subset.

Trading & Signal Analysis (v4.2)

New primitives for market making, signal quality measurement, and regime detection. See docs/use-cases/trading.md for full guide with examples.

License

Licensed under either of Apache License, Version 2.0 or MIT License at your option.