Struct TDigest

Source

pub struct TDigest { /* private fields */ }

Expand description

The main struct representing a t-digest.

The TDigest struct allows efficient computation of quantiles and supports merging from other t-digests.

§Examples

use tdigests::TDigest;

let values = vec![1.0, 2.0, 3.0];
let digest = TDigest::from_values(values);

let q = digest.estimate_quantile(0.5);
assert_eq!(q, 2.0);

Implementations§

Source §

impl TDigest

Source

pub fn from_values(values: Vec<f64>) -> Self

Creates a t-digest from a list of values.

§Panics

Panics if the input values are empty or if all values are NaN.

§Examples

use tdigests::TDigest;

let values = vec![3.0, 1.0, 2.0];
let digest = TDigest::from_values(values);

Source

pub fn from_centroids(centroids: Vec<Centroid>) -> Self

Creates a t-digest from existing centroids.

This method is useful when working in distributed systems where centroids are generated on partitions of data and need to be merged.

§Panics

Panics if the input centroids is empty or if all centroids have either zero weight or NaN means.

§Examples

use tdigests::Centroid;
use tdigests::TDigest;

let centroids = vec![
    Centroid::new(10.0, 1.0),
    Centroid::new(20.0, 2.0),
    Centroid::new(30.0, 1.0),
];
let digest = TDigest::from_centroids(centroids);

Source

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

Returns the internal centroids.

§Examples

use tdigests::TDigest;

let values = vec![1.0, 2.0, 3.0];
let digest = TDigest::from_values(values);

let centroids = digest.centroids();
assert_eq!(centroids.len(), 3);

Source

pub fn merge(&self, other: &TDigest) -> TDigest

Merges another t-digest into this one.

§Examples

use tdigests::TDigest;

let values1 = vec![1.0, 2.0, 3.0];
let digest1 = TDigest::from_values(values1);

let values2 = vec![4.0, 5.0, 6.0];
let digest2 = TDigest::from_values(values2);

let merged_digest = digest1.merge(&digest2);

Source

pub fn compress(&mut self, max_centroids: usize)

Compresses the centroids to reduce their number while maintaining accuracy.

This method should be called after adding a large number of points to reduce the memory footprint and improve estimation performance.

§Examples

use tdigests::TDigest;

let values = (0..1000).map(|i| i as f64).collect::<Vec<_>>();
let mut digest = TDigest::from_values(values);

// Compress to have at most 100 centroids
digest.compress(100);

assert!(digest.centroids().len() <= 100);

Source

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

Estimates the quantile for a given cumulative probability q.

§Examples

use tdigests::TDigest;

let values = (0..=100).map(|i| i as f64).collect::<Vec<_>>();
let digest = TDigest::from_values(values);
let median = digest.estimate_quantile(0.5);
assert_eq!(median, 50.0);

Source

pub fn estimate_rank(&self, x: f64) -> f64

Compute the relative rank of a given value x, specified as a percentage ranging from 0.0 to 1.0.

Returns a value between 0.0 and 1.0 representing the probability that a random variable is less than or equal to x.

§Examples

use tdigests::TDigest;

let values = (0..=100).map(|i| i as f64).collect::<Vec<_>>();
let digest = TDigest::from_values(values);
let rank = digest.estimate_rank(50.0);
assert_eq!(rank, 0.5);