feat: refactoring, adds Result to most public API

Author: Volodymyr Orlov

src/algorithm/neighbour/cover_tree.rs

@@ -16,7 +16,7 @@
 //!
 //! let data = vec![1, 2, 3, 4, 5, 6, 7, 8, 9]; // data points
 //!
-//! let mut tree = CoverTree::new(data, SimpleDistance {});
+//! let mut tree = CoverTree::new(data, SimpleDistance {}).unwrap();
 //!
 //! tree.find(&5, 3); // find 3 knn points from 5
 //!
@@ -26,6 +26,7 @@ use std::fmt::Debug;
 use serde::{Deserialize, Serialize};
 
 use crate::algorithm::sort::heap_select::HeapSelection;
+use crate::error::{Failed, FailedError};
 use crate::math::distance::Distance;
 use crate::math::num::RealNumber;
 
@@ -73,7 +74,7 @@ impl<T: Debug + PartialEq, F: RealNumber, D: Distance<T, F>> CoverTree<T, F, D>
     /// Construct a cover tree.
     /// * `data` - vector of data points to search for.
     /// * `distance` - distance metric to use for searching. This function should extend [`Distance`](../../../math/distance/index.html) interface.
-    pub fn new(data: Vec<T>, distance: D) -> CoverTree<T, F, D> {
+    pub fn new(data: Vec<T>, distance: D) -> Result<CoverTree<T, F, D>, Failed> {
         let base = F::from_f64(1.3).unwrap();
         let root = Node {
             idx: 0,
@@ -93,19 +94,22 @@ impl<T: Debug + PartialEq, F: RealNumber, D: Distance<T, F>> CoverTree<T, F, D>
 
         tree.build_cover_tree();
 
-        tree
+        Ok(tree)
     }
 
     /// Find k nearest neighbors of `p`
     /// * `p` - look for k nearest points to `p`
     /// * `k` - the number of nearest neighbors to return
-    pub fn find(&self, p: &T, k: usize) -> Vec<(usize, F)> {
+    pub fn find(&self, p: &T, k: usize) -> Result<Vec<(usize, F)>, Failed> {
         if k <= 0 {
-            panic!("k should be > 0");
+            return Err(Failed::because(FailedError::FindFailed, "k should be > 0"));
         }
 
         if k > self.data.len() {
-            panic!("k is > than the dataset size");
+            return Err(Failed::because(
+                FailedError::FindFailed,
+                "k is > than the dataset size",
+            ));
         }
 
         let e = self.get_data_value(self.root.idx);
@@ -171,7 +175,7 @@ impl<T: Debug + PartialEq, F: RealNumber, D: Distance<T, F>> CoverTree<T, F, D>
             }
         }
 
-        neighbors.into_iter().take(k).collect()
+        Ok(neighbors.into_iter().take(k).collect())
     }
 
     fn new_leaf(&self, idx: usize) -> Node<F> {
@@ -407,9 +411,9 @@ mod tests {
     fn cover_tree_test() {
         let data = vec![1, 2, 3, 4, 5, 6, 7, 8, 9];
 
-        let tree = CoverTree::new(data, SimpleDistance {});
+        let tree = CoverTree::new(data, SimpleDistance {}).unwrap();
 
-        let mut knn = tree.find(&5, 3);
+        let mut knn = tree.find(&5, 3).unwrap();
         knn.sort_by(|a, b| a.0.partial_cmp(&b.0).unwrap());
         let knn: Vec<usize> = knn.iter().map(|v| v.0).collect();
         assert_eq!(vec!(3, 4, 5), knn);
@@ -425,9 +429,9 @@ mod tests {
             vec![9., 10.],
         ];
 
-        let tree = CoverTree::new(data, Distances::euclidian());
+        let tree = CoverTree::new(data, Distances::euclidian()).unwrap();
 
-        let mut knn = tree.find(&vec![1., 2.], 3);
+        let mut knn = tree.find(&vec![1., 2.], 3).unwrap();
         knn.sort_by(|a, b| a.0.partial_cmp(&b.0).unwrap());
         let knn: Vec<usize> = knn.iter().map(|v| v.0).collect();
 
@@ -438,7 +442,7 @@ mod tests {
     fn serde() {
         let data = vec![1, 2, 3, 4, 5, 6, 7, 8, 9];
 
-        let tree = CoverTree::new(data, SimpleDistance {});
+        let tree = CoverTree::new(data, SimpleDistance {}).unwrap();
 
         let deserialized_tree: CoverTree<i32, f64, SimpleDistance> =
             serde_json::from_str(&serde_json::to_string(&tree).unwrap()).unwrap();

src/algorithm/neighbour/linear_search.rs

@@ -15,7 +15,7 @@
 //!
 //! let data = vec![1, 2, 3, 4, 5, 6, 7, 8, 9]; // data points
 //!
-//! let knn = LinearKNNSearch::new(data, SimpleDistance {});
+//! let knn = LinearKNNSearch::new(data, SimpleDistance {}).unwrap();
 //!
 //! knn.find(&5, 3); // find 3 knn points from 5
 //!
@@ -26,6 +26,7 @@ use std::cmp::{Ordering, PartialOrd};
 use std::marker::PhantomData;
 
 use crate::algorithm::sort::heap_select::HeapSelection;
+use crate::error::Failed;
 use crate::math::distance::Distance;
 use crate::math::num::RealNumber;
 
@@ -41,18 +42,18 @@ impl<T, F: RealNumber, D: Distance<T, F>> LinearKNNSearch<T, F, D> {
     /// Initializes algorithm.
     /// * `data` - vector of data points to search for.
     /// * `distance` - distance metric to use for searching. This function should extend [`Distance`](../../../math/distance/index.html) interface.
-    pub fn new(data: Vec<T>, distance: D) -> LinearKNNSearch<T, F, D> {
-        LinearKNNSearch {
+    pub fn new(data: Vec<T>, distance: D) -> Result<LinearKNNSearch<T, F, D>, Failed> {
+        Ok(LinearKNNSearch {
             data: data,
             distance: distance,
             f: PhantomData,
-        }
+        })
     }
 
     /// Find k nearest neighbors
     /// * `from` - look for k nearest points to `from`
     /// * `k` - the number of nearest neighbors to return
-    pub fn find(&self, from: &T, k: usize) -> Vec<(usize, F)> {
+    pub fn find(&self, from: &T, k: usize) -> Result<Vec<(usize, F)>, Failed> {
         if k < 1 || k > self.data.len() {
             panic!("k should be >= 1 and <= length(data)");
         }
@@ -76,10 +77,11 @@ impl<T, F: RealNumber, D: Distance<T, F>> LinearKNNSearch<T, F, D> {
             }
         }
 
-        heap.get()
+        Ok(heap
+            .get()
             .into_iter()
             .flat_map(|x| x.index.map(|i| (i, x.distance)))
-            .collect()
+            .collect())
     }
 }
 
@@ -120,9 +122,14 @@ mod tests {
     fn knn_find() {
         let data1 = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
 
-        let algorithm1 = LinearKNNSearch::new(data1, SimpleDistance {});
+        let algorithm1 = LinearKNNSearch::new(data1, SimpleDistance {}).unwrap();
 
-        let mut found_idxs1: Vec<usize> = algorithm1.find(&2, 3).iter().map(|v| v.0).collect();
+        let mut found_idxs1: Vec<usize> = algorithm1
+            .find(&2, 3)
+            .unwrap()
+            .iter()
+            .map(|v| v.0)
+            .collect();
         found_idxs1.sort();
 
         assert_eq!(vec!(0, 1, 2), found_idxs1);
@@ -135,10 +142,11 @@ mod tests {
             vec![5., 5.],
         ];
 
-        let algorithm2 = LinearKNNSearch::new(data2, Distances::euclidian());
+        let algorithm2 = LinearKNNSearch::new(data2, Distances::euclidian()).unwrap();
 
         let mut found_idxs2: Vec<usize> = algorithm2
             .find(&vec![3., 3.], 3)
+            .unwrap()
             .iter()
             .map(|v| v.0)
             .collect();

src/cluster/kmeans.rs

@@ -61,7 +61,7 @@ use std::iter::Sum;
 use serde::{Deserialize, Serialize};
 
 use crate::algorithm::neighbour::bbd_tree::BBDTree;
-use crate::error::{FitFailedError, PredictFailedError};
+use crate::error::Failed;
 use crate::linalg::Matrix;
 use crate::math::distance::euclidian::*;
 use crate::math::num::RealNumber;
@@ -122,19 +122,16 @@ impl<T: RealNumber + Sum> KMeans<T> {
         data: &M,
         k: usize,
         parameters: KMeansParameters,
-    ) -> Result<KMeans<T>, FitFailedError> {
+    ) -> Result<KMeans<T>, Failed> {
         let bbd = BBDTree::new(data);
 
         if k < 2 {
-            return Err(FitFailedError::new(&format!(
-                "Invalid number of clusters: {}",
-                k
-            )));
+            return Err(Failed::fit(&format!("invalid number of clusters: {}", k)));
         }
 
         if parameters.max_iter <= 0 {
-            return Err(FitFailedError::new(&format!(
-                "Invalid maximum number of iterations: {}",
+            return Err(Failed::fit(&format!(
+                "invalid maximum number of iterations: {}",
                 parameters.max_iter
             )));
         }
@@ -191,7 +188,7 @@ impl<T: RealNumber + Sum> KMeans<T> {
 
     /// Predict clusters for `x`
     /// * `x` - matrix with new data to transform of size _KxM_ , where _K_ is number of new samples and _M_ is number of features.
-    pub fn predict<M: Matrix<T>>(&self, x: &M) -> Result<M::RowVector, PredictFailedError> {
+    pub fn predict<M: Matrix<T>>(&self, x: &M) -> Result<M::RowVector, Failed> {
         let (n, _) = x.shape();
         let mut result = M::zeros(1, n);
 
@@ -274,11 +271,9 @@ mod tests {
     fn invalid_k() {
         let x = DenseMatrix::from_2d_array(&[&[1., 2., 3.], &[4., 5., 6.]]);
 
-        println!("{:?}", KMeans::fit(&x, 0, Default::default()));
-
         assert!(KMeans::fit(&x, 0, Default::default()).is_err());
         assert_eq!(
-            "Invalid number of clusters: 1",
+            "Fit failed: invalid number of clusters: 1",
             KMeans::fit(&x, 1, Default::default())
                 .unwrap_err()
                 .to_string()

src/decomposition/pca.rs

@@ -37,9 +37,9 @@
 //!                     &[5.2, 2.7, 3.9, 1.4],
 //!                     ]);
 //!
-//! let pca = PCA::new(&iris, 2, Default::default()); // Reduce number of features to 2
+//! let pca = PCA::fit(&iris, 2, Default::default()).unwrap(); // Reduce number of features to 2
 //!
-//! let iris_reduced = pca.transform(&iris);
+//! let iris_reduced = pca.transform(&iris).unwrap();
 //!
 //! ```
 //!
@@ -49,6 +49,7 @@ use std::fmt::Debug;
 
 use serde::{Deserialize, Serialize};
 
+use crate::error::Failed;
 use crate::linalg::Matrix;
 use crate::math::num::RealNumber;
 
@@ -100,7 +101,11 @@ impl<T: RealNumber, M: Matrix<T>> PCA<T, M> {
     /// * `data` - _NxM_ matrix with _N_ observations and _M_ features in each observation.
     /// * `n_components` - number of components to keep.
     /// * `parameters` - other parameters, use `Default::default()` to set parameters to default values.
-    pub fn new(data: &M, n_components: usize, parameters: PCAParameters) -> PCA<T, M> {
+    pub fn fit(
+        data: &M,
+        n_components: usize,
+        parameters: PCAParameters,
+    ) -> Result<PCA<T, M>, Failed> {
         let (m, n) = data.shape();
 
         let mu = data.column_mean();
@@ -117,7 +122,7 @@ impl<T: RealNumber, M: Matrix<T>> PCA<T, M> {
         let mut eigenvectors;
 
         if m > n && !parameters.use_correlation_matrix {
-            let svd = x.svd();
+            let svd = x.svd()?;
             eigenvalues = svd.s;
             for i in 0..eigenvalues.len() {
                 eigenvalues[i] = eigenvalues[i] * eigenvalues[i];
@@ -155,7 +160,7 @@ impl<T: RealNumber, M: Matrix<T>> PCA<T, M> {
                     }
                 }
 
-                let evd = cov.evd(true);
+                let evd = cov.evd(true)?;
 
                 eigenvalues = evd.d;
 
@@ -167,7 +172,7 @@ impl<T: RealNumber, M: Matrix<T>> PCA<T, M> {
                     }
                 }
             } else {
-                let evd = cov.evd(true);
+                let evd = cov.evd(true)?;
 
                 eigenvalues = evd.d;
 
@@ -189,26 +194,26 @@ impl<T: RealNumber, M: Matrix<T>> PCA<T, M> {
             }
         }
 
-        PCA {
+        Ok(PCA {
             eigenvectors: eigenvectors,
             eigenvalues: eigenvalues,
             projection: projection.transpose(),
             mu: mu,
             pmu: pmu,
-        }
+        })
     }
 
     /// Run dimensionality reduction for `x`
     /// * `x` - _KxM_ data where _K_ is number of observations and _M_ is number of features.
-    pub fn transform(&self, x: &M) -> M {
+    pub fn transform(&self, x: &M) -> Result<M, Failed> {
         let (nrows, ncols) = x.shape();
         let (_, n_components) = self.projection.shape();
         if ncols != self.mu.len() {
-            panic!(
+            return Err(Failed::transform(&format!(
                 "Invalid input vector size: {}, expected: {}",
                 ncols,
                 self.mu.len()
-            );
+            )));
         }
 
         let mut x_transformed = x.matmul(&self.projection);
@@ -217,7 +222,7 @@ impl<T: RealNumber, M: Matrix<T>> PCA<T, M> {
                 x_transformed.sub_element_mut(r, c, self.pmu[c]);
             }
         }
-        x_transformed
+        Ok(x_transformed)
     }
 }
 
@@ -372,7 +377,7 @@ mod tests {
             302.04806302399646,
         ];
 
-        let pca = PCA::new(&us_arrests, 4, Default::default());
+        let pca = PCA::fit(&us_arrests, 4, Default::default()).unwrap();
 
         assert!(pca
             .eigenvectors
@@ -383,7 +388,7 @@ mod tests {
             assert!((pca.eigenvalues[i].abs() - expected_eigenvalues[i].abs()).abs() < 1e-8);
         }
 
-        let us_arrests_t = pca.transform(&us_arrests);
+        let us_arrests_t = pca.transform(&us_arrests).unwrap();
 
         assert!(us_arrests_t
             .abs()
@@ -481,13 +486,14 @@ mod tests {
             0.1734300877298357,
         ];
 
-        let pca = PCA::new(
+        let pca = PCA::fit(
             &us_arrests,
             4,
             PCAParameters {
                 use_correlation_matrix: true,
             },
-        );
+        )
+        .unwrap();
 
         assert!(pca
             .eigenvectors
@@ -498,7 +504,7 @@ mod tests {
             assert!((pca.eigenvalues[i].abs() - expected_eigenvalues[i].abs()).abs() < 1e-8);
         }
 
-        let us_arrests_t = pca.transform(&us_arrests);
+        let us_arrests_t = pca.transform(&us_arrests).unwrap();
 
         assert!(us_arrests_t
             .abs()
@@ -530,7 +536,7 @@ mod tests {
             &[5.2, 2.7, 3.9, 1.4],
         ]);
 
-        let pca = PCA::new(&iris, 4, Default::default());
+        let pca = PCA::fit(&iris, 4, Default::default()).unwrap();
 
         let deserialized_pca: PCA<f64, DenseMatrix<f64>> =
             serde_json::from_str(&serde_json::to_string(&pca).unwrap()).unwrap();