Struct SparseHistogram

Source

pub struct SparseHistogram { /* private fields */ }

Expand description

A sparse, columnar representation of a histogram.

Significantly smaller than a Histogram when many buckets are zero. Each non-zero bucket is stored as a pair (index[i], count[i]) where index[i] is the bucket index and count[i] is its count, in ascending index order.

Implementations§

Source §

impl SparseHistogram

Source

pub fn new(grouping_power: u8, max_value_power: u8) -> Result<Self, Error>

Construct a new histogram from the provided parameters. See the documentation for crate::Config to understand their meaning.

Source

pub fn with_config(config: &Config) -> Self

Creates a new histogram using a provided crate::Config.

Source

pub fn from_parts( config: Config, index: Vec<u32>, count: Vec<u64>, ) -> Result<Self, Error>

Creates a sparse histogram from its raw parts.

Returns an error if:

index and count have different lengths
any index is out of range for the config
the indices are not in strictly ascending order

Source

pub fn into_parts(self) -> (Config, Vec<u32>, Vec<u64>)

Consumes the histogram, returning the config, index, and count vectors.

Source

pub fn config(&self) -> Config

Returns the bucket configuration.

Source

pub fn index(&self) -> &[u32]

Returns a slice of the non-zero bucket indices.

Source

pub fn count(&self) -> &[u64]

Returns a slice of the bucket counts.

Source

pub fn checked_add(&self, h: &SparseHistogram) -> Result<SparseHistogram, Error>

Adds the other histogram to this histogram and returns the result as a new histogram.

Returns Err(Error::IncompatibleParameters) if the configs don’t match, or Err(Error::Overflow) if any bucket overflows.

Source

pub fn wrapping_add( &self, h: &SparseHistogram, ) -> Result<SparseHistogram, Error>

Adds the other histogram to this histogram and returns the result as a new histogram.

Returns Err(Error::IncompatibleParameters) if the configs don’t match. Buckets which have values in both histograms are allowed to wrap.

Source

pub fn checked_sub(&self, h: &SparseHistogram) -> Result<SparseHistogram, Error>

Subtracts the other histogram from this histogram and returns the result as a new histogram. The other histogram is expected to be a subset of the current histogram, i.e., for every bucket in the other histogram should have a count less than or equal to the corresponding bucket in this histogram.

Returns Err(Error::IncompatibleParameters) if the configs don’t match, Err(Error::InvalidSubset) if the other histogram has buckets not present in this one, or Err(Error::Underflow) if any bucket would underflow.

Source

pub fn wrapping_sub( &self, h: &SparseHistogram, ) -> Result<SparseHistogram, Error>

Subtracts the other histogram from this histogram and returns the result as a new histogram.

Returns Err(Error::IncompatibleParameters) if the configs don’t match, or Err(Error::InvalidSubset) if the other histogram has buckets not present in this one. Buckets are allowed to wrap on underflow.

Source

pub fn percentiles( &self, percentiles: &[f64], ) -> Result<Option<Vec<(f64, Bucket)>>, Error>

Return a collection of percentiles from this histogram.

Each percentile should be in the inclusive range 0.0..=1.0. For example, the 50th percentile (median) can be found using 0.5.

The results will be sorted by the percentile.

Source

pub fn percentile(&self, percentile: f64) -> Result<Option<Bucket>, Error>

Return a single percentile from this histogram.

The percentile should be in the inclusive range 0.0..=1.0. For example, the 50th percentile (median) can be found using 0.5.

Source

pub fn downsample(&self, grouping_power: u8) -> Result<SparseHistogram, Error>

Returns a new histogram with a reduced grouping power. The reduced grouping power should lie in the range (0..existing grouping power).

Returns an error if the requested grouping power is not less than the current grouping power.

This works by iterating over every bucket in the existing histogram and inserting the contained values into the new histogram. While we do not know the exact values of the data points (only that they lie within the bucket’s range), it does not matter since the bucket is not split during downsampling and any value can be used.

Source