DOC: Update column_standardize, axis_ops, zip_may examples

Update column_standardize to use new functionality in ndarray.
Update the examples, clean them up a bit, add comments.

Author: bluss

examples/axis_ops.rs

@@ -7,7 +7,16 @@
 
 use ndarray::prelude::*;
 
-fn regularize<A, D>(a: &mut Array<A, D>) -> Result<(), ()>
+/// Reorder a's axes so that they are in "standard" axis order;
+/// make sure axes are in positive stride direction, and merge adjacent
+/// axes if possible.
+///
+/// This changes the logical order of the elments in the
+/// array, so that if we read them in row-major order after regularization,
+/// it corresponds to their order in memory.
+///
+/// Errors if array has a 0-stride axis
+fn regularize<A, D>(a: &mut Array<A, D>) -> Result<(), &'static str>
 where
     D: Dimension,
     A: ::std::fmt::Debug,
@@ -16,7 +25,9 @@ where
     // reverse all neg axes
     while let Some(ax) = a.axes().find(|ax| ax.stride <= 0) {
         if ax.stride == 0 {
-            return Err(());
+            // no real reason to error on this case; other than
+            // stride == 0 is incompatible with an owned array.
+            return Err("Cannot regularize array with stride == 0 axis");
         }
         // reverse ax
         println!("Reverse {:?}", ax.axis);
@@ -27,8 +38,11 @@ where
     let mut i = 0;
     let n = a.ndim();
     while let Some(ax) = a.axes().rev().skip(i).min_by_key(|ax| ax.stride.abs()) {
-        a.swap_axes(n - 1 - i, ax.axis.index());
-        println!("Swap {:?} <=> {}", ax.axis, n - 1 - i);
+        let cur_axis = Axis(n - 1 - i);
+        if ax.axis != cur_axis {
+            a.swap_axes(cur_axis.index(), ax.axis.index());
+            println!("Swap {:?} <=> {:?}", cur_axis, ax.axis);
+        }
         i += 1;
     }
 
@@ -40,7 +54,7 @@ where
             break;
         }
     }
-    println!("{:?}", a);
+    println!("Result:\n{:?}\n", a);
     Ok(())
 }
 
@@ -52,22 +66,24 @@ fn main() {
     a.swap_axes(0, 1);
     a.swap_axes(0, 2);
     a.slice_collapse(s![.., ..;-1, ..]);
-    regularize(&mut a).ok();
+    regularize(&mut a).unwrap();
 
     let mut b = Array::<u8, _>::zeros((2, 3, 4));
     for (i, elt) in (0..).zip(&mut b) {
         *elt = i;
     }
-    regularize(&mut b).ok();
+    regularize(&mut b).unwrap();
+
     let mut b = b.into_shape(a.len()).unwrap();
-    regularize(&mut b).ok();
+    regularize(&mut b).unwrap();
+
     b.invert_axis(Axis(0));
-    regularize(&mut b).ok();
+    regularize(&mut b).unwrap();
 
     let mut a = Array::<u8, _>::zeros((2, 3, 4));
     for (i, elt) in (0..).zip(&mut a) {
         *elt = i;
     }
     a.slice_collapse(s![..;-1, ..;2, ..]);
-    regularize(&mut a).ok();
+    regularize(&mut a).unwrap();
 }

examples/column_standardize.rs

@@ -1,31 +1,21 @@
 use ndarray::prelude::*;
 
