gbrt_rs/utils/

validation.rs

//! Data and parameter validation utilities for gradient boosting models.
//!
//! This module provides comprehensive validation functions for:
//! - Input data quality (finite values, dimensional consistency)
//! - Parameter constraints (ranges, positivity)
//! - Model hyperparameter validation
//!
//! # Design
//!
//! The module offers both **struct-based validators** with builder patterns for
//! complex validation scenarios and **standalone functions** for quick checks.
//! All validation functions return [`ValidationResult<T>`], providing detailed
//! error messages when validation fails.
//!
//! # Key Components
//!
//! - [`DataValidator`]: Validates data arrays, features, and targets
//! - [`ParameterValidator`]: Validates model parameters against constraints
//! - Standalone functions: Lightweight validation helpers for common checks
//!
//! # Error Handling
//!
//! Validation failures return [`ValidationError`] with specific variants describing
//! the exact nature of the validation failure, enabling precise error reporting.

use std::collections::HashMap;
use thiserror::Error;

/// Errors that can occur during validation.
///
/// Each variant provides detailed information about the specific validation
/// failure, including parameter names, expected constraints, and actual values.
#[derive(Error, Debug)]
pub enum ValidationError {
    /// General validation failure with a descriptive message.
    #[error("Validation failed: {0}")]
    ValidationFailed(String),
    
    /// Parameter value is outside the allowed range.
    #[error("Invalid parameter: {name} = {value} (expected: {constraint})")]
    InvalidParameter {
        /// Name of the parameter that failed validation.
        name: String,
        /// Actual value provided.
        value: f64,
        /// Expected constraint or range.
        constraint: String,
    },
    
    /// Array dimensions don't match expected values.
    #[error("Dimension mismatch: expected {expected}, got {actual}")]
    DimensionMismatch {
        /// Expected dimension or size.
        expected: String,
        /// Actual dimension or size found.
        actual: String,
    },
    
    /// Input data is empty.
    #[error("Empty data")]
    EmptyData,
    
    /// Non-finite value (NaN, Inf, -Inf) found in data.
    #[error("Non-finite value found")]
    NonFiniteValue,
    
    /// Probability value is outside [0, 1] range. 
    #[error("Invalid probability: {value} (must be in [0, 1])")]
    /// The invalid probability value.
    InvalidProbability { value: f64 },
}

/// Result type for validation operations.
pub type ValidationResult<T> = std::result::Result<T, ValidationError>;

/// Validator for input data integrity.
///
/// Provides methods to check data quality including finiteness, positivity,
/// dimensional consistency, and target value validity.
pub struct DataValidator;

impl DataValidator {
    /// Creates a new data validator.
    pub fn new() -> Self {
        Self
    }
    
    /// Checks that all values in a slice are finite (not NaN, Inf, or -Inf).
    ///
    /// # Arguments
    ///
    /// * `values` - Slice of values to check
    ///
    /// # Returns
    ///
    /// `Ok(())` if all values are finite, `Err(ValidationError::NonFiniteValue)` otherwise
    pub fn check_finite(&self, values: &[f64]) -> ValidationResult<()> {
        check_finite(values)
    }
    
    /// Checks that all values are positive (> 0.0).
    ///
    /// # Arguments
    ///
    /// * `values` - Slice of values to check
    ///
    /// # Returns
    ///
    /// `Ok(())` if all values are positive, `Err` otherwise 
    pub fn check_positive(&self, values: &[f64]) -> ValidationResult<()> {
        check_positive(values)
    }
    
    /// Checks that all values are valid probabilities (in [0, 1]).
    ///
    /// # Arguments
    ///
    /// * `values` - Slice of values to check
    ///
    /// # Returns
    ///
    /// `Ok(())` if all values are valid probabilities, `Err` otherwise 
    pub fn check_probability(&self, values: &[f64]) -> ValidationResult<()> {
        check_probability(values)
    }
    
