shrinkage 0.4.0

Composable regularized statistical models in Rust.
Documentation
//! Penalty values, complete proximal maps, and coefficient subproblems.

mod axis;
mod chain_fused_lasso;
mod clustered_lasso;
mod coordinate;
mod group_lasso;
mod groups;
mod masked;
mod scaled;
mod slope;
pub use axis::{AxisPenalty, PenaltyAxis};
pub use chain_fused_lasso::ChainFusedLasso;
pub use clustered_lasso::ClusteredLasso;
pub use coordinate::CoordinatePenalty;
pub use group_lasso::GroupLasso;
pub use groups::{DisjointGroups, UncoveredPolicy};
pub use masked::{Masked, RestrictedProximalPenalty};
pub use scaled::Scaled;
pub use slope::Slope;

use crate::FitError;
use crate::error::{finite, invalid};

/// An L1 penalty on optimization-scale coefficients.
#[derive(Clone, Copy, Debug)]
pub struct L1 {
    pub(crate) lambda: f64,
}

impl L1 {
    /// Set the penalty strength, checked when fitting.
    pub fn new(lambda: f64) -> Self {
        Self { lambda }
    }
}

/// The complete penalty `R(beta)` on optimization-scale coefficients.
///
/// A value alone does not imply a proximal map or a valid coordinate update.
pub trait Penalty {
    /// Failure returned by penalty evaluation.
    type Error;

    /// Evaluate the penalty, including its strength.
    ///
    /// # Errors
    /// Returns an error for invalid coefficients, parameters, or arithmetic.
    fn value(&self, coefficients: &[f64]) -> Result<f64, Self::Error>;

    /// Check parameters and coefficient compatibility independently of scaling.
    ///
    /// The default evaluates the penalty and discards its value. Implementations
    /// can override this to validate without value arithmetic, allowing a zero
    /// [`Scaled`] penalty to avoid overflow in a value that is never used.
    ///
    /// # Errors
    /// Reject invalid coefficients or parameters. The default also propagates
    /// errors from value evaluation.
    fn validate_input(&self, coefficients: &[f64]) -> Result<(), Self::Error> {
        self.value(coefficients).map(|_| ())
    }
}

impl L1 {
    /// Configured penalty strength.
    pub fn lambda(&self) -> f64 {
        self.lambda
    }

    pub(crate) fn validate<E>(&self) -> Result<(), FitError<E>> {
        if !self.lambda.is_finite() || self.lambda < 0.0 {
            return Err(invalid("lambda must be finite and nonnegative"));
        }
        Ok(())
    }

    pub(crate) fn value_unchecked(&self, coefficients: &[f64]) -> f64 {
        if self.lambda == 0.0 {
            0.0
        } else {
            coefficients
                .iter()
                .map(|value| self.lambda * value.abs())
                .sum()
        }
    }

    pub(crate) fn coordinate_minimum(&self, correlation: f64, curvature: f64) -> f64 {
        let thresholded = if correlation > self.lambda {
            correlation - self.lambda
        } else if correlation < -self.lambda {
            correlation + self.lambda
        } else {
            0.0
        };
        thresholded / curvature
    }
}

impl Penalty for L1 {
    type Error = FitError;

    fn value(&self, coefficients: &[f64]) -> Result<f64, Self::Error> {
        self.validate_input(coefficients)?;
        Ok(finite(
            self.value_unchecked(coefficients),
            "computing the penalty",
            0,
        )?)
    }

    fn validate_input(&self, coefficients: &[f64]) -> Result<(), FitError> {
        self.validate()?;
        if coefficients.iter().any(|value| !value.is_finite()) {
            return Err(invalid("coefficients must be finite"));
        }
        Ok(())
    }
}

/// A convex penalty with an exact proximal map for the complete term.
///
/// Implementations minimize `||z - input||² / (2 * step) + self.value(z)`.
/// This contract applies to the entire penalty, including its strengths. A
/// sum of penalties does not acquire this capability from its summands.
/// A value-only penalty cannot be fitted by proximal gradient:
///
/// ```compile_fail
/// use shrinkage::{FitError, Gaussian, Penalty, Problem, ProximalGradient};
/// use shrinkage::lazymatrix::{ColumnStats, MatVecInto, MatTransposeVecInto, RawColumns};
/// fn fit<M, P>(problem: &Problem<&M, Gaussian<'_>, P>)
/// where
///     M: RawColumns<f64> + ColumnStats<f64>
///         + MatVecInto<Vec<f64>> + MatTransposeVecInto<Vec<f64>>,
///     P: Penalty<Error = FitError>,
/// {
///     let _ = problem.fit_with(&ProximalGradient::<Vec<f64>>::new());
/// }
/// ```
pub trait ProximalPenalty: Penalty<Error = FitError> {
    /// Optional dual feasibility, safe zero screening, and exact zero restriction.
    ///
    /// Implementations without this capability retain ordinary proximal fitting.
    fn gap_safe(&self) -> Option<&dyn crate::screening::GapSafePenalty> {
        None
    }

    /// Write the proximal minimizer into reusable output storage.
    ///
    /// # Errors
    /// Reject invalid parameters, nonpositive or nonfinite steps, mismatched
    /// lengths, nonfinite input, or nonfinite arithmetic. Output is unspecified
    /// after an error.
    fn prox(&self, input: &[f64], step: f64, output: &mut [f64]) -> Result<(), FitError>;
}

/// Ridge penalty `lambda * ||beta||² / 2`, distinct from the L2 norm.
#[derive(Clone, Copy, Debug)]
pub struct Ridge {
    lambda: f64,
}

impl Ridge {
    /// Set the squared L2 strength, checked during evaluation and fitting.
    pub fn new(lambda: f64) -> Self {
        Self { lambda }
    }

    /// Configured squared L2 strength.
    pub fn lambda(&self) -> f64 {
        self.lambda
    }
}

/// Complete elastic-net penalty `l1 * ||beta||₁ + l2 * ||beta||² / 2`.
#[derive(Clone, Copy, Debug)]
pub struct ElasticNet {
    l1: f64,
    l2: f64,
    mixing: Option<f64>,
}

impl ElasticNet {
    /// Set the L1 and squared L2 strengths independently, checked when used.
    pub fn new(l1: f64, l2: f64) -> Self {
        Self {
            l1,
            l2,
            mixing: None,
        }
    }

    /// Use `lambda * (alpha * ||beta||₁ + (1 - alpha) * ||beta||² / 2)`.
    /// Lambda must be finite and nonnegative, and alpha must lie in `[0, 1]`.
    /// Validation occurs during evaluation or fitting. Automatic paths retain
    /// alpha even when the supplied lambda is zero.
    pub fn from_alpha(lambda: f64, alpha: f64) -> Self {
        Self {
            l1: lambda * alpha,
            l2: lambda * (1.0 - alpha),
            mixing: Some(alpha),
        }
    }

    /// Configured mixing parameter, or its equivalent for positive independent
    /// strengths. Two independently supplied zero strengths have no mixing ratio.
    pub fn alpha(&self) -> Option<f64> {
        self.mixing.or_else(|| {
            let scale = self.l1.max(self.l2);
            (scale > 0.0).then(|| (self.l1 / scale) / (self.l1 / scale + self.l2 / scale))
        })
    }

    fn validate(&self) -> Result<(), FitError> {
        L1::new(self.l1).validate()?;
        L1::new(self.l2).validate()?;
        if self
            .mixing
            .is_some_and(|alpha| !alpha.is_finite() || !(0.0..=1.0).contains(&alpha))
        {
            return Err(invalid("elastic-net alpha must be finite and in [0, 1]"));
        }
        Ok(())
    }

    /// Configured L1 strength.
    pub fn l1(&self) -> f64 {
        self.l1
    }

    /// Configured squared L2 strength.
    pub fn l2(&self) -> f64 {
        self.l2
    }
}

impl Penalty for Ridge {
    type Error = FitError;

    fn value(&self, coefficients: &[f64]) -> Result<f64, FitError> {
        ElasticNet::new(0.0, self.lambda).value(coefficients)
    }

    fn validate_input(&self, coefficients: &[f64]) -> Result<(), FitError> {
        L1::new(self.lambda).validate_input(coefficients)
    }
}

impl Penalty for ElasticNet {
    type Error = FitError;

    fn value(&self, coefficients: &[f64]) -> Result<f64, FitError> {
        self.validate()?;
        let l1 = L1::new(self.l1).value(coefficients)?;
        let l2 = if self.l2 == 0.0 {
            0.0
        } else {
            coefficients
                .iter()
                .map(|&coefficient| {
                    let scaled = self.l2.sqrt() * coefficient;
                    0.5 * scaled * scaled
                })
                .sum()
        };
        Ok(finite(l1 + l2, "computing the penalty", 0)?)
    }

    fn validate_input(&self, coefficients: &[f64]) -> Result<(), FitError> {
        self.validate()?;
        L1::new(0.0).validate_input(coefficients)
    }
}

impl ProximalPenalty for L1 {
    fn prox(&self, input: &[f64], step: f64, output: &mut [f64]) -> Result<(), FitError> {
        ElasticNet::new(self.lambda, 0.0).prox(input, step, output)
    }
}

impl ProximalPenalty for Ridge {
    fn prox(&self, input: &[f64], step: f64, output: &mut [f64]) -> Result<(), FitError> {
        ElasticNet::new(0.0, self.lambda).prox(input, step, output)
    }
}

impl ProximalPenalty for ElasticNet {
    fn prox(&self, input: &[f64], step: f64, output: &mut [f64]) -> Result<(), FitError> {
        self.validate()?;
        if input.len() != output.len() {
            return Err(invalid("proximal input and output lengths must match"));
        }
        if !step.is_finite() || step <= 0.0 {
            return Err(invalid(
                "proximal step must be finite and strictly positive",
            ));
        }
        if input.iter().any(|value| !value.is_finite()) {
            return Err(invalid("proximal input must be finite"));
        }
        let threshold = finite(step * self.l1, "computing a proximal threshold", 0)?;
        let denominator = finite(1.0 + step * self.l2, "computing proximal curvature", 0)?;
        for (&value, target) in input.iter().zip(output) {
            *target = value.signum() * (value.abs() - threshold).max(0.0) / denominator;
        }
        Ok(())
    }
}

impl<P: Penalty + ?Sized> Penalty for Box<P> {
    type Error = P::Error;

    fn value(&self, coefficients: &[f64]) -> Result<f64, Self::Error> {
        (**self).value(coefficients)
    }

    fn validate_input(&self, coefficients: &[f64]) -> Result<(), Self::Error> {
        (**self).validate_input(coefficients)
    }
}

impl<P: ProximalPenalty + ?Sized> ProximalPenalty for Box<P> {
    fn gap_safe(&self) -> Option<&dyn crate::screening::GapSafePenalty> {
        (**self).gap_safe()
    }

    fn prox(&self, input: &[f64], step: f64, output: &mut [f64]) -> Result<(), FitError> {
        (**self).prox(input, step, output)
    }
}