shrinkage 0.4.0

Composable regularized statistical models in Rust.
Documentation

Shrinkage

CI crates.io docs.rs DOI

Shrinkage is a Rust library for fitting regression models with penalties that shrink coefficients, select features, or encourage structure. It supports linear and logistic regression, dense and sparse matrices, and fitting across a range of penalty strengths. Start with Lasso for linear regression with feature selection, or combine losses, penalties, and solvers to build other models.

See the documentation for installation, the Rust API reference, and contributor guides.

Installation

Add shrinkage from crates.io and enable the feature for your matrix library. For example, to use faer:

cargo add shrinkage --features faer
cargo add faer@0.24

The core library requires Rust 1.84 or newer. Some optional matrix backends require a newer compiler; see the compatibility guide.

Python bindings are under development. See the Python package guide for their current status and source installation.

Usage

Fit a Gaussian lasso model and predict from a matrix whose rows are observations and columns are features:

use faer::Mat;
use shrinkage::{Lasso, Termination};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let x = Mat::from_fn(3, 1, |i, _| i as f64);
    let y = [1.0, 3.0, 5.0];

    let fit = Lasso::new(0.1).fit(&x, &y)?;
    assert_eq!(fit.termination(), Termination::Converged);

    println!("Coefficients: {:?}", fit.coefficients());
    println!("Intercept: {}", fit.intercept());
    println!("Predictions: {:?}", fit.predict(&x)?);
    Ok(())
}

By default, Lasso standardizes features and fits an intercept without penalizing it. The penalty applies to standardized coefficients, while the returned coefficients and intercept use the original input scale. Prediction uses the preprocessing learned during fitting. Check termination() to see whether the solver converged or reached its iteration limit.

Compose a loss, a penalty, and a compatible solver for other models. For Gaussian elastic net:

use faer::{Col, Mat};
use shrinkage::{ElasticNet, Gaussian, Problem, ProximalGradient};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let x = Mat::from_fn(3, 1, |i, _| i as f64);
    let y = [1.0, 3.0, 5.0];

    let fit = Problem::new(&x, Gaussian::new(&y), ElasticNet::new(0.1, 0.2))
        .fit_with(&ProximalGradient::<Col<f64>>::new())?;

    println!("Coefficients: {:?}", fit.coefficients());
    Ok(())
}

The examples cover more models, sparse input, and regularization paths. Run one from a checkout with:

cargo run --locked --example regularization_path --features faer

Supported models

  • Linear and logistic regression, plus multivariate linear regression for multiple responses.
  • Lasso, ridge, and elastic net for feature selection and coefficient shrinkage.
  • Structured penalties: Group LASSO selects groups of features, SLOPE applies ranked penalties, clustered lasso encourages equal coefficients, and chain fused lasso encourages neighboring coefficients to be equal.
  • Regularization paths fit a sequence of penalty strengths, reusing previous fits and workspaces across all solver families. Automatic paths support deviance-based early stopping; explicit paths fit every supplied point. See the regularization path example.
  • Cross-validation fits a complete path within each training fold, scores held-out observations, selects by minimum error or the one-standard-error rule, and refits on all observations. Gaussian and binomial models support seeded folds, explicit candidates, and training-only automatic anchors. See the cross-validation example.

Solvers include coordinate descent, proximal gradient, hybrid coordinate descent, and iteratively reweighted least squares (IRLS). Supported combinations vary by loss and penalty. The Rust API reference covers these combinations and how to add custom losses and penalties. See the binomial example for logistic regression.

Matrix backends

No matrix backend is enabled by default. Match your matrix dependency to one of these features:

Feature Versioned feature Supported input
faer faer_v0_24 Dense and sparse CSC matrices, including borrowed views
nalgebra nalgebra_v0_34 Dense matrices, views, and nalgebra-sparse 0.11 CSC
ndarray ndarray_v0_17 Two-dimensional arrays and views
sprs sprs_v0_11 Sparse CSC matrices and views through SprsCsc

The short names are aliases for the listed versioned features. Matrix access and normalization use LazyMatrix. The installation guide also covers experimental file-backed input through Zarr.

Fitting also accepts shrinkage::lazymatrix::IndexedRows to borrow a raw row selection and estimate normalization on that selection alone. Built-in cross-validation keeps owned fold matrices so repeated sweeps reuse the selected storage.

Documentation

Citation

If you use Shrinkage in your research, please cite the release you used. Select that release in the Zenodo archive and export its citation. To cite Shrinkage generally, use the concept DOI 10.5281/zenodo.23613100.

Machine-readable metadata is available in CITATION.cff.

Contributing

Read the contribution guide and the development guide for setup and focused checks. Enter the pinned development environment and run the complete check with:

devenv shell
task check

License

Shrinkage is licensed under the MIT license.