subms_stats/lib.rs
1//! # subms-stats
2//!
3//! Latency-distribution statistics for measurement-heavy workloads.
4//! Pure functions on `&[u64]` sample arrays + an ergonomic
5//! [`SubMsSamples`] facade.
6//!
7//! This is the statistics primitive the `subms` perf harness uses
8//! internally, published as its own crate so you can use it without
9//! pulling in the bench machinery. Bring your own `Vec<u64>` of
10//! nanosecond readings (from any source) and compose the analyses you
11//! need.
12//!
13//! ## Feature flags
14//!
15//! The crate ships a tiny **core** that's always on (`percentile`,
16//! `mean`, `stddev`) plus optional features that you opt into via Cargo:
17//!
18//! - `histogram` (default) - log2-spaced CDF buckets
19//! - `jitter` (default) - per-window variance score
20//! - `tail` (default) - CTE, Hill estimator, fatness ratio
21//! - `robust` (default) - IQR, MAD, CoV, skewness, kurtosis
22//! - `compare` (default) - KS statistic, Cohen's d
23//! - `bootstrap` (default) - bootstrap CIs for percentiles
24//!
25//! Everything is on by default. For a minimal build:
26//!
27//! ```toml
28//! [dependencies]
29//! subms-stats = { version = "0.5", default-features = false }
30//! ```
31//!
32//! Then pick only the features you need:
33//!
34//! ```toml
35//! subms-stats = { version = "0.5", default-features = false, features = ["histogram", "tail"] }
36//! ```
37//!
38//! ## Quickstart
39//!
40//! ```
41//! use subms_stats::SubMsSamples;
42//!
43//! let raw = vec![100u64, 200, 150, 300, 250, 175, 125, 400];
44//! let s = SubMsSamples::new(&raw);
45//! let p99 = s.p99();
46//! let _ = p99;
47//! ```
48
49// Always-on core.
50pub mod percentiles;
51pub mod samples;
52
53#[cfg(feature = "bootstrap")]
54pub mod bootstrap;
55#[cfg(feature = "compare")]
56pub mod compare;
57#[cfg(feature = "histogram")]
58pub mod histogram;
59#[cfg(feature = "jitter")]
60pub mod jitter;
61#[cfg(feature = "robust")]
62pub mod robust;
63#[cfg(feature = "tail")]
64pub mod tail;
65
66// Flat re-exports for the most common entry points. Library consumers
67// can use module paths (e.g. `subms_stats::tail::hill_tail_index`) or
68// the flat form (e.g. `subms_stats::hill_tail_index`).
69pub use percentiles::{mean, percentile, percentile_sweep, stddev};
70pub use samples::SubMsSamples;
71
72#[cfg(feature = "bootstrap")]
73pub use bootstrap::bootstrap_percentile_ci;
74#[cfg(feature = "compare")]
75pub use compare::{cohens_d, ks_statistic};
76#[cfg(feature = "histogram")]
77pub use histogram::cdf_buckets;
78#[cfg(feature = "jitter")]
79pub use jitter::jitter_score;
80#[cfg(feature = "robust")]
81pub use robust::{coefficient_of_variation, iqr, kurtosis, median_absolute_deviation, skewness};
82#[cfg(feature = "tail")]
83pub use tail::{conditional_tail_expectation, hill_tail_index, tail_fatness_ratio};