Crate ndhistogram[][src]

Expand description

ndhistogram implements multi-dimensional histograms for Rust.

This library aims to provide a similar feature set to the C++ library boost-histogram but with an idomatic pure-Rust implementation.

Features include:

  • Histograms with any number of dimensions from 1 up to 21 dimensions.
  • Continuous (eg represented by a floating point number) and discrete axis (eg a category represented by a string value or enum) types that are composable (eg you may mix discrete and continuous axes).
  • Flexible bin values including any primitive number type, or a user-defined type.
  • Unweighted and weighted filling of histograms.
  • Flexible, user-definable axis types.
  • Sparse histograms to reduce the memory footprint of high bin count, mostly empty, histograms.

Usage

Add this to your Cargo.toml:

[dependencies]
ndhistogram = "0.6.2"

See the change log for differences between releases. Please report any bugs in the issues tracker.

Quick-start

use ndhistogram::{Histogram, axis::Axis, ndhistogram, axis::Uniform, axis::Category, value::Mean};

// create a 1D histogram with 10 equally sized bins between -5 and 5
let mut hist = ndhistogram!(Uniform::new(10, -5.0, 5.0));
// fill this histogram with a single value
hist.fill(&1.0);
// fill this histogram with weights
hist.fill_with(&2.0, 4.0);
// read the histogram values
let x1 = hist.value(&1.0);
let also_x1 = hist.value_at_index(7);
assert_eq!(x1, also_x1);
// iterate the histogram values
for item in hist.iter() {
    println!("{}, {}, {}", item.index, item.bin, item.value)
}
// print the histogram to stdout
println!("{}", hist);


// create a 2D histogram
let mut hist = ndhistogram!(Uniform::new(10, -5.0, 5.0), Uniform::new(10, -5.0, 5.0));
// fill 2D histogram
hist.fill(&(1.0, 2.0));
// read back the histogram values
let x1_y2 = hist.value(&(1.0, 2.0));
// higher dimensions are possible with additional arguments to ndhistogram

// Several axis types are available
let mut hist = ndhistogram!(Category::new(vec!["Red", "Blue", "Green"]));
hist.fill(&"Red");
let red_value = hist.value(&"Red");
// and user axis types may be created by implementing the Axis trait

// The Histogram bin value type is configurable
let mut hist = ndhistogram!(Uniform::new(10, -5.0, 5.0); i32);
hist.fill_with(&1.0, 2);
let value: Option<&i32> = hist.value(&1.0);

// and more complex value types beyond primitives are available
let mut hist = ndhistogram!(Uniform::new(10, -5.0, 5.0); Mean);
hist.fill_with(&1.0, 1.0);
hist.fill_with(&1.0, 3.0);
assert_eq!(hist.value(&1.0).unwrap().mean(), 2.0);

// user defined value types are possible by implementing Fill, FillWith or FillWithWeighted traits

Overview

A Histogram is composed of two components:

  • The Axes which is a set of Axis corresponding to each dimension of the histogram. The Axes and Axis define the binning of the histogram and are responsible for mapping from coordinate space (eg [x,y,z]) to an integer bin number.
  • The histogram bin value storage. Valid bin value types including any integer and floating number type as well as user defined types that implement Fill, FillWith or FillWithWeighted.

Histogram Implementations

  • VecHistogram: bin values are stored in a Vec. Created with the ndhistogram macro. This is the recommended implementation for most use cases. However, as memory is allocated even for empty bins, this may not be practical for very high dimension histograms.
  • HashHistogram: bin values are stored in a HashMap. Created with the sparsehistogram macro. Useful for high dimension, mostly empty, histograms as empty bins take up no memory.

Alternative implementations are possible by implementing the Histogram trait.

Axis Implementations

User defined axes types are possible by implementing the Axis trait.

Histogram Bin Values

Histograms may be filled with values of the following types:

This crate defines the following bin value types:

  • Sum : a simple bin count that counts the number of times it has been filled.
  • WeightedSum : as Sum but with weighted fills.
  • Mean : computes the mean of the values it is filled with.
  • WeightedMean : as Mean but with weighted fills.

User defined bin value types are possible by implementing the Fill, FillWith or FillWithWeighted traits.

Modules

Axis for ND histograms

Provides errors that may be returned by Histograms.

Bin Value types for ND-histograms

Macros

Creates a sparse Histogram.

Structs

Container for a set of Axis that implements Axes.

A sparse N-dimensional Histogram that stores its values in a HashMap.

Struct to be returned when iterating over Histograms bins.

A Histogram that stores its values in a Vec.

Traits

Axes provided an interface for a set of ND dimensional set of histograms.

Fill a histogram bin value with unit weight.

Fill a histogram bin value with some data.

Fill a histogram with some weighted value.

A common interface for an ND histograms.

Type Definitions

Type alias for 1D Histograms returned by ndhistogram.

Type alias for 2D Histograms returned by ndhistogram.

Type alias for 3D Histograms returned by ndhistogram.

Type alias for ND Histograms returned by ndhistogram.

Type alias for 1D Histograms returned by sparsehistogram.

Type alias for 2D Histograms returned by sparsehistogram.

Type alias for 3D Histograms returned by sparsehistogram.

Type alias for ND Histograms returned by sparsehistogram.