fixed lints

Author: DanielLacina

src/svm/svc.rs

@@ -62,6 +62,7 @@
 //! let svc = SVC::fit(&x, &y, parameters, None).unwrap();
 //!
 //! let y_hat = svc.predict(&x).unwrap();
+//! 
 //! ```
 //!
 //! ## References:
@@ -92,20 +93,43 @@ use crate::svm::Kernel;
 
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 #[derive(Debug)]
+/// Configuration for a multi-class Support Vector Machine (SVM) classifier.
+///
+/// This struct holds the indices of the data points relevant to a specific binary
+/// classification problem within a multi-class context, and the two classes
+/// being discriminated.
 pub struct MultiClassConfig<TY: Number + Ord> {
+    /// The indices of the data points from the original dataset that belong to the two `classes`.
     indices: Vec<usize>,
+    /// A tuple representing the two classes that this configuration is designed to distinguish.
     classes: (TY, TY),
 }
 
 impl<'a, TX: Number + RealNumber, TY: Number + Ord, X: Array2<TX>, Y: Array1<TY>>
     SupervisedEstimatorBorrow<'a, X, Y, SVCParameters<TX, TY, X, Y>>
     for MultiClassSVC<'a, TX, TY, X, Y>
 {
+    /// Creates a new, empty `MultiClassSVC` instance.
+    ///
+    /// The `classifiers` field is initialized to `Option::None`, indicating that
+    /// the model has not yet been fitted.
     fn new() -> Self {
         Self {
             classifiers: Option::None,
         }
     }
+
+    /// Fits the `MultiClassSVC` model to the provided data and parameters.
+    ///
+    /// This method delegates the fitting process to the inherent `MultiClassSVC::fit` method.
+    ///
+    /// # Arguments
+    /// * `x` - A reference to the input features (2D array).
+    /// * `y` - A reference to the target labels (1D array).
+    /// * `parameters` - A reference to the `SVCParameters` controlling the SVM training.
+    ///
+    /// # Returns
+    /// A `Result` indicating success (`Self`) or failure (`Failed`).
     fn fit(
         x: &'a X,
         y: &'a Y,
@@ -118,50 +142,95 @@ impl<'a, TX: Number + RealNumber, TY: Number + Ord, X: Array2<TX>, Y: Array1<TY>
 impl<'a, TX: Number + RealNumber, TY: Number + Ord, X: Array2<TX>, Y: Array1<TY>>
     PredictorBorrow<'a, X, TX> for MultiClassSVC<'a, TX, TY, X, Y>
 {
+    /// Predicts the class labels for new data points.
+    ///
+    /// This method delegates the prediction process to the inherent `MultiClassSVC::predict` method.
+    /// It unwraps the inner `Result` from `MultiClassSVC::predict`, assuming that
+    /// the prediction will always succeed after a successful fit.
+    ///
+    /// # Arguments
+    /// * `x` - A reference to the input features (2D array) for which to make predictions.
+    ///
+    /// # Returns
+    /// A `Result` containing a `Vec` of predicted class labels (`TX`) or a `Failed` error.
     fn predict(&self, x: &'a X) -> Result<Vec<TX>, Failed> {
         Ok(self.predict(x).unwrap())
     }
 }
 
+/// A multi-class Support Vector Machine (SVM) classifier.
+///
+/// This struct implements a multi-class SVM using the "one-vs-one" strategy,
+/// where a separate binary SVC classifier is trained for every pair of classes.
+///
+/// # Type Parameters
+/// * `'a` - Lifetime parameter for borrowed data.
+/// * `TX` - The numeric type of the input features (must implement `Number` and `RealNumber`).
+/// * `TY` - The numeric type of the target labels (must implement `Number` and `Ord`).
+/// * `X` - The type representing the 2D array of input features (e.g., a matrix).
+/// * `Y` - The type representing the 1D array of target labels (e.g., a vector).
 pub struct MultiClassSVC<
     'a,
     TX: Number + RealNumber,
     TY: Number + Ord,
     X: Array2<TX>,
     Y: Array1<TY>,
 > {
+    /// An optional vector of binary `SVC` classifiers.
+    ///
+    /// This will be `Some` after the model has been fitted, containing one `SVC`
+    /// for each pair of unique classes.
     classifiers: Option<Vec<SVC<'a, TX, TY, X, Y>>>,
 }
 
 impl<'a, TX: Number + RealNumber, TY: Number + Ord, X: Array2<TX>, Y: Array1<TY>>
     MultiClassSVC<'a, TX, TY, X, Y>
 {
+    /// Fits the `MultiClassSVC` model to the provided data using a one-vs-one strategy.
+    ///
+    /// This method identifies all unique classes in the target labels `y` and then
+    /// trains a binary `SVC` for every unique pair of classes. For each pair, it
+    /// extracts the relevant data points and their labels, and then trains a
+    /// specialized `SVC` for that binary classification task.
+    ///
+    /// # Arguments
+    /// * `x` - A reference to the input features (2D array).
+    /// * `y` - A reference to the target labels (1D array).
+    /// * `parameters` - A reference to the `SVCParameters` controlling the SVM training for each individual binary classifier.
+    ///  
+    ///
+    /// # Returns
+    /// A `Result` indicating success (`MultiClassSVC`) or failure (`Failed`).
     pub fn fit(
         x: &'a X,
         y: &'a Y,
         parameters: &'a SVCParameters<TX, TY, X, Y>,
     ) -> Result<MultiClassSVC<'a, TX, TY, X, Y>, Failed> {
         let unique_classes = y.unique();
         let mut classifiers = Vec::new();
+        // Iterate through all unique pairs of classes (one-vs-one strategy)
         for i in 0..unique_classes.len() {
             for j in i..unique_classes.len() {
                 if i == j {
-                    continue;
+                    continue; // Skip comparing a class to itself
                 }
                 let class0 = unique_classes[j];
                 let class1 = unique_classes[i];
+
                 let mut indices = Vec::new();
+                // Collect indices of data points belonging to the current pair of classes
                 for (index, v) in y.iterator(0).enumerate() {
                     if *v == class0 || *v == class1 {
                         indices.push(index)
                     }
                 }
                 let classes = (class0, class1);
                 let multiclass_config = MultiClassConfig {
-                    classes: classes.clone(),
+                    classes,
                     indices,
                 };
-                let svc = SVC::fit(x, y, parameters, Some(multiclass_config)).unwrap();
+                // Fit a binary SVC for the current pair of classes
+                let svc = SVC::fit(x, y, parameters, Some(multiclass_config)).unwrap(); // .unwrap() might panic if SVC::fit fails
                 classifiers.push(svc);
             }
         }
@@ -170,25 +239,50 @@ impl<'a, TX: Number + RealNumber, TY: Number + Ord, X: Array2<TX>, Y: Array1<TY>
         })
     }
 
+    /// Predicts the class labels for new data points using the trained multi-class SVM.
+    ///
+    /// This method uses a "voting" scheme (majority vote) among all the binary
+    /// classifiers to determine the final prediction for each data point.
+    ///
+    /// # Arguments
+    /// * `x` - A reference to the input features (2D array) for which to make predictions.
+    ///
+    /// # Returns
+    /// A `Result` containing a `Vec` of predicted class labels (`TX`) or a `Failed` error.
+    ///
+    /// # Panics
+    /// Panics if the model has not been fitted (`self.classifiers` is `None`).
     pub fn predict(&self, x: &X) -> Result<Vec<TX>, Failed> {
+        // Initialize a HashMap for each data point to store votes for each class
         let mut polls = vec![HashMap::new(); x.shape().0];
+        // Retrieve the trained binary classifiers; panics if not fitted
         let classifiers = self.classifiers.as_ref().unwrap();
+
+        // Iterate through each binary classifier
         for i in 0..classifiers.len() {
-            let svc = classifiers.get(i).unwrap();
-            let predictions = svc.predict(x).unwrap();
+            let svc = classifiers.get(i).unwrap(); // .unwrap() might panic if index is out of bounds
+            let predictions = svc.predict(x).unwrap(); // .unwrap() might panic if SVC::predict fails
+
+            // For each prediction from the current binary classifier
             for (j, prediction) in predictions.iter().enumerate() {
-                let prediction = prediction.to_i32().unwrap();
-                let poll = polls.get_mut(j).unwrap();
+                let prediction = prediction.to_i32().unwrap(); // Convert prediction to i32 for HashMap key
+                let poll = polls.get_mut(j).unwrap(); // Get the poll for the current data point
+                // Increment the vote for the predicted class
                 if let Some(count) = poll.get_mut(&prediction) {
                     *count += 1
                 } else {
                     poll.insert(prediction, 1);
                 }
             }
         }
+
+        // Determine the final prediction for each data point based on majority vote
         Ok(polls
             .iter()
-            .map(|v| TX::from(*v.iter().max_by_key(|(_, class)| *class).unwrap().0).unwrap())
+            .map(|v| {
+                // Find the class with the maximum votes for each data point
+                TX::from(*v.iter().max_by_key(|(_, class)| *class).unwrap().0).unwrap()
+            })
             .collect())
     }
 }