gbrt_rs/objective/

mod.rs

//! Objective functions for gradient boosting.
//!
//! This module defines the core trait and infrastructure for objective functions (loss functions)
//! used in gradient boosting. Objective functions compute the loss and its derivatives (gradient
//! and Hessian) which guide the boosting process.
//!
//! # Module Organization
//!
//! - [`regression`]: Regression objectives (MSE, MAE, Huber)
//! - [`binary_classification`]: Binary classification objectives (Log Loss)
//! - [`factory`]: Factory functions for creating objective instances
//!
//! # Key Components
//!
//! - [`Objective`]: Core trait that all objective functions must implement
//! - [`ObjectiveConfig`]: Configuration for objective functions with builder pattern
//! - [`ObjectiveError`]: Error type for objective-related failures

mod regression;
mod binary_classification;
mod factory;

// Re-export commonly used objective types.
pub use regression::{RegressionObjective, MSEObjective, MAEObjective, HuberObjective};
pub use binary_classification::{BinaryClassificationObjective, LogLossObjective};
pub use factory::{ObjectiveFactory, create_objective, ObjectiveType};

use crate::data::FeatureMatrix;
use thiserror::Error;
use serde::{Deserialize, Serialize};

/// Errors that can occur during objective function operations.
///
/// This error type covers all failure modes when working with objective functions,
/// including invalid input data, computation failures, configuration issues,
/// and serialization problems.
#[derive(Error, Debug)]
pub enum ObjectiveError {
    /// Input data is invalid for the objective function.
    ///
    /// This includes mismatched array lengths, non-finite values,
    /// or target values outside the valid range (e.g., non-binary targets for classification).
    #[error("Invalid input data: {0}")]
    InvalidInput(String),
    
    /// An error occurred during loss/gradient computation.
    ///
    /// This typically indicates numerical instability or overflow/underflow issues.
    #[error("Objective computation error: {0}")]
    ComputationError(String),
    
    /// Objective configuration is invalid or missing required parameters.
    #[error("Configuration error: {0}")]
    ConfigError(String),
   
    /// Serialization or deserialization of objective configuration failed.
    #[error("Serialization error: {0}")]
    SerializationError(String),
}

/// Result type for objective function operations.
///
/// This is a convenience type alias for `Result<T, ObjectiveError>`.
pub type ObjectiveResult<T> = std::result::Result<T, ObjectiveError>;

/// Core trait for objective functions in gradient boosting.
///
/// Objective functions (also called loss functions) measure how well the model's predictions
/// match the true target values. They provide the gradient and Hessian (second derivative)
/// that guide the boosting algorithm in fitting subsequent trees.
///
/// # Implementation Requirements
///
/// All objective functions must implement the required methods. The [`gradient_hessian`](Objective::gradient_hessian)
/// method has a default implementation that calls [`gradient`](Objective::gradient) and [`hessian`](Objective::hessian)
/// separately, but can be overridden for more efficient combined computation.
///
/// # Mathematical Background
///
/// - **Gradient**: First derivative of the loss with respect to predictions, ∇L(y, ŷ)
/// - **Hessian**: Second derivative of the loss, ∇²L(y, ŷ)
/// - These are used to approximate the loss function via second-order Taylor expansion
pub trait Objective: Send + Sync + std::fmt::Debug {
    /// Computes the loss value for given predictions and targets.
    ///
    /// # Arguments
    ///
    /// * `y_true` - Slice of true target values
    /// * `y_pred` - Slice of predicted values (in the transformed space if applicable)
    ///
    /// # Returns
    ///
    /// The average loss value across all samples
    ///
    /// # Errors
    ///
    /// Returns [`ObjectiveError::InvalidInput`] if inputs have mismatched lengths or contain invalid values
    /// Returns [`ObjectiveError::ComputationError`] if numerical computation fails.
    fn loss(&self, y_true: &[f64], y_pred: &[f64]) -> ObjectiveResult<f64>;
    
    /// Computes the gradient of the loss with respect to predictions.
    ///
    /// The gradient indicates how predictions should be adjusted to reduce loss.
    ///
    /// # Arguments
    ///
    /// * `y_true` - Slice of true target values
    /// * `y_pred` - Slice of predicted values
    ///
    /// # Returns
    ///
    /// A vector of gradient values, one per sample
    ///
    /// # Errors
    ///
    /// Returns [`ObjectiveError::InvalidInput`] if inputs have mismatched lengths
    /// Returns [`ObjectiveError::ComputationError`] if gradient computation fails 
    fn gradient(&self, y_true: &[f64], y_pred: &[f64]) -> ObjectiveResult<Vec<f64>>;
    
    /// Computes the Hessian (second derivative) of the loss.
    ///
    /// The Hessian represents the curvature of the loss function and is used
    /// to weight the importance of different samples in tree splitting.
    ///
    /// # Arguments
    ///
    /// * `y_true` - Slice of true target values
    /// * `y_pred` - Slice of predicted values
    ///
    /// # Returns
    ///
    /// A vector of Hessian values, one per sample
    ///
    /// # Errors
    ///
    /// Returns [`ObjectiveError::InvalidInput`] if inputs have mismatched lengths
    /// Returns [`ObjectiveError::ComputationError`] if Hessian computation fails 
    fn hessian(&self, y_true: &[f64], y_pred: &[f64]) -> ObjectiveResult<Vec<f64>>;
    
    /// Computes both gradient and Hessian in one pass for efficiency.
    ///
    /// This method has a default implementation that calls [`gradient`](Objective::gradient)
    /// and [`hessian`](Objective::hessian) separately. Implementations should override
    /// this for better performance when both can be computed simultaneously.
    ///
    /// # Arguments
    ///
    /// * `y_true` - Slice of true target values
    /// * `y_pred` - Slice of predicted values
    ///
    /// # Returns
    ///
    /// A tuple of (gradient_values, hessian_values)
    ///
    /// # Errors
    ///
    /// See [`gradient`](Objective::gradient) and [`hessian`](Objective::hessian) 
    fn gradient_hessian(&self, y_true: &[f64], y_pred: &[f64]) -> ObjectiveResult<(Vec<f64>, Vec<f64>)> {
        let gradient = self.gradient(y_true, y_pred)?;
        let hessian = self.hessian(y_true, y_pred)?;
        Ok((gradient, hessian))
    }
    
    /// Transforms raw predictions to the target space.
    ///
    /// For example, logistic loss applies a sigmoid transformation to produce
    /// probabilities for binary classification.
    ///
    /// # Arguments
    ///
    /// * `y_pred` - Slice of raw prediction values
    ///
    /// # Returns
    ///
    /// Transformed predictions (e.g., probabilities for classification) 
    fn transform(&self, y_pred: &[f64]) -> Vec<f64>;
    
    /// Returns the name of the objective function.
    ///
    /// This is used for logging, serialization, and configuration matching.
    ///
    /// # Returns
    ///
    /// A string slice identifying the objective (e.g., "mse", "logloss") 
    fn name(&self) -> &str;
    
    /// Checks if this objective is for regression tasks.
    ///
    /// # Returns
    ///
    /// `true` if the objective is for regression (e.g., MSE, MAE) 
    fn is_regression(&self) -> bool;
    
    /// Checks if this objective is for classification tasks.
    ///
    /// # Returns
    ///
    /// `true` if the objective is for classification (e.g., Log Loss) 
    fn is_classification(&self) -> bool;
    
    /// Computes the default initial prediction for this objective.
    ///
    /// The initial prediction is used as the starting point for boosting.
    /// For regression, this is often the mean of targets. For classification,
    /// it's typically the logit of the class proportion.
    ///
    /// # Arguments
    ///
    /// * `y_true` - Slice of true target values
    ///
    /// # Returns
    ///
    /// The initial prediction value
    ///
    /// # Errors
    ///
    /// Returns [`ObjectiveError::InvalidInput`] if `y_true` is empty or invalid 
    fn initial_prediction(&self, y_true: &[f64]) -> ObjectiveResult<f64>;
    
    /// Validates that target values are appropriate for this objective.
    ///
    /// This checks for common issues like non-finite values, out-of-range targets,
    /// or invalid class labels.
    ///
    /// # Arguments
    ///
    /// * `y_true` - Slice of true target values to validate
    ///
    /// # Returns
    ///
    /// `Ok(())` if validation passes
    ///
    /// # Errors
    ///
    /// Returns [`ObjectiveError::InvalidInput`] if validation fails 
    fn validate_targets(&self, y_true: &[f64]) -> ObjectiveResult<()>;
}

/// Configuration for objective functions.
///
/// This struct provides a flexible way to configure objective functions with
/// a name and optional parameters. It supports serialization/deserialization
/// for model persistence and uses a builder pattern for ergonomic configuration.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ObjectiveConfig {
    /// The name of the objective function (e.g., "mse", "huber", "logloss")
    pub name: String,
    /// Optional parameters for the objective (e.g., "delta" for Huber loss)
    pub params: std::collections::HashMap<String, f64>,
}

impl Default for ObjectiveConfig {
    /// Returns the default configuration using Mean Squared Error (MSE).
    fn default() -> Self {
        Self {
            name: "mse".to_string(),
            params: std::collections::HashMap::new(),
        }
    }
}

impl ObjectiveConfig {
    /// Creates a new objective configuration with the given name and no parameters.
    ///
    /// # Arguments
    ///
    /// * `name` - The name of the objective function
    ///
    /// # Returns
    ///
    /// A new `ObjectiveConfig` instance
    pub fn new(name: &str) -> Self {
        Self {
            name: name.to_string(),
            params: std::collections::HashMap::new(),
        }
    }
    
    /// Adds a parameter to the configuration (builder pattern).
    ///
    /// This method consumes `self` and returns a modified configuration,
    /// enabling method chaining for ergonomic configuration.
    ///
    /// # Arguments
    ///
    /// * `key` - Parameter name
    /// * `value` - Parameter value
    ///
    /// # Returns
    ///
    /// Self with the parameter added
    pub fn with_param(mut self, key: &str, value: f64) -> Self {
        self.params.insert(key.to_string(), value);
        self
    }

    /// Retrieves a parameter value by key.
    ///
    /// # Arguments
    ///
    /// * `key` - Parameter name to look up
    ///
    /// # Returns
    ///
    /// `Some(f64)` if the parameter exists, `None` otherwise
    pub fn get_param(&self, key: &str) -> Option<f64> {
        self.params.get(key).copied()
    }
}