Struct TDigest

Source

#[non_exhaustive]
pub struct TDigest { /* private fields */ }

Expand description

T-Digest to be operated on.

Call TDigest::flush before centroid-based queries or serialization after using the mutable ingestion API. The pending buffer is deliberately omitted from serde output, so serializing an unflushed digest produces an incomplete digest.

Queries that need data return None when the digest is empty. Summary accessors such as TDigest::count and TDigest::sum return zero.

Implementations§

Source §

impl TDigest

Source

pub fn new_with_size(max_size: usize) -> Self

Create an empty digest with the requested compression size.

Larger sizes retain more centroids and generally improve accuracy.

use tdigest::TDigest;

let digest = TDigest::new_with_size(200);
assert_eq!(digest.max_size(), 200);

Source

pub fn new( centroids: Vec<Centroid>, sum: f64, count: f64, max: Option<f64>, min: Option<f64>, max_size: usize, ) -> Self

Construct a digest from existing centroids and summary statistics.

If there are more centroids than max_size, they are recompressed.

Source

pub fn mean(&self) -> Option<f64>

Return the arithmetic mean, or None when the digest is empty.

Source

pub fn sum(&self) -> f64

Return the sum of all inserted values.

Source

pub fn count(&self) -> f64

Return the number of inserted values as an f64.

Integer counts are represented exactly up to 2^53.

Source

pub fn max(&self) -> Option<f64>

Return the greatest inserted value, or None when empty.

Source

pub fn min(&self) -> Option<f64>

Return the least inserted value, or None when empty.

Source

pub fn is_empty(&self) -> bool

Return whether no values have been inserted.

Source

pub fn max_size(&self) -> usize

Return the configured compression size.

Source

pub fn centroids(&self) -> &[Centroid]

Return the compressed centroids in ascending mean order.

Call TDigest::flush first after mutable ingestion.

Source §

impl TDigest

Source

pub fn push(&mut self, value: f64)

Insert one value into this digest.

Values are buffered and compressed automatically. Call TDigest::flush before estimating quantiles or reading centroids.

use tdigest::TDigest;

let mut digest = TDigest::new_with_size(100);
digest.push(1.0);
digest.push(2.0);
digest.flush();
assert_eq!(digest.estimate_quantile(0.5), Some(1.5));

Source

pub fn extend_values(&mut self, values: impl IntoIterator<Item = f64>)

Insert several values using the mutable buffered ingestion path.

Source

pub fn flush(&mut self)

Compress pending buffered values into this digest’s centroids.

This is a no-op when the buffer is empty.

Source

pub fn merge_unsorted(&self, unsorted_values: Vec<f64>) -> TDigest

Merge unsorted values into a new digest, sorting them internally.

use tdigest::TDigest;

let digest = TDigest::default().merge_unsorted(vec![3.0, 1.0, 2.0]);
assert_eq!(digest.estimate_quantile(0.5), Some(2.0));

Source

pub fn merge_sorted(&self, sorted_values: Vec<f64>) -> TDigest

Merge ascending values into a new digest.

use tdigest::TDigest;

let digest = TDigest::default().merge_sorted(vec![1.0, 2.0, 3.0]);
assert_eq!(digest.count(), 3.0);

Source

pub fn merge_digests(digests: Vec<TDigest>) -> TDigest

Merge several digests into one.

The result uses the largest max_size among the inputs. With no inputs, this returns a digest with the default size of 100.

use tdigest::TDigest;

let left = TDigest::default().merge_sorted(vec![1.0, 2.0]);
let right = TDigest::default().merge_sorted(vec![3.0, 4.0]);
let merged = TDigest::merge_digests(vec![left, right]);
assert_eq!(merged.count(), 4.0);

Source

pub fn estimate_quantile(&self, q: f64) -> Option<f64>

Estimate the value at quantile q (0.0 to 1.0). Returns None if the digest is empty. Values below zero return the minimum; values above one return the maximum.

use tdigest::TDigest;

let digest = TDigest::default().merge_sorted(vec![1.0, 2.0, 3.0]);
assert_eq!(digest.estimate_quantile(0.5), Some(2.0));

Source

pub fn quantiles(&self, qs: &[f64]) -> Vec<Option<f64>>

Estimate several quantiles with one cumulative-weight pass.

Quantiles do not need to be sorted. Each result has the same semantics as TDigest::estimate_quantile.

use tdigest::TDigest;

let digest = TDigest::default().merge_sorted(vec![1.0, 2.0, 3.0]);
assert_eq!(digest.quantiles(&[0.0, 0.5, 1.0]), vec![Some(1.0), Some(2.0), Some(3.0)]);

Source

pub fn estimate_rank(&self, value: f64) -> Option<f64>

Estimate the rank (CDF) of value: the fraction of inserted values less than or equal to it.

Returns None if the digest is empty.

use tdigest::TDigest;

let digest = TDigest::default().merge_sorted((1..=100).map(f64::from).collect());
let median_rank = digest.estimate_rank(50.0).unwrap();
assert!((median_rank - 0.5).abs() < 0.05);

Source

pub fn trimmed_mean(&self, lo: f64, hi: f64) -> Option<f64>

Estimate the mean of values between quantiles lo and hi.

Quantiles are clamped to [0.0, 1.0]. Returns None if the digest is empty, either bound is NaN, or the resulting interval is empty.

use tdigest::TDigest;

let digest = TDigest::default().merge_sorted((1..=100).map(f64::from).collect());
assert!((digest.trimmed_mean(0.1, 0.9).unwrap() - 50.5).abs() < 1.0);