histogram/grid.rs: Rewriting some docs

- More documentations are added.
- Also adjusted some formatting.

Author: lebensterben

src/histogram/grid.rs

@@ -5,37 +5,61 @@ use itertools::izip;
 use ndarray::{ArrayBase, Axis, Data, Ix1, Ix2};
 use std::ops::Range;
 
-/// A `Grid` is a partition of a rectangular region of an *n*-dimensional
-/// space—e.g. [*a*<sub>0</sub>, *b*<sub>0</sub>) × ⋯ × [*a*<sub>*n*−1</sub>,
-/// *b*<sub>*n*−1</sub>)—into a collection of rectangular *n*-dimensional bins.
+/// An orthogonal partition of a rectangular region in an *n*-dimensional space, e.g.
+/// [*a*<sub>0</sub>, *b*<sub>0</sub>) × ⋯ × [*a*<sub>*n*−1</sub>, *b*<sub>*n*−1</sub>),
+/// 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:
 ///
-/// The grid is **fully determined by its 1-dimensional projections** on the
-/// coordinate axes. For example, this is a partition that can be represented
-/// as a `Grid` struct:
 /// ```text
-/// +---+-------+-+
-/// |   |       | |
-/// +---+-------+-+
-/// |   |       | |
-/// |   |       | |
-/// |   |       | |
-/// |   |       | |
-/// +---+-------+-+
+///
+/// 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:
+///
 /// ```text
-/// +---+-------+-+
-/// |   |       | |
-/// |   +-------+-+
-/// |   |         |
-/// |   |         |
-/// |   |         |
-/// |   |         |
-/// +---+-------+-+
+///  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 genrating a [`histogram`]:
+///
 /// ```
 /// use ndarray::{Array, array};
 /// use ndarray_stats::{
@@ -44,17 +68,14 @@ use std::ops::Range;
 /// };
 /// use noisy_float::types::{N64, n64};
 ///
-/// // 1-dimensional observations, as a (n_observations, 1) 2-d matrix
+/// // 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,
-/// // specifying a strategy (Auto in this case)
+/// // 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 expected_grid = Grid::from(vec![Bins::new(Edges::from(vec![1, 20, 39, 58, 77, 96, 115]))]);
-/// assert_eq!(grid, expected_grid);
 ///
 /// let histogram = observations.histogram(grid);
 ///
@@ -63,19 +84,22 @@ use std::ops::Range;
 /// let expected = array![4, 3, 3, 1, 0, 1];
 /// assert_eq!(histogram_matrix, expected.into_dyn());
 /// ```
+///
+/// [`histogram`]: trait.HistogramExt.html
+/// [`GridBuilder`]: struct.GridBuilder.html
+/// [`strategy`]: strategies/index.html
 #[derive(Clone, Debug, Eq, PartialEq)]
 pub struct Grid<A: Ord> {
     projections: Vec<Bins<A>>,
 }
 
 impl<A: Ord> From<Vec<Bins<A>>> for Grid<A> {
-    /// Get a `Grid` instance from a `Vec<Bins<A>>`.
+    /// Converts a `Vec<Bins<A>>` into a `Grid<A>`, consuming the vector of bins.
     ///
-    /// The `i`-th element in `Vec<Bins<A>>` represents the 1-dimensional
-    /// projection of the bin grid on the `i`-th axis.
+    /// 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`].
+    /// Alternatively, a `Grid` can be built directly from data using a [`GridBuilder`].
     ///
     /// [`GridBuilder`]: struct.GridBuilder.html
     fn from(projections: Vec<Bins<A>>) -> Self {
@@ -84,7 +108,7 @@ impl<A: Ord> From<Vec<Bins<A>>> for Grid<A> {
 }
 
 impl<A: Ord> Grid<A> {
-    /// Returns `n`, the number of dimensions of the region partitioned by the grid.
+    /// Returns the number of dimensions of the region partitioned by the grid.
     ///
     /// # Examples
     ///
@@ -101,7 +125,7 @@ impl<A: Ord> Grid<A> {
         self.projections.len()
     }
 
-    /// Returns the number of bins along each coordinate axis.
+    /// Returns the numbers of bins along each coordinate axis.
     ///
     /// # Examples
     ///
@@ -120,19 +144,19 @@ impl<A: Ord> Grid<A> {
         self.projections.iter().map(|e| e.len()).collect()
     }
 
-    /// Returns the grid projections on the coordinate axes as a slice of immutable references.
+    /// Returns the grid projections on each coordinate axis as a slice of immutable references.
     pub fn projections(&self) -> &[Bins<A>] {
         &self.projections
     }
 
-    /// Returns the index of the *n*-dimensional bin containing the point, if
-    /// one exists.
+    /// 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 `point.len()` does not equal `self.ndim()`.
+    /// Panics if dimensionality of the point doesn't equal the grid's.
     ///
     /// # Examples
     ///
@@ -147,18 +171,19 @@ impl<A: Ord> Grid<A> {
     /// let bins = Bins::new(edges);
     /// let square_grid = Grid::from(vec![bins.clone(), bins.clone()]);
     ///
-    /// // `0.` and `-0.7` falls in 1-st and 0-th bin respectively
+    /// // (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]),
     /// );
-    /// // `1.` is outside of the grid, return `None`
+    /// // Returns `None`, as `1.` is outside the grid since bins are right exclusive
     /// assert_eq!(
     ///     square_grid.index_of(&array![n64(0.), n64(1.)]),
     ///     None,
     /// );
     /// ```
-    /// A panic upon incompatible `point` length:
+    ///
+    /// A panic upon dimensionality mismatch:
     ///
     /// ```should_panic
     /// # use ndarray::array;
@@ -167,8 +192,8 @@ impl<A: Ord> Grid<A> {
     /// # 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()]);
+    /// // the point has 3 dimensions, the grid expected 2 dimensions
     /// assert_eq!(
-    ///     // the point has 3 dimensions, the grid expected 2 dimensions
     ///     square_grid.index_of(&array![n64(0.), n64(-0.7), n64(0.5)]),
     ///     Some(vec![1, 0, 1]),
     /// );
@@ -194,14 +219,15 @@ impl<A: Ord> Grid<A> {
 }
 
 impl<A: Ord + Clone> Grid<A> {
-    /// Given `i=(i_0, ..., i_{n-1})`, an `n`-dimensional index, it returns
-    /// `I_{i_0}x...xI_{i_{n-1}}`, an `n`-dimensional bin, where `I_{i_j}` is
-    /// the `i_j`-th interval on the `j`-th projection of the grid on the coordinate axes.
+    /// 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 among `(i_0, ..., i_{n-1})` is out of bounds on the respective
-    /// coordinate axis - i.e. if there exists `j` such that `i_j >= self.projections[j].len()`.
+    /// Panics if at least one in the index, `(i_0, ..., i_{n-1})`, is out of bound on the
+    /// corresponding coordinate axis, i.e. if there exists `j` s.t.
+    /// `i_j >= self.projections[j].len()`.
     ///
     /// # Examples
     ///
@@ -211,15 +237,16 @@ impl<A: Ord + Clone> Grid<A> {
     /// use ndarray::array;
     /// use ndarray_stats::histogram::{Edges, Bins, Grid};
     ///
-    /// let edges_x = Edges::from(vec![0, 1, 2]);
-    /// let edges_y = Edges::from(vec![3, 4, 5]);
+    /// 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, 4..5],
+    ///     vec![0..1, 3..4],
     /// );
     /// ```
     ///
@@ -228,15 +255,15 @@ impl<A: Ord + Clone> Grid<A> {
     /// ```should_panic
     /// # use ndarray::array;
     /// # use ndarray_stats::histogram::{Edges, Bins, Grid};
-    /// # let edges_x = Edges::from(vec![0, 1, 2]);
-    /// # let edges_y = Edges::from(vec![3, 4, 5]);
+    /// # 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]);
+    /// // out-of-bound on y-axis
     /// assert_eq!(
-    ///     // out-of-bound on `edges_y`
     ///     square_grid.index(&[0, 2]),
-    ///     vec![0..1, 1..2],
+    ///     vec![0..1, 3..4],
     /// );
     /// ```
     pub fn index(&self, index: &[usize]) -> Vec<Range<A>> {
@@ -254,8 +281,32 @@ impl<A: Ord + Clone> Grid<A> {
     }
 }
 
-/// Given a [`strategy`] and some observations, returns a [`Grid`] instance for [`histogram`]
-/// computation.
+/// A builder used to create [`Grid`] instances for [`histogram`] computations.
+///
+/// # Examples
+///
+/// Basic usage, creating a `Grid` with some observations and a given [`strategy`]:
+///
+/// ```
+/// use ndarray::{Array, array};
+/// use noisy_float::types::{N64, n64};
+/// use ndarray_stats::histogram::{
+///     strategies::Auto, Bins, Edges, Grid, GridBuilder, Histogram,
+/// };
+///
+/// // 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();
+/// // Equivalently, build a Grid directly
+/// let expected_grid = Grid::from(vec![Bins::new(Edges::from(vec![1, 20, 39, 58, 77, 96, 115]))]);
+///
+/// assert_eq!(grid, expected_grid);
+/// ```
 ///
 /// [`Grid`]: struct.Grid.html
 /// [`histogram`]: trait.HistogramExt.html
@@ -269,18 +320,22 @@ where
     A: Ord,
     B: BinsBuildingStrategy<Elem = A>,
 {
-    /// Given some observations in a 2-dimensional array with shape `(n_observations, n_dimension)`
-    /// it returns a `GridBuilder` instance that has learned the required parameter
-    /// to build a [`Grid`] according to the specified [`strategy`].
+    /// Returns a `GridBuilder` for building a [`Grid`] with a given [`strategy`] and some
+    /// observations in a 2-dimensionalarray with shape `(n_observations, n_dimension)`.
     ///
     /// # Errors
     ///
     /// It returns [`BinsBuildError`] if it is not possible to build a [`Grid`] given
     /// the observed data according to the chosen [`strategy`].
     ///
+    /// # Examples
+    ///
+    /// See [Trait-level examples] for basic usage.
+    ///
     /// [`Grid`]: struct.Grid.html
     /// [`strategy`]: strategies/index.html
     /// [`BinsBuildError`]: errors/enum.BinsBuildError.html
+    /// [Trait-level examples]: struct.GridBuilder.html#examples
     pub fn from_array<S>(array: &ArrayBase<S, Ix2>) -> Result<Self, BinsBuildError>
     where
         S: Data<Elem = A>,
@@ -292,8 +347,12 @@ where
         Ok(Self { bin_builders })
     }
 
-    /// Returns a [`Grid`] instance, built accordingly to the specified [`strategy`]
-    /// using the parameters inferred from observations in [`from_array`].
+    /// Returns a [`Grid`] instance, with building parameters infered in [`from_array`], according
+    /// to the specified [`strategy`] and observations provided.
+    ///
+    /// # Examples
+    ///
+    /// See [Trait-level examples] for basic usage.
     ///
     /// [`Grid`]: struct.Grid.html
     /// [`strategy`]: strategies/index.html