FEAT: New method names sum → sum_axis, mean → mean_axis

Old names are deprecated. This standardizes on a *_axis convention for
these methods (more: map_axis, fold_axis). This makes room for
.scalar_sum to take the name sum at a later date, and it makes room for
introducing both std and std_axis for standard dev.

Author: bluss

benches/bench1.rs

@@ -961,23 +961,23 @@ fn range_mat(m: Ix, n: Ix) -> Array2<f32> {
 #[bench]
 fn mean_axis0(bench: &mut test::Bencher) {
     let a = range_mat(MEAN_SUM_N, MEAN_SUM_N);
-    bench.iter(|| a.mean(Axis(0)));
+    bench.iter(|| a.mean_axis(Axis(0)));
 }
 
 #[bench]
 fn mean_axis1(bench: &mut test::Bencher) {
     let a = range_mat(MEAN_SUM_N, MEAN_SUM_N);
-    bench.iter(|| a.mean(Axis(1)));
+    bench.iter(|| a.mean_axis(Axis(1)));
 }
 
 #[bench]
 fn sum_axis0(bench: &mut test::Bencher) {
     let a = range_mat(MEAN_SUM_N, MEAN_SUM_N);
-    bench.iter(|| a.sum(Axis(0)));
+    bench.iter(|| a.sum_axis(Axis(0)));
 }
 
 #[bench]
 fn sum_axis1(bench: &mut test::Bencher) {
     let a = range_mat(MEAN_SUM_N, MEAN_SUM_N);
-    bench.iter(|| a.sum(Axis(1)));
+    bench.iter(|| a.sum_axis(Axis(1)));
 }

examples/column_standardize.rs

@@ -25,9 +25,9 @@ fn main() {
                           [ 2.,  2.,  2.]];
 
     println!("{:8.4}", data);
-    println!("{:8.4} (Mean axis=0)", data.mean(Axis(0)));
+    println!("{:8.4} (Mean axis=0)", data.mean_axis(Axis(0)));
 
-    data -= &data.mean(Axis(0));
+    data -= &data.mean_axis(Axis(0));
     println!("{:8.4}", data);
 
     data /= &std(&data, Axis(0));

src/numeric/impl_numeric.rs

@@ -58,15 +58,15 @@ impl<A, S, D> ArrayBase<S, D>
     /// let a = arr2(&[[1., 2.],
     ///                [3., 4.]]);
     /// assert!(
-    ///     a.sum(Axis(0)) == aview1(&[4., 6.]) &&
-    ///     a.sum(Axis(1)) == aview1(&[3., 7.]) &&
+    ///     a.sum_axis(Axis(0)) == aview1(&[4., 6.]) &&
+    ///     a.sum_axis(Axis(1)) == aview1(&[3., 7.]) &&
     ///
-    ///     a.sum(Axis(0)).sum(Axis(0)) == aview0(&10.)
+    ///     a.sum_axis(Axis(0)).sum_axis(Axis(0)) == aview0(&10.)
     /// );
     /// ```
     ///
     /// **Panics** if `axis` is out of bounds.
-    pub fn sum(&self, axis: Axis) -> Array<A, D::Smaller>
+    pub fn sum_axis(&self, axis: Axis) -> Array<A, D::Smaller>
         where A: Clone + Zero + Add<Output=A>,
               D: RemoveAxis,
     {
@@ -88,6 +88,15 @@ impl<A, S, D> ArrayBase<S, D>
         res
     }
 
+    /// Old name for `sum_axis`.
+    #[deprecated(note="Use new name .sum_axis()")]
+    pub fn sum(&self, axis: Axis) -> Array<A, D::Smaller>
+        where A: Clone + Zero + Add<Output=A>,
+              D: RemoveAxis,
+    {
+        self.sum_axis(axis)
+    }
+
     /// Return mean along `axis`.
     ///
     /// **Panics** if `axis` is out of bounds.
@@ -98,23 +107,32 @@ impl<A, S, D> ArrayBase<S, D>
     /// let a = arr2(&[[1., 2.],
     ///                [3., 4.]]);
     /// assert!(
-    ///     a.mean(Axis(0)) == aview1(&[2.0, 3.0]) &&
-    ///     a.mean(Axis(1)) == aview1(&[1.5, 3.5])
+    ///     a.mean_axis(Axis(0)) == aview1(&[2.0, 3.0]) &&
+    ///     a.mean_axis(Axis(1)) == aview1(&[1.5, 3.5])
     /// );
     /// ```
-    pub fn mean(&self, axis: Axis) -> Array<A, D::Smaller>
+    pub fn mean_axis(&self, axis: Axis) -> Array<A, D::Smaller>
         where A: LinalgScalar,
               D: RemoveAxis,
     {
         let n = self.shape().axis(axis);
-        let sum = self.sum(axis);
+        let sum = self.sum_axis(axis);
         let mut cnt = A::one();
         for _ in 1..n {
             cnt = cnt + A::one();
         }
         sum / &aview0(&cnt)
     }
 
+    /// Old name for `mean_axis`.
+    #[deprecated(note="Use new name .mean_axis()")]
+    pub fn mean(&self, axis: Axis) -> Array<A, D::Smaller>
+        where A: LinalgScalar,
+              D: RemoveAxis,
+    {
+        self.mean_axis(axis)
+    }
+
     /// Return `true` if the arrays' elementwise differences are all within
     /// the given absolute tolerance, `false` otherwise.
     ///

src/zip/mod.rs

@@ -444,8 +444,8 @@ impl<'a, A, D: Dimension> NdProducer for ArrayViewMut<'a, A, D> {
 ///         *e = row.scalar_sum();
 ///     });
 ///
-/// // Check the result against the built in `.sum()` along axis 1.
-/// assert_eq!(e, a.sum(Axis(1)));
+/// // Check the result against the built in `.sum_axis()` along axis 1.
+/// assert_eq!(e, a.sum_axis(Axis(1)));
 /// ```
 #[derive(Debug, Clone)]
 pub struct Zip<Parts, D> {

tests/array.rs

@@ -340,12 +340,12 @@ fn assign()
 fn sum_mean()
 {
     let a = arr2(&[[1., 2.], [3., 4.]]);
-    assert_eq!(a.sum(Axis(0)), arr1(&[4., 6.]));
-    assert_eq!(a.sum(Axis(1)), arr1(&[3., 7.]));
-    assert_eq!(a.mean(Axis(0)), arr1(&[2., 3.]));
-    assert_eq!(a.mean(Axis(1)), arr1(&[1.5, 3.5]));
-    assert_eq!(a.sum(Axis(1)).sum(Axis(0)), arr0(10.));
-    assert_eq!(a.view().mean(Axis(1)), aview1(&[1.5, 3.5]));
+    assert_eq!(a.sum_axis(Axis(0)), arr1(&[4., 6.]));
+    assert_eq!(a.sum_axis(Axis(1)), arr1(&[3., 7.]));
+    assert_eq!(a.mean_axis(Axis(0)), arr1(&[2., 3.]));
+    assert_eq!(a.mean_axis(Axis(1)), arr1(&[1.5, 3.5]));
+    assert_eq!(a.sum_axis(Axis(1)).sum_axis(Axis(0)), arr0(10.));
+    assert_eq!(a.view().mean_axis(Axis(1)), aview1(&[1.5, 3.5]));
     assert_eq!(a.scalar_sum(), 10.);
 }
 

tests/azip.rs

@@ -52,7 +52,7 @@ fn test_azip2_sum() {
         let ax = Axis(i);
         let mut b = Array::zeros(c.len_of(ax));
         azip!(mut b, ref c (c.axis_iter(ax)) in { *b = c.scalar_sum() });
-        assert!(b.all_close(&c.sum(Axis(1 - i)), 1e-6));
+        assert!(b.all_close(&c.sum_axis(Axis(1 - i)), 1e-6));
     }
 }
 

tests/complex.rs

@@ -22,5 +22,5 @@ fn complex_mat_mul()
     let r = a.dot(&e);
     println!("{}", a);
     assert_eq!(r, a);
-    assert_eq!(a.mean(Axis(0)), arr1(&[c(1.5, 1.), c(2.5, 0.)]));
+    assert_eq!(a.mean_axis(Axis(0)), arr1(&[c(1.5, 1.), c(2.5, 0.)]));
 }