-fn std1d(a: ArrayView1<'_, f64>) -> f64 {
-    let n = a.len() as f64;
-    if n == 0. {
-        return 0.;
-    }
-    let mean = a.sum() / n;
-    (a.fold(0., |acc, &x| acc + (x - mean).powi(2)) / n).sqrt()
-}
-
-fn std(a: &Array2<f64>, axis: Axis) -> Array1<f64> {
-    a.map_axis(axis, std1d)
-}
-
 fn main() {
-    // "recreating the following"
+    // This example recreates the following from python/numpy
     // counts -= np.mean(counts, axis=0)
     // counts /= np.std(counts, axis=0)
 
     let mut data = array![[-1., -2., -3.], [1., -3., 5.], [2., 2., 2.]];
 
     println!("{:8.4}", data);
-    println!("{:8.4} (Mean axis=0)", data.mean_axis(Axis(0)).unwrap());
+    println!("Mean along axis=0 (along columns):\n{:8.4}", data.mean_axis(Axis(0)).unwrap());
 
     data -= &data.mean_axis(Axis(0)).unwrap();
-    println!("{:8.4}", data);
+    println!("Centered around mean:\n{:8.4}", data);
 
-    data /= &std(&data, Axis(0));
-    println!("{:8.4}", data);
+    data /= &data.std_axis(Axis(0), 0.);
+    println!("Scaled to normalize std:\n{:8.4}", data);
+
+    println!("New mean:\n{:8.4}", data.mean_axis(Axis(0)).unwrap());
+    println!("New std: \n{:8.4}", data.std_axis(Axis(0), 0.));
 }

examples/sort-axis.rs

@@ -1,3 +1,7 @@
+//! This is an example of sorting arrays along an axis.
+//! This file may not be so instructive except for advanced users, instead it
+//! could be a "feature preview" before sorting is added to the main crate.
+//!
 use ndarray::prelude::*;
 use ndarray::{Data, RemoveAxis, Zip};
 

examples/zip_many.rs

@@ -9,45 +9,40 @@ use ndarray::prelude::*;
 use ndarray::Zip;
 
 fn main() {
-    let n = 16;
+    let n = 6;
+
     let mut a = Array::<f32, _>::zeros((n, n));
-    let mut b = Array::<f32, _>::from_elem((n, n), 1.);
+    let mut b = Array::<f32, _>::zeros((n, n));
     for ((i, j), elt) in b.indexed_iter_mut() {
-        *elt /= 1. + (i + 2 * j) as f32;
+        *elt = 1. / (1. + (i + 2 * j) as f32);
     }
     let c = Array::<f32, _>::from_elem((n, n + 1), 1.7);
     let c = c.slice(s![.., ..-1]);
 
-    {
-        let a = a.view_mut().reversed_axes();
-        azip!((a in a, &b in b.t()) *a = b);
-    }
-    assert_eq!(a, b);
+    // Using Zip for arithmetic ops across a, b, c
+    Zip::from(&mut a).and(&b).and(&c)
+        .for_each(|a, &b, &c| *a = b + c);
+    assert_eq!(a, &b + &c);
 
+    // and this is how to do the *same thing* with azip!()
     azip!((a in &mut a, &b in &b, &c in c) *a = b + c);
-    assert_eq!(a, &b + &c);
+
+    println!("{:8.4}", a);
 
     // sum of each row
-    let ax = Axis(0);
-    let mut sums = Array::zeros(a.len_of(ax));
-    azip!((s in &mut sums, a in a.axis_iter(ax)) *s = a.sum());
+    let mut sums = Array::zeros(a.nrows());
+    Zip::from(a.rows()).and(&mut sums)
+        .for_each(|row, sum| *sum = row.sum());
+    // show sums as a column matrix
+    println!("{:8.4}", sums.insert_axis(Axis(1)));
 
-    // sum of each chunk
+    // sum of each 2x2 chunk
     let chunk_sz = (2, 2);
     let nchunks = (n / chunk_sz.0, n / chunk_sz.1);
     let mut sums = Array::zeros(nchunks);
-    azip!((s in &mut sums, a in a.exact_chunks(chunk_sz)) *s = a.sum());
-
-    // Let's imagine we split to parallelize
-    {
-        let (x, y) = Zip::indexed(&mut a).split();
-        x.for_each(|(_, j), elt| {
-            *elt = elt.powi(j as i32);
-        });
-
-        y.for_each(|(_, j), elt| {
-            *elt = elt.powi(j as i32);
-        });
-    }
-    println!("{:8.3?}", a);
+
+    Zip::from(a.exact_chunks(chunk_sz))
+        .and(&mut sums)
+        .for_each(|chunk, sum| *sum = chunk.sum());
+    println!("{:8.4}", sums);
 }