shrinkage 0.4.0

Composable regularized statistical models in Rust.
Documentation
//! Gaussian loss on a linear predictor.

use crate::error::{NumericalFailure, finite, invalid};
use crate::{Datafit, DiagonalHessianDatafit, DifferentiableDatafit, FitError, SmoothDatafit};

/// A Gaussian response with an optional unpenalized fitted intercept.
#[derive(Clone, Copy, Debug)]
pub struct Gaussian<'a> {
    pub(crate) response: &'a [f64],
    pub(crate) fit_intercept: bool,
}

impl<'a> Gaussian<'a> {
    /// Borrow a response, fitting an intercept by default.
    pub fn new(response: &'a [f64]) -> Self {
        Self {
            response,
            fit_intercept: true,
        }
    }

    /// Compose this family with a link for Fisher-scoring IRLS.
    pub fn with_link<L: crate::Link>(self, link: L) -> crate::LinkedDatafit<Self, L> {
        crate::LinkedDatafit::new(self, link)
    }

    /// Transform a mean with the default identity link.
    ///
    /// # Errors
    /// Reject means outside the link domain or nonfinite arithmetic.
    pub fn link(&self, mu: f64) -> Result<f64, FitError> {
        crate::Link::link(&crate::Identity, mu)
    }

    /// Transform a predictor to a mean with the default link.
    ///
    /// # Errors
    /// Reject nonfinite predictors or arithmetic.
    pub fn inverse_link(&self, eta: f64) -> Result<f64, FitError> {
        crate::Link::inverse_link(&crate::Identity, eta)
    }

    /// Enable or disable the unpenalized fitted intercept.
    ///
    /// Explicit column centering can still induce an original-scale intercept.
    pub fn fit_intercept(mut self, enabled: bool) -> Self {
        self.fit_intercept = enabled;
        self
    }
}

impl DiagonalHessianDatafit for Gaussian<'_> {
    fn hessian_diagonal(&self, predictor: &[f64], output: &mut [f64]) -> Result<(), FitError> {
        self.value(predictor)?;
        if output.len() != predictor.len() {
            return Err(invalid("predictor and Hessian lengths must match"));
        }
        output.fill(1.0 / predictor.len() as f64);
        Ok(())
    }
}

impl SmoothDatafit for Gaussian<'_> {
    fn gap_safe(&self) -> Option<&dyn crate::GapSafeDatafit> {
        Some(self)
    }
}

impl DifferentiableDatafit for Gaussian<'_> {
    fn n_obs(&self) -> usize {
        self.response.len()
    }

    fn fits_intercept(&self) -> bool {
        self.fit_intercept
    }

    fn gradient(&self, predictor: &[f64], output: &mut [f64]) -> Result<(), FitError> {
        self.validate(predictor.len())?;
        if output.len() != predictor.len() {
            return Err(invalid("predictor and gradient lengths must match"));
        }
        for ((&value, &target), derivative) in predictor.iter().zip(self.response).zip(output) {
            if !value.is_finite() {
                return Err(invalid("predictor values must be finite"));
            }
            *derivative = finite(
                (value - target) / predictor.len() as f64,
                "computing the predictor gradient",
                0,
            )?;
        }
        Ok(())
    }
}

impl crate::GapSafeDatafit for Gaussian<'_> {
    fn dual_candidate(&self, predictor: &[f64], output: &mut [f64]) -> Result<(), FitError> {
        self.gradient(predictor, output)?;
        for theta in output.iter_mut() {
            *theta = -*theta;
        }
        if self.fit_intercept {
            let mean = output
                .iter()
                .map(|theta| theta / output.len() as f64)
                .sum::<f64>();
            for theta in output.iter_mut() {
                *theta -= mean;
            }
            let last = output.len() - 1;
            output[last] = -output[..last].iter().sum::<f64>();
        }
        self.finalize_dual(output)
    }

    fn finalize_dual(&self, dual: &mut [f64]) -> Result<(), FitError> {
        self.validate(dual.len())?;
        if self.fit_intercept {
            crate::screening::intercept::balance(dual, None)?;
        }
        Ok(())
    }

    fn dual_objective(&self, dual: &[f64]) -> Result<f64, FitError> {
        self.validate(dual.len())?;
        if self.fit_intercept && dual.iter().sum::<f64>() != 0.0 {
            return Err(invalid(
                "Gaussian dual point violates the free-intercept equality",
            ));
        }
        let n = dual.len() as f64;
        let reference = if self.fit_intercept {
            self.response[0]
        } else {
            0.0
        };
        let mut value = 0.0;
        for (&y, &theta) in self.response.iter().zip(dual) {
            value += finite(
                ((y - reference) - 0.5 * n * theta) * theta,
                "evaluating the Gaussian dual",
                0,
            )?;
        }
        Ok(finite(value, "summing the Gaussian dual", 0)?)
    }

    fn strong_concavity(&self) -> f64 {
        self.response.len() as f64
    }

    fn fenchel_gap(&self, predictor: &[f64], dual: &[f64]) -> Result<f64, FitError> {
        self.validate(predictor.len())?;
        if dual.len() != predictor.len() {
            return Err(invalid("dual dimensions must match Gaussian observations"));
        }
        let n = predictor.len() as f64;
        let mut gap = 0.0;
        for ((&y, &eta), &theta) in self.response.iter().zip(predictor).zip(dual) {
            let difference = ((y - eta) / n.sqrt()) - n.sqrt() * theta;
            gap += 0.5 * difference * difference;
        }
        Ok(finite(gap, "computing the Gaussian Fenchel gap", 0)?)
    }
}

impl Gaussian<'_> {
    /// Borrow the observed response.
    pub fn response(&self) -> &[f64] {
        self.response
    }

    /// Whether fitting includes a free, unpenalized intercept.
    pub fn fits_intercept(&self) -> bool {
        self.fit_intercept
    }

    pub(crate) fn validate<E>(&self, nrows: usize) -> Result<(), FitError<E>> {
        if nrows == 0 {
            return Err(invalid("training data must have at least one observation"));
        }
        if self.response.len() != nrows {
            return Err(invalid(format!(
                "response length {} does not match {} training rows",
                self.response.len(),
                nrows
            )));
        }
        for (i, value) in self.response.iter().enumerate() {
            if !value.is_finite() {
                return Err(invalid(format!("response at row {i} is not finite")));
            }
        }
        Ok(())
    }

    pub(crate) fn residual_loss(
        residual: impl Iterator<Item = f64>,
        n: usize,
        iteration: usize,
    ) -> Result<f64, NumericalFailure> {
        let divisor = (n as f64).sqrt();
        let mut sum = 0.0;
        for residual in residual {
            let value = finite(residual, "reconstructing residuals", iteration)? / divisor;
            sum += 0.5 * value * value;
        }
        finite(sum, "computing the loss", iteration)
    }
}

impl Datafit for Gaussian<'_> {
    type Error = FitError;

    /// Evaluate `||response - predictor||² / (2n)`.
    fn value(&self, predictor: &[f64]) -> Result<f64, Self::Error> {
        self.validate(predictor.len())?;
        if predictor.iter().any(|value| !value.is_finite()) {
            return Err(invalid("predictor values must be finite"));
        }
        Ok(Self::residual_loss(
            self.response.iter().zip(predictor).map(|(y, eta)| y - eta),
            predictor.len(),
            0,
        )?)
    }
}

impl crate::QuadraticModelDatafit for Gaussian<'_> {
    fn working_curvature(&self, predictor: &[f64], output: &mut [f64]) -> Result<(), FitError> {
        self.hessian_diagonal(predictor, output)
    }
}