feat: documents metric functions

src/metrics/f1.rs

@@ -1,3 +1,22 @@
+//! # F-measure
+//!
+//! Harmonic mean of the precision and recall.
+//!
+//! \\[f1 = (1 + \beta^2)\frac{precision \times recall}{\beta^2 \times precision + recall}\\]
+//!
+//! where \\(\beta \\) is a positive real factor, where \\(\beta \\) is chosen such that recall is considered \\(\beta \\) times as important as precision.
+//!
+//! Example:
+//!
+//! ```
+//! use smartcore::metrics::f1::F1;
+//! let y_pred: Vec<f64> = vec![0., 0., 1., 1., 1., 1.];
+//! let y_true: Vec<f64> = vec![0., 1., 1., 0., 1., 0.];
+//!
+//! let score: f64 = F1 {beta: 1.0}.get_score(&y_pred, &y_true);
+//! ```
+//!
+//! <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS_CHTML"></script>
 use serde::{Deserialize, Serialize};
 
 use crate::linalg::BaseVector;
@@ -5,11 +24,18 @@ use crate::math::num::RealNumber;
 use crate::metrics::precision::Precision;
 use crate::metrics::recall::Recall;
 
+/// F-measure
 #[derive(Serialize, Deserialize, Debug)]
-pub struct F1 {}
+pub struct F1<T: RealNumber> {
+    /// a positive real factor
+    pub beta: T,
+}
 
-impl F1 {
-    pub fn get_score<T: RealNumber, V: BaseVector<T>>(&self, y_true: &V, y_pred: &V) -> T {
+impl<T: RealNumber> F1<T> {
+    /// Computes F1 score
+    /// * `y_true` - cround truth (correct) labels.
+    /// * `y_pred` - predicted labels, as returned by a classifier.
+    pub fn get_score<V: BaseVector<T>>(&self, y_true: &V, y_pred: &V) -> T {
         if y_true.len() != y_pred.len() {
             panic!(
                 "The vector sizes don't match: {} != {}",
@@ -17,7 +43,7 @@ impl F1 {
                 y_pred.len()
             );
         }
-        let beta2 = T::one();
+        let beta2 = self.beta * self.beta;
 
         let p = Precision {}.get_score(y_true, y_pred);
         let r = Recall {}.get_score(y_true, y_pred);
@@ -35,8 +61,8 @@ mod tests {
         let y_pred: Vec<f64> = vec![0., 0., 1., 1., 1., 1.];
         let y_true: Vec<f64> = vec![0., 1., 1., 0., 1., 0.];
 
-        let score1: f64 = F1 {}.get_score(&y_pred, &y_true);
-        let score2: f64 = F1 {}.get_score(&y_true, &y_true);
+        let score1: f64 = F1 { beta: 1.0 }.get_score(&y_pred, &y_true);
+        let score2: f64 = F1 { beta: 1.0 }.get_score(&y_true, &y_true);
 
         assert!((score1 - 0.57142857).abs() < 1e-8);
         assert!((score2 - 1.0).abs() < 1e-8);