    /// Validates feature matrix dimensions and optional feature names.
    ///
    /// # Arguments
    ///
    /// * `n_samples` - Number of samples (must be > 0)
    /// * `n_features` - Number of features (must be > 0)
    /// * `feature_names` - Optional slice of feature names (length must match n_features)
    ///
    /// # Returns
    ///
    /// `Ok(())` if dimensions are valid, `Err` otherwise 
    pub fn validate_features(
        &self, 
        n_samples: usize, 
        n_features: usize,
        feature_names: Option<&[String]>
    ) -> ValidationResult<()> {
        validate_features(n_samples, n_features, feature_names)
    }
    
    /// Validates target values for regression or classification.
    ///
    /// # Arguments
    ///
    /// * `targets` - Target values to validate
    /// * `is_classification` - Whether this is a classification problem
    ///
    /// # Returns
    ///
    /// `Ok(())` if targets are valid, `Err` otherwise
    ///
    /// # Behavior
    ///
    /// - For classification: targets must be 0.0 or 1.0
    /// - For regression: targets must be finite (no other constraints) 
    pub fn validate_targets(&self, targets: &[f64], is_classification: bool) -> ValidationResult<()> {
        validate_targets(targets, is_classification)
    }
    
    /// Asserts that two slices have the same length.
    ///
    /// # Arguments
    ///
    /// * `a` - First slice
    /// * `b` - Second slice
    ///
    /// # Returns
    ///
    /// `Ok(())` if lengths match, `Err(ValidationError::DimensionMismatch)` otherwise 
    pub fn assert_same_length(&self, a: &[f64], b: &[f64]) -> ValidationResult<()> {
        assert_same_length(a, b)
    }
    
    /// Asserts that a slice is not empty.
    ///
    /// # Arguments
    ///
    /// * `values` - Slice to check
    ///
    /// # Returns
    ///
    /// `Ok(())` if non-empty, `Err(ValidationError::EmptyData)` otherwise
    pub fn assert_non_empty(&self, values: &[f64]) -> ValidationResult<()> {
        assert_non_empty(values)
    }
}

impl Default for DataValidator {
    fn default() -> Self {
        Self::new()
    }
}

/// Validator for model parameters with configurable constraints.
///
/// Maintains a map of parameter names to allowed (min, max) ranges,
/// enabling reusable validation logic for hyperparameters.
pub struct ParameterValidator {
    /// Map of parameter name to (min, max) constraint.
    constraints: HashMap<String, (f64, f64)>, // (min, max) for each parameter
}

impl ParameterValidator {
    /// Creates a new parameter validator with no constraints.
    pub fn new() -> Self {
        Self {
            constraints: HashMap::new(),
        }
    }
    
    /// Adds a parameter range constraint (builder pattern).
    ///
    /// # Arguments
    ///
    /// * `name` - Parameter name
    /// * `min` - Minimum allowed value (inclusive)
    /// * `max` - Maximum allowed value (inclusive)
    ///
    /// # Returns
    ///
    /// Self with the new constraint added
    pub fn add_constraint(mut self, name: &str, min: f64, max: f64) -> Self {
        self.constraints.insert(name.to_string(), (min, max));
        self
    }
    
    /// Validates a single parameter against its constraints.
    ///
    /// # Arguments
    ///
    /// * `name` - Parameter name
    /// * `value` - Parameter value to validate
    ///
    /// # Returns
    ///
    /// `Ok(())` if valid or no constraint exists, `Err` if out of range 
    pub fn validate_parameter(&self, name: &str, value: f64) -> ValidationResult<()> {
        if let Some(&(min, max)) = self.constraints.get(name) {
            if value < min || value > max {
                return Err(ValidationError::InvalidParameter {
                    name: name.to_string(),
                    value,
                    constraint: format!("[{}, {}]", min, max),
                });
            }
        }
        Ok(())
    }
    
    /// Validates multiple parameters against all registered constraints.
    ///
    /// # Arguments
    ///
    /// * `params` - HashMap of parameter name → value
    ///
    /// # Returns
    ///
    /// `Ok(())` if all parameters satisfy constraints, `Err` otherwise 
    pub fn validate_parameters(&self, params: &HashMap<String, f64>) -> ValidationResult<()> {
        for (name, &value) in params {
            self.validate_parameter(name, value)?;
        }
        Ok(())
    }
    
    /// Validates common gradient boosting hyperparameters.
    ///
    /// Checks all parameters against sensible ranges for a typical GBM model.
    ///
    /// # Arguments
    ///
    /// * `n_estimators` - Number of trees (must be > 0)
    /// * `learning_rate` - Step size (must be in (0, 1])
    /// * `max_depth` - Tree depth (must be > 0)
    /// * `subsample` - Subsampling rate (must be in [0, 1])
    ///
    /// # Returns
    ///
    /// `Ok(())` if all parameters are valid 
    pub fn validate_model_params(
        &self,
        n_estimators: usize,
        learning_rate: f64,
        max_depth: usize,
        subsample: f64,
    ) -> ValidationResult<()> {
        let mut params = HashMap::new();
        params.insert("n_estimators".to_string(), n_estimators as f64);
        params.insert("learning_rate".to_string(), learning_rate);
        params.insert("max_depth".to_string(), max_depth as f64);
        params.insert("subsample".to_string(), subsample);
        
        let validator = ParameterValidator::new()
            .add_constraint("n_estimators", 1.0, 10000.0)
            .add_constraint("learning_rate", 1e-10, 1.0)
            .add_constraint("max_depth", 1.0, 100.0)
            .add_constraint("subsample", 0.0, 1.0);
        
        validator.validate_parameters(&params)
    }
}

impl Default for ParameterValidator {
    fn default() -> Self {
        Self::new()
    }
}

// Standalone validation functions

/// Checks that all values in a slice are finite (not NaN, Inf, or -Inf).
///
/// # Arguments
///
/// * `values` - Slice to check
///
/// # Returns
///
/// `Ok(())` if all values are finite
pub fn check_finite(values: &[f64]) -> ValidationResult<()> {
    if values.iter().any(|&x| !x.is_finite()) {
        return Err(ValidationError::NonFiniteValue);
    }
    Ok(())
}

/// Checks that all values are positive (> 0.0).
///
/// # Arguments
///
/// * `values` - Slice to check
///
/// # Returns
///
/// `Ok(())` if all values are positive
pub fn check_positive(values: &[f64]) -> ValidationResult<()> {
    if values.iter().any(|&x| x <= 0.0) {
        return Err(ValidationError::ValidationFailed(
            "All values must be positive".to_string()
        ));
    }
    Ok(())
}

/// Checks that all values are valid probabilities (in [0, 1]).
///
/// # Arguments
///
/// * `values` - Slice to check
///
/// # Returns
///
/// `Ok(())` if all values are probabilities
pub fn check_probability(values: &[f64]) -> ValidationResult<()> {
    for &value in values {
        if value < 0.0 || value > 1.0 {
            return Err(ValidationError::InvalidProbability { value });
        }
    }
    Ok(())
}

/// Validates feature matrix dimensions and optional feature names.
///
/// # Arguments
///
/// * `n_samples` - Number of samples (must be > 0)
/// * `n_features` - Number of features (must be > 0)
/// * `feature_names` - Optional feature names (length must match n_features if provided)
///
/// # Returns
///
/// `Ok(())` if dimensions are valid
pub fn validate_features(
    n_samples: usize, 
    n_features: usize,
    feature_names: Option<&[String]>
) -> ValidationResult<()> {
    if n_samples == 0 {
        return Err(ValidationError::EmptyData);
    }
    
    if n_features == 0 {
        return Err(ValidationError::ValidationFailed(
            "Number of features must be positive".to_string()
        ));
    }
    
    if let Some(names) = feature_names {
        if names.len() != n_features {
            return Err(ValidationError::DimensionMismatch {
                expected: n_features.to_string(),
                actual: names.len().to_string(),
            });
        }
    }
    
    Ok(())
}

/// Validates target values for regression or classification.
///
/// For classification, ensures targets are binary (0 or 1). For regression,
/// ensures all values are finite.
///
/// # Arguments
///
/// * `targets` - Target values
/// * `is_classification` - Whether this is a classification problem
///
/// # Returns
///
/// `Ok(())` if targets are valid
pub fn validate_targets(targets: &[f64], is_classification: bool) -> ValidationResult<()> {
    if targets.is_empty() {
        return Err(ValidationError::EmptyData);
    }
    
    check_finite(targets)?;
    
    if is_classification {
        // For classification, targets should be 0 or 1
        for &target in targets {
            if target != 0.0 && target != 1.0 {
                return Err(ValidationError::ValidationFailed(
                    format!("Classification targets must be 0 or 1, got {}", target)
                ));
            }
        }
    }
    
    Ok(())
}

/// Asserts that two slices have the same length.
///
/// # Arguments
///
/// * `a` - First slice
/// * `b` - Second slice
///
/// # Returns
///
/// `Ok(())` if lengths match
pub fn assert_same_length(a: &[f64], b: &[f64]) -> ValidationResult<()> {
    if a.len() != b.len() {
        return Err(ValidationError::DimensionMismatch {
            expected: a.len().to_string(),
            actual: b.len().to_string(),
        });
    }
    Ok(())
}

/// Asserts that a slice is not empty.
///
/// # Arguments
///
/// * `values` - Slice to check
///
/// # Returns
///
/// `Ok(())` if non-empty
pub fn assert_non_empty(values: &[f64]) -> ValidationResult<()> {
    if values.is_empty() {
        return Err(ValidationError::EmptyData);
    }
    Ok(())
}

/// Validates that a value falls within a specified range.
///
/// # Arguments
///
/// * `value` - Value to check
/// * `min` - Minimum allowed (inclusive)
/// * `max` - Maximum allowed (inclusive)
/// * `name` - Name for error messages
///
/// # Returns
///
/// `Ok(())` if value is in range
pub fn validate_range(value: f64, min: f64, max: f64, name: &str) -> ValidationResult<()> {
    if value < min || value > max {
        return Err(ValidationError::InvalidParameter {
            name: name.to_string(),
            value,
            constraint: format!("[{}, {}]", min, max),
        });
    }
    Ok(())
}

/// Validates that a value is positive (> 0).
///
/// # Arguments
///
/// * `value` - Value to check
/// * `name` - Name for error messages
///
/// # Returns
///
/// `Ok(())` if value is positive
pub fn validate_positive(value: f64, name: &str) -> ValidationResult<()> {
    if value <= 0.0 {
        return Err(ValidationError::InvalidParameter {
            name: name.to_string(),
            value,
            constraint: "> 0".to_string(),
        });
    }
    Ok(())
}

/// Validates that a value is non-negative (≥ 0).
///
/// # Arguments
///
/// * `value` - Value to check
/// * `name` - Name for error messages
///
/// # Returns
///
/// `Ok(())` if value is non-negative
pub fn validate_non_negative(value: f64, name: &str) -> ValidationResult<()> {
    if value < 0.0 {
        return Err(ValidationError::InvalidParameter {
            name: name.to_string(),
            value,
            constraint: ">= 0".to_string(),
        });
    }
    Ok(())
}

/// Validates common gradient boosting model hyperparameters.
///
/// Checks all parameters against sensible ranges for typical GBM models.
///
/// # Arguments
///
/// * `n_estimators` - Number of trees
/// * `learning_rate` - Step size
/// * `max_depth` - Maximum tree depth
/// * `subsample` - Subsampling rate
///
/// # Returns
///
/// `Ok(())` if all parameters are valid
pub fn validate_model_params(
    n_estimators: usize,
    learning_rate: f64,
    max_depth: usize,
    subsample: f64,
) -> ValidationResult<()> {
    if n_estimators == 0 {
        return Err(ValidationError::ValidationFailed(
            "n_estimators must be positive".to_string()
        ));
    }
    
    validate_range(learning_rate, 1e-10, 1.0, "learning_rate")?;
    
    if max_depth == 0 {
        return Err(ValidationError::ValidationFailed(
            "max_depth must be positive".to_string()
        ));
    }
    
    validate_range(subsample, 0.0, 1.0, "subsample")?;
    
    Ok(())
}