ferricml 0.2.1

A lean, pure-Rust toolkit for classical machine learning
Documentation
//! Deterministic classification and regression metrics.

use std::error::Error;
use std::fmt;

mod averaging;
mod classification;
mod confusion;
mod ranking;
mod regression;

pub use averaging::{Average, Averaging, ZeroDivision};
pub use classification::{
    BinaryConfusionMatrix, accuracy_score, binary_confusion_matrix, brier_score, f1_score,
    log_loss, multiclass_brier_score, multiclass_log_loss, precision_score, recall_score,
    roc_auc_score,
};
pub use confusion::{ClassCounts, ConfusionMatrix};
pub use ranking::{
    PrecisionRecallCurve, RocCurve, average_precision_score, precision_recall_curve, roc_curve,
};
pub use regression::{
    explained_variance_score, mean_absolute_error, mean_absolute_percentage_error,
    mean_squared_error, median_absolute_error, r2_score, root_mean_squared_error,
};

/// Errors produced while evaluating predictions.
///
/// Inputs are numbered in call order: expected values are input zero and
/// predicted values, probabilities, or scores are input one.
#[derive(Clone, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum MetricError {
    /// Expected and predicted inputs have different lengths.
    LengthMismatch {
        /// Expected input length.
        expected: usize,
        /// Actual input length.
        actual: usize,
    },
    /// A metric received no observations.
    Empty,
    /// A binary metric received a label other than zero or one.
    InvalidBinaryTarget {
        /// Zero for expected labels, one for predicted labels.
        input: usize,
        /// Position of the invalid label.
        index: usize,
        /// Invalid label value.
        value: u8,
    },
    /// A numeric input contained NaN or infinity.
    NonFiniteValue {
        /// Zero for expected values, one for predicted values or scores.
        input: usize,
        /// Position of the invalid value.
        index: usize,
    },
    /// A probability was outside the closed interval from zero to one.
    InvalidProbability {
        /// Position of the invalid probability.
        index: usize,
    },
    /// A binary-only average was requested for a wider label set.
    NotBinary {
        /// Number of distinct observed labels.
        labels: usize,
    },
    /// An F-score beta was not finite and strictly positive.
    InvalidBeta,
    /// The metric denominator or required class distribution is undefined.
    Undefined,
    // New variants are appended rather than inserted: this enum is
    // `#[non_exhaustive]`, but shifting an existing variant's discriminant is
    // still a change `cargo-semver-checks` reports, and it buys nothing.
    /// A class list was empty or not strictly increasing.
    ///
    /// A probability matrix's columns are identified by position, so the class
    /// list has to be the sorted, deduplicated set a classifier reports. A
    /// repeated or out-of-order label would silently mislabel a column.
    InvalidClassSet,
    /// An expected label is absent from the supplied class list.
    UnknownClass {
        /// Position of the label.
        index: usize,
        /// The label that has no column.
        value: u8,
    },
}

impl fmt::Display for MetricError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::LengthMismatch { expected, actual } => {
                write!(f, "expected {expected} metric values, got {actual}")
            }
            Self::Empty => f.write_str("metric requires at least one observation"),
            Self::InvalidBinaryTarget {
                input,
                index,
                value,
            } => write!(
                f,
                "binary label in input {input} at index {index} is {value}, expected 0 or 1"
            ),
            Self::NonFiniteValue { input, index } => {
                write!(
                    f,
                    "metric value in input {input} at index {index} is not finite"
                )
            }
            Self::InvalidProbability { index } => {
                write!(f, "probability at index {index} must be in 0..=1")
            }
            Self::NotBinary { labels } => write!(
                f,
                "binary averaging requires labels 0 and 1, got {labels} distinct labels"
            ),
            Self::InvalidBeta => f.write_str("F-score beta must be finite and strictly positive"),
            Self::Undefined => f.write_str("metric is undefined for these observations"),
            Self::InvalidClassSet => {
                f.write_str("class list must be non-empty and strictly increasing")
            }
            Self::UnknownClass { index, value } => write!(
                f,
                "expected label at index {index} is {value}, which has no probability column"
            ),
        }
    }
}

impl Error for MetricError {}

fn validate_lengths(expected: usize, actual: usize) -> Result<(), MetricError> {
    if expected != actual {
        return Err(MetricError::LengthMismatch { expected, actual });
    }
    if expected == 0 {
        return Err(MetricError::Empty);
    }
    Ok(())
}

fn validate_binary(values: &[u8], input: usize) -> Result<(), MetricError> {
    if let Some((index, &value)) = values.iter().enumerate().find(|(_, value)| **value > 1) {
        return Err(MetricError::InvalidBinaryTarget {
            input,
            index,
            value,
        });
    }
    Ok(())
}

fn validate_finite(values: &[f32], input: usize) -> Result<(), MetricError> {
    if let Some(index) = values.iter().position(|value| !value.is_finite()) {
        return Err(MetricError::NonFiniteValue { input, index });
    }
    Ok(())
}

fn validate_probabilities(values: &[f32]) -> Result<(), MetricError> {
    validate_finite(values, 1)?;
    if let Some(index) = values.iter().position(|value| !(0.0..=1.0).contains(value)) {
        return Err(MetricError::InvalidProbability { index });
    }
    Ok(())
}