ferricml 0.2.1

A lean, pure-Rust toolkit for classical machine learning
Documentation
use super::selection::validate_selection;
use super::{DataError, SelectionError};

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

/// An owned, non-empty vector of binary classification targets.
///
/// Every target is guaranteed to be either `0` or `1`.
///
/// ```
/// use ferricml::data::BinaryTargets;
///
/// let targets = BinaryTargets::new(vec![0, 1, 1, 0])?;
///
/// assert_eq!(targets.len(), 4);
/// assert_eq!(targets.as_slice(), &[0, 1, 1, 0]);
/// // Selecting a subset keeps the type's guarantees, which is what makes it
/// // safe to hand a cross-validation fold straight back to a fit.
/// assert_eq!(targets.select(&[1, 2])?.as_slice(), &[1, 1]);
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
///
/// A label outside `{0, 1}` is rejected at construction, with its index and its
/// value, rather than being clamped or reinterpreted:
///
/// ```
/// use ferricml::data::{BinaryTargets, DataError};
///
/// assert_eq!(
///     BinaryTargets::new(vec![0, 1, 2]),
///     Err(DataError::InvalidBinaryTarget { index: 2, value: 2 }),
/// );
/// ```
///
/// For more than two classes use [`ClassTargets`], which additionally records
/// the observed class set that orders every probability column.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct BinaryTargets {
    values: Vec<u8>,
}

impl BinaryTargets {
    /// Validates and stores binary targets.
    pub fn new(values: Vec<u8>) -> Result<Self, DataError> {
        if values.is_empty() {
            return Err(DataError::EmptyTargets);
        }
        if let Some((index, &value)) = values.iter().enumerate().find(|(_, value)| **value > 1) {
            return Err(DataError::InvalidBinaryTarget { index, value });
        }
        Ok(Self { values })
    }

    /// Returns the number of targets.
    #[inline]
    pub fn len(&self) -> usize {
        self.values.len()
    }

    /// Returns whether this vector is empty.
    ///
    /// Valid instances are never empty; this method is provided for standard
    /// collection-style interfaces.
    #[inline]
    pub fn is_empty(&self) -> bool {
        self.values.is_empty()
    }

    /// Returns the validated target values.
    #[inline]
    pub fn as_slice(&self) -> &[u8] {
        &self.values
    }

    /// Returns a target, or `None` if `index` is out of bounds.
    #[inline]
    pub fn get(&self, index: usize) -> Option<u8> {
        self.values.get(index).copied()
    }

    /// Consumes the targets and returns their allocation.
    #[inline]
    pub fn into_values(self) -> Vec<u8> {
        self.values
    }

    /// Copies selected targets in the requested order.
    pub fn select(&self, indices: &[usize]) -> Result<Self, SelectionError> {
        validate_selection(indices, self.values.len())?;
        Ok(Self {
            values: indices.iter().map(|&index| self.values[index]).collect(),
        })
    }
}

/// An owned, non-empty vector of general classification targets.
///
/// Every `u8` is a valid class label, so construction only rejects an empty
/// vector. What this type adds over a bare `Vec<u8>` is the *observed class
/// set*: the sorted, deduplicated labels actually present, computed once at
/// construction and carried alongside the values.
///
/// That set is the column order of every probability matrix produced from these
/// targets. It is deliberately not assumed contiguous and not assumed
/// zero-based — labels `{7, 3, 10}` give classes `[3, 7, 10]`, and column `j`
/// is the probability of `classes()[j]`. There is no notion of a "missing"
/// class between two observed labels, so a caller never has to renumber its
/// labels to fit a dense range.
///
/// ```
/// use ferricml::data::ClassTargets;
///
/// let targets = ClassTargets::new(vec![7, 3, 10, 3])?;
/// assert_eq!(targets.classes(), &[3, 7, 10]);
/// assert_eq!(targets.n_classes(), 3);
/// assert_eq!(targets.class_index(10), Some(2));
/// assert_eq!(targets.class_index(0), None);
/// # Ok::<(), ferricml::data::DataError>(())
/// ```
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct ClassTargets {
    values: Vec<u8>,
    classes: Vec<u8>,
}

impl ClassTargets {
    /// Validates targets and records their sorted observed class set.
    pub fn new(values: Vec<u8>) -> Result<Self, DataError> {
        if values.is_empty() {
            return Err(DataError::EmptyTargets);
        }
        let classes = observed_classes(&values);
        Ok(Self { values, classes })
    }

    /// Returns the number of targets.
    #[inline]
    pub fn len(&self) -> usize {
        self.values.len()
    }

    /// Returns whether this vector is empty.
    ///
    /// Valid instances are never empty; this method is provided for standard
    /// collection-style interfaces.
    #[inline]
    pub fn is_empty(&self) -> bool {
        self.values.is_empty()
    }

    /// Returns the target values.
    #[inline]
    pub fn as_slice(&self) -> &[u8] {
        &self.values
    }

    /// Returns a target, or `None` if `index` is out of bounds.
    #[inline]
    pub fn get(&self, index: usize) -> Option<u8> {
        self.values.get(index).copied()
    }

    /// Returns the sorted, deduplicated labels observed in these targets.
    ///
    /// This is the probability column order for any classifier fitted on them.
    #[inline]
    pub fn classes(&self) -> &[u8] {
        &self.classes
    }

    /// Returns the number of distinct observed labels.
    ///
    /// Always at least one, because valid targets are never empty.
    #[inline]
    pub fn n_classes(&self) -> usize {
        self.classes.len()
    }

    /// Returns the column index of `label`, or `None` when it was not observed.
    #[inline]
    pub fn class_index(&self, label: u8) -> Option<usize> {
        self.classes.binary_search(&label).ok()
    }

    /// Consumes the targets and returns their allocation.
    #[inline]
    pub fn into_values(self) -> Vec<u8> {
        self.values
    }

    /// Copies selected targets in the requested order.
    ///
    /// The observed class set is recomputed from the selection, so a fold that
    /// happens to contain fewer labels than the whole vector reports exactly
    /// the labels it contains.
    pub fn select(&self, indices: &[usize]) -> Result<Self, SelectionError> {
        validate_selection(indices, self.values.len())?;
        let values = indices
            .iter()
            .map(|&index| self.values[index])
            .collect::<Vec<_>>();
        let classes = observed_classes(&values);
        Ok(Self { values, classes })
    }
}

impl From<BinaryTargets> for ClassTargets {
    /// Widens validated binary targets without revalidating them.
    ///
    /// The observed class set of `[0, 0]` is `[0]`, not `[0, 1]`: it records
    /// what was seen, never what was permitted.
    fn from(targets: BinaryTargets) -> Self {
        let values = targets.into_values();
        let classes = observed_classes(&values);
        Self { values, classes }
    }
}

/// A validated classification target vector, as its consumers need it.
///
/// Anything that folds, resamples, or re-scores classification targets needs
/// exactly two things from them: the labels to score against, and a subset copy
/// that still carries the container's construction-time guarantees. Both
/// [`BinaryTargets`] and [`ClassTargets`] already provide those inherently, so
/// this trait names the requirement rather than adding one, and one entry point
/// per consumer serves both vocabularies.
///
/// # Why this is a type parameter and not a second entry point
///
/// Label arity is a property of the **metric**, not of the loop.
/// [`ClassificationScore::output_kind`](crate::model_selection::ClassificationScore::output_kind)
/// already says whether a score reads labels, a positive-probability column, or
/// a whole probability matrix, and the matrix form works for any observed class
/// set. So the scoring layer was already arity-agnostic while cross-validation,
/// search, and permutation importance were each split by arity — a split that
/// would have doubled again every time the capability question was answered as
/// well. Making the target vocabulary a parameter keeps the two axes composing
/// instead of multiplying: the arity lives in `T`, the "does this model produce
/// probabilities?" question lives in the
/// [`ScorableClassifier`](crate::model_selection::ScorableClassifier) value, and
/// a third shape of either adds an implementation rather than an entry point.
///
/// # Why it lives here
///
/// This is vocabulary about target *types*, and `data` owns those. It was
/// written beside its first consumer in `model_selection`, which was defensible
/// while there was exactly one; `inspection` is the second, and two independent
/// consumers make it crate-wide vocabulary rather than one module's machinery.
/// It has no single public path in a consumer that would not read as an accident
/// of which module happened to need it first.
///
/// # Sealed
///
/// FerricML implements this for its own validated target containers and nothing
/// else. An implementation outside the crate could not uphold what a fold loop
/// relies on — that `select` preserves the container's construction-time
/// guarantees — and a target shape that model selection should serve is a new
/// container here, which arrives with its implementation.
pub trait ClassificationTargets: sealed::Sealed + Sized {
    /// The validated labels, one per row, in row order.
    fn as_slice(&self) -> &[u8];

    /// Copies the selected targets, preserving this type's own guarantees.
    ///
    /// This is the container's inherent `select`, named here so a fold loop can
    /// hand a training fold straight back to a fitting closure that takes the
    /// same type.
    fn select(&self, indices: &[usize]) -> Result<Self, SelectionError>;
}

impl ClassificationTargets for BinaryTargets {
    fn as_slice(&self) -> &[u8] {
        Self::as_slice(self)
    }

    fn select(&self, indices: &[usize]) -> Result<Self, SelectionError> {
        Self::select(self, indices)
    }
}

impl ClassificationTargets for ClassTargets {
    fn as_slice(&self) -> &[u8] {
        Self::as_slice(self)
    }

    fn select(&self, indices: &[usize]) -> Result<Self, SelectionError> {
        Self::select(self, indices)
    }
}

mod sealed {
    pub trait Sealed {}

    impl Sealed for super::BinaryTargets {}
    impl Sealed for super::ClassTargets {}
}

/// Sorted, deduplicated labels, in one pass plus a fixed 256-entry scan.
///
/// The fixed scan is what makes the result independent of the input order, and
/// therefore of anything a caller happens to do upstream.
fn observed_classes(values: &[u8]) -> Vec<u8> {
    let mut observed = [false; 256];
    for &value in values {
        observed[value as usize] = true;
    }
    (0..=u8::MAX)
        .filter(|&label| observed[label as usize])
        .collect()
}

/// An owned, non-empty vector of finite regression targets.
///
/// ```
/// use ferricml::data::RegressionTargets;
///
/// let targets = RegressionTargets::new(vec![0.0, 1.0, 4.0, 9.0])?;
///
/// assert_eq!(targets.len(), 4);
/// assert_eq!(targets.get(2), Some(4.0));
/// assert_eq!(targets.select(&[0, 3])?.as_slice(), &[0.0, 9.0]);
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
///
/// Non-finite targets are refused at construction, so no estimator has to
/// decide what fitting against a `NaN` would mean:
///
/// ```
/// use ferricml::data::{DataError, RegressionTargets};
///
/// assert_eq!(
///     RegressionTargets::new(vec![1.0, f32::INFINITY]),
///     Err(DataError::NonFiniteValue { index: 1 }),
/// );
/// ```
#[derive(Clone, Debug, PartialEq)]
pub struct RegressionTargets {
    values: Vec<f32>,
}

impl RegressionTargets {
    /// Validates and stores regression targets.
    pub fn new(values: Vec<f32>) -> Result<Self, DataError> {
        if values.is_empty() {
            return Err(DataError::EmptyTargets);
        }
        validate_finite(&values)?;
        Ok(Self { values })
    }

    /// Returns the number of targets.
    #[inline]
    pub fn len(&self) -> usize {
        self.values.len()
    }

    /// Returns whether this vector is empty.
    ///
    /// Valid instances are never empty; this method is provided for standard
    /// collection-style interfaces.
    #[inline]
    pub fn is_empty(&self) -> bool {
        self.values.is_empty()
    }

    /// Returns the finite target values.
    #[inline]
    pub fn as_slice(&self) -> &[f32] {
        &self.values
    }

    /// Returns a target, or `None` if `index` is out of bounds.
    #[inline]
    pub fn get(&self, index: usize) -> Option<f32> {
        self.values.get(index).copied()
    }

    /// Consumes the targets and returns their allocation.
    #[inline]
    pub fn into_values(self) -> Vec<f32> {
        self.values
    }

    /// Copies selected targets in the requested order.
    pub fn select(&self, indices: &[usize]) -> Result<Self, SelectionError> {
        validate_selection(indices, self.values.len())?;
        Ok(Self {
            values: indices.iter().map(|&index| self.values[index]).collect(),
        })
    }
}