Struct ndarray_stats::histogram::Grid

pub struct Grid<A: Ord> { /* private fields */ }

An orthogonal partition of a rectangular region in an n-dimensional space, e.g. [a₀, b₀) × ⋯ × [a_n−1, b_n−1), represented as a collection of rectangular n-dimensional bins.

The grid is solely determined by the Cartesian product of its projections on each coordinate axis. Therefore, each element in the product set should correspond to a sub-region in the grid.

For example, this partition can be represented as a Grid struct:

g +---+-------+---+
  | 3 |   4   | 5 |
f +---+-------+---+
  |   |       |   |
  | 0 |   1   | 2 |
  |   |       |   |
e +---+-------+---+
  a   b       c   d

R0:    [a, b) × [e, f)
R1:    [b, c) × [e, f)
R2:    [c, d) × [e, f)
R3:    [a, b) × [f, g)
R4:    [b, d) × [f, g)
R5:    [c, d) × [f, g)
Grid:  { [a, b), [b, c), [c, d) } × { [e, f), [f, g) } == { R0, R1, R2, R3, R4, R5 }

while the next one can’t:

 g  +---+-----+---+
    |   |  2  | 3 |
(f) |   +-----+---+
    | 0 |         |
    |   |    1    |
    |   |         |
 e  +---+-----+---+
    a   b     c   d

R0:    [a, b) × [e, g)
R1:    [b, d) × [e, f)
R2:    [b, c) × [f, g)
R3:    [c, d) × [f, g)
// 'f', as long as 'R1', 'R2', or 'R3', doesn't appear on LHS
// [b, c) × [e, g), [c, d) × [e, g) doesn't appear on RHS
Grid:  { [a, b), [b, c), [c, d) } × { [e, g) } != { R0, R1, R2, R3 }

Examples

Basic usage, building a Grid via GridBuilder, with optimal grid layout determined by a given strategy, and generating a histogram:

use ndarray::{Array, array};
use ndarray_stats::{
    histogram::{strategies::Auto, Bins, Edges, Grid, GridBuilder},
    HistogramExt,
};

// 1-dimensional observations, as a (n_observations, n_dimension) 2-d matrix
let observations = Array::from_shape_vec(
    (12, 1),
    vec![1, 4, 5, 2, 100, 20, 50, 65, 27, 40, 45, 23],
).unwrap();

// The optimal grid layout is inferred from the data, given a chosen strategy, Auto in this case
let grid = GridBuilder::<Auto<usize>>::from_array(&observations).unwrap().build();

let histogram = observations.histogram(grid);

let histogram_matrix = histogram.counts();
// Bins are left-closed, right-open!
let expected = array![4, 3, 3, 1, 0, 1];
assert_eq!(histogram_matrix, expected.into_dyn());

Implementations

impl<A: Ord> Grid<A>

pub fn ndim(&self) -> usize

Returns the number of dimensions of the region partitioned by the grid.

Examples

use ndarray_stats::histogram::{Edges, Bins, Grid};

let edges = Edges::from(vec![0, 1]);
let bins = Bins::new(edges);
let square_grid = Grid::from(vec![bins.clone(), bins.clone()]);

assert_eq!(square_grid.ndim(), 2usize)

pub fn shape(&self) -> Vec<usize>

Returns the numbers of bins along each coordinate axis.

Examples

use ndarray_stats::histogram::{Edges, Bins, Grid};

let edges_x = Edges::from(vec![0, 1]);
let edges_y = Edges::from(vec![-1, 0, 1]);
let bins_x = Bins::new(edges_x);
let bins_y = Bins::new(edges_y);
let square_grid = Grid::from(vec![bins_x, bins_y]);

assert_eq!(square_grid.shape(), vec![1usize, 2usize]);

pub fn projections(&self) -> &[Bins<A>]

Returns the grid projections on each coordinate axis as a slice of immutable references.

pub fn index_of<S>(&self, point: &ArrayBase<S, Ix1>) -> Option<Vec<usize>> where
    S: Data<Elem = A>, 

Returns an n-dimensional index, of bins along each axis that contains the point, if one exists.

Returns None if the point is outside the grid.

Panics

Panics if dimensionality of the point doesn’t equal the grid’s.

Examples

Basic usage:

use ndarray::array;
use ndarray_stats::histogram::{Edges, Bins, Grid};
use noisy_float::types::n64;

let edges = Edges::from(vec![n64(-1.), n64(0.), n64(1.)]);
let bins = Bins::new(edges);
let square_grid = Grid::from(vec![bins.clone(), bins.clone()]);

// (0., -0.7) falls in 1st and 0th bin respectively
assert_eq!(
    square_grid.index_of(&array![n64(0.), n64(-0.7)]),
    Some(vec![1, 0]),
);
// Returns `None`, as `1.` is outside the grid since bins are right-open
assert_eq!(
    square_grid.index_of(&array![n64(0.), n64(1.)]),
    None,
);

A panic upon dimensionality mismatch:

// the point has 3 dimensions, the grid expected 2 dimensions
assert_eq!(
    square_grid.index_of(&array![n64(0.), n64(-0.7), n64(0.5)]),
    Some(vec![1, 0, 1]),
);

impl<A: Ord + Clone> Grid<A>

pub fn index(&self, index: &[usize]) -> Vec<Range<A>>

Given an n-dimensional index, i = (i_0, ..., i_{n-1}), returns an n-dimensional bin, I_{i_0} x ... x I_{i_{n-1}}, where I_{i_j} is the i_j-th interval on the j-th projection of the grid on the coordinate axes.

Panics

Panics if at least one in the index, (i_0, ..., i_{n-1}), is out of bounds on the corresponding coordinate axis, i.e. if there exists j s.t. i_j >= self.projections[j].len().

Examples

Basic usage:

use ndarray::array;
use ndarray_stats::histogram::{Edges, Bins, Grid};

let edges_x = Edges::from(vec![0, 1]);
let edges_y = Edges::from(vec![2, 3, 4]);
let bins_x = Bins::new(edges_x);
let bins_y = Bins::new(edges_y);
let square_grid = Grid::from(vec![bins_x, bins_y]);

// Query the 0-th bin on x-axis, and 1-st bin on y-axis
assert_eq!(
    square_grid.index(&[0, 1]),
    vec![0..1, 3..4],
);

A panic upon out-of-bounds:

// out-of-bound on y-axis
assert_eq!(
    square_grid.index(&[0, 2]),
    vec![0..1, 3..4],
);

Trait Implementations

impl<A: Clone + Ord> Clone for Grid<A>

fn clone(&self) -> Grid<A>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<A: Debug + Ord> Debug for Grid<A>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<A: Ord> From<Vec<Bins<A>, Global>> for Grid<A>

fn from(projections: Vec<Bins<A>>) -> Self

Converts a Vec<Bins<A>> into a Grid<A>, consuming the vector of bins.

The i-th element in Vec<Bins<A>> represents the projection of the bin grid onto the i-th axis.

Alternatively, a Grid can be built directly from data using a GridBuilder.

impl<A: PartialEq + Ord> PartialEq<Grid<A>> for Grid<A>

fn eq(&self, other: &Grid<A>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<A: Eq + Ord> Eq for Grid<A>

impl<A: Ord> StructuralEq for Grid<A>

impl<A: Ord> StructuralPartialEq for Grid<A>