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.
Add this to your Cargo.toml:
toml
[dependencies]
ndhistogram = "0.5.0"
See the change log for differences between releases. Please report any bugs in the issues tracker.
```rust 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.fillwith(&2.0, 4.0); // read the histogram values let x1 = hist.value(&1.0); let alsox1 = hist.valueatindex(7); asserteq!(x1, alsox1); // 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.fillwith(&1.0, 1.0); hist.fillwith(&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
```
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].
Alternative implementations are possible by implementing the [Histogram] trait.
User defined axes types are possible by implementing the Axis trait.
Histograms may be filled with values of the following types:
This crate defines the following bin value types:
User defined bin value types are possible by implementing the [Fill], [FillWith] or [FillWithWeighted] traits.
Licensed under either of
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.