ndhistogram 0.3.0

multi-dimensional histogramming for Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125

//! Multi-dimensional histogramming for Rust.
//!
//! 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.
//! - Flexible bin values including any primitive number type, or a user-defined struct.
//! - Unweighted and weighted filling of histograms.
//! - Flexible, user-definable axis types.
//!
//! ## Quick-start
//!
//! ```rust
//! use ndhistogram::{Histogram, axis::Axis, ndhistogram, axis::Uniform, axis::Category};
//!
//! // 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));
//!
//! // 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 user defined value types are possible by implementing Fill and FillWith traits
//!
//! ```
//!
//! ## Overview
//!
//! A [Histogram](crate::Histogram) is composed of two components:
//! - An [Axis](crate::axis::Axis) for 1D histograms or set of [Axes] for higher dimensional histograms.
//! The [Axes] and [Axis](crate::axis::Axis) map from coodinate space (eg \[x,y,z\]) to an integer bin number.
//! - The histogram bin value storage. Bin values may be any type that implements [Fill], [FillWith] or [FillWithWeight] (including any integer and floating number type).
//!
//! ### 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.
//!
//!
//! Alternative implentations are possible by implementing the [Histogram] trait.
//!
//! ### Axis Implementations
//!
//! - [Uniform](crate::axis::Uniform)/[UniformNoFlow](crate::axis::UniformNoFlow): equally sized bins in a some range with optional underflow/overflow bins.
//! - [Variable](crate::axis::Variable)/[VariableNoFlow](crate::axis::VariableNoFlow): variable sized bins with optional underflow/overflow bins.
//! - [Category](crate::axis::Category)/[CategoryNoFlow](crate::axis::CategoryNoFlow): a finite set of discrete values with optional overflow bin.
//!
//! User defined axes types are possible by implementing the [Axis](crate::axis::Axis) trait.
//!
//! ### Histogram Bin Values
//!
//! Histograms may be filled with values of the following types.
//!
//! - Primitve floating point and integer number types.
//! - All types that implement [AddAssign](std::ops::AddAssign) are [FillWith].
//! - All types that implement [AddAssign](std::ops::AddAssign) and [One](num_traits::One) are [Fill].
//!
//! This crate defines the following bin value types:
//!
//! - [Sum](crate::value::Sum) : a simple bin count that counts the number of times it has been filled.
//! - [WeightedSum](crate::value::WeightedSum) : as Sum but with weighted fills.
//! - [Mean](crate::value::Mean) : computes the mean of the values it is filled with.
//! - [WeightedMean](crate::value::WeightedMean) : as Mean but with weighted fills.
//!
//! User defined bin value types are possible by implementing the [Fill], [FillWith] or [FillWithWeighted] traits.

#![doc(issue_tracker_base_url = "https://github.com/davehadley/rust-hist/issues")]
#![cfg_attr(
    debug_assertions,
    warn(
        missing_debug_implementations,
        rust_2018_idioms,
        unreachable_pub,
        unused_import_braces
    ),
    deny(unsafe_code, macro_use_extern_crate),
    warn(missing_docs, missing_crate_level_docs, missing_doc_code_examples,)
)]

mod axes;
pub mod axis;
mod histogram;

pub mod value;

pub use axes::Axes;
pub use histogram::fill::Fill;
pub use histogram::fill::FillWith;
pub use histogram::fill::FillWithWeighted;
pub use histogram::histogram::Histogram;
pub use histogram::histogram::Item;
pub use histogram::vechistogram::VecHistogram;

#[macro_use]
mod macros;