shrinkage 0.4.0

Composable regularized statistical models in Rust.
Documentation
//! Regularized statistical models with lazy matrix normalization.
//!
//! [`Lasso`] fits Gaussian lasso models using dense or sparse CSC columns.
//! Fits return original-scale parameters, reusable training preprocessing,
//! and explicit convergence diagnostics. See [`Lasso::terminate_on`] for the
//! stopping criterion and [`LassoFit::termination`] before using a fit.
//!
//! The primal objective is `P(beta_0, beta) = F(beta_0, beta) + R(beta)`,
//! with datafit `F`, complete penalty `R`, coefficients `beta`, and intercept
//! `beta_0`. For a feasible dual variable `theta`, the dual objective is
//! `D(theta)` and the duality gap is
//! `G(beta_0, beta, theta) = P(beta_0, beta) - D(theta)`.
//!
//! No matrix backend is enabled by default. Versioned features select
//! LazyMatrix's integrations with faer 0.24 (`faer_v0_24`), nalgebra 0.34 and
//! nalgebra-sparse 0.11 (`nalgebra_v0_34`), ndarray 0.17 (`ndarray_v0_17`), or
//! sprs 0.11 (`sprs_v0_11`). The short names `faer`, `nalgebra`, `ndarray`, and
//! `sprs` are aliases for these features. Match your direct matrix dependency
//! to the selected release line.
//!
//! LazyMatrix implements each enabled backend release independently, so
//! feature unification retains support for the selected matrix types.
//! faer CSC inputs also accept borrowed `SparseColMatRef` views, including
//! cross-validation, without first cloning the source matrix.
//!
//! With `ndarray_v0_17` or its `ndarray` alias, fit directly against an array or
//! borrowed view:
//!
//! ```
//! # #[cfg(feature = "ndarray_v0_17")] {
//! use ndarray::array;
//! use shrinkage::Lasso;
//!
//! let x = array![[0.0], [1.0], [2.0]];
//! let fit = Lasso::new(0.1).fit(&x.view(), &[1.0, 3.0, 5.0])?;
//! let predictions = fit.predict(&x)?;
//! # }
//! # Ok::<(), Box<dyn std::error::Error>>(())
//! ```
//!
//! With `sprs_v0_11` or its `sprs` alias, wrap CSC storage in
//! `lazymatrix::SprsCsc`. Borrowing a view checks its orientation without copying
//! its entries:
//!
//! ```
//! # #[cfg(feature = "sprs_v0_11")] {
//! use shrinkage::{Lasso, lazymatrix::SprsCsc};
//! use sprs::CsMat;
//!
//! let x = CsMat::new_csc((3, 1), vec![0, 2], vec![1, 2], vec![1.0, 2.0]);
//! let columns = SprsCsc::try_new(x.view()).unwrap();
//! let fit = Lasso::new(0.1).fit(&columns, &[1.0, 3.0, 5.0])?;
//! let predictions = fit.predict(&columns)?;
//! # }
//! # Ok::<(), Box<dyn std::error::Error>>(())
//! ```
//!
//! For CSR input, explicitly convert with `to_csc()` before wrapping. ndarray
//! supports row-major, column-major, and strided arrays; column-major storage
//! keeps each column contiguous for coordinate descent.
//!
//! [`lazymatrix::IndexedRows`] borrows a raw row selection. Normalization uses
//! only those observations, and predictions retain the original feature scale:
//!
//! ```
//! # #[cfg(feature = "ndarray_v0_17")] {
//! use ndarray::array;
//! use shrinkage::{Lasso, lazymatrix::IndexedRows};
//!
//! let x = array![[0.0], [100.0], [2.0]];
//! let rows = [0, 2];
//! let training = IndexedRows::new(&x, &rows);
//! let fit = Lasso::new(0.1).fit(&training, &[1.0, 5.0])?;
//! assert_eq!(fit.preprocessing().centers(), Some([1.0].as_slice()));
//! let predictions = fit.predict(&x)?;
//! # }
//! # Ok::<(), Box<dyn std::error::Error>>(())
//! ```
//!
//! Indexed columns filter the source on each traversal. Built-in
//! cross-validation instead copies selected entries into owned fold matrices
//! once, keeping repeated solver sweeps on that storage.

pub mod cross_validation;
pub mod datafit;
pub mod error;
#[cfg(feature = "experimental-block-reader")]
pub mod experimental;
pub mod fit;
pub mod layout;
pub mod link;
pub mod model;
pub mod normalization;
pub mod path;
pub mod penalty;
pub mod problem;
pub mod screening;
pub mod solver;

pub use cross_validation::{
    CrossValidation, CrossValidationDatafit, CrossValidationError, CrossValidationFit,
    FoldAssignments, FoldPath, RowSubset, SelectionRule, ValidationFit, ValidationMetric,
};
pub use datafit::{
    Binomial, Datafit, DiagonalHessianDatafit, DifferentiableDatafit, Gaussian, LinkedDatafit,
    MultivariateGaussian, QuadraticModelDatafit, SmoothDatafit,
};
pub use error::FitError as LassoError;
pub use error::{BackendError, FitError};
pub use fit::{
    HybridFit, IrlsFit, LassoFit, MultivariateFit, Preprocessing, ProximalFit, Termination,
};
pub use layout::CoefficientLayout;
pub use link::{ConvexLink, Identity, Link, Logit, Probit, TwiceDifferentiableLink};
pub use model::{Lasso, lasso};
pub use normalization::{Centering, Normalization, QuantileRange, Scaling};
pub use path::{
    ErasedPathPenalty, NullModelDatafit, PathDatafit, PathFit, PathOptions, PathPenalty,
    PathSolver, PathTermination, PenaltyMaximum, RegularizationPathSolver,
};
pub use penalty::{
    AxisPenalty, ChainFusedLasso, ClusteredLasso, CoordinatePenalty, DisjointGroups, ElasticNet,
    GroupLasso, L1, Masked, Penalty, PenaltyAxis, ProximalPenalty, RestrictedProximalPenalty,
    Ridge, Scaled, Slope, UncoveredPolicy,
};
pub use problem::{
    MatrixDesign, Problem, RuntimeDesign, RuntimeMultivariateProblem, RuntimePathProblem,
    RuntimeProblem,
};
pub use screening::{
    DualCertificate, GapSafeDatafit, GapSafePenalty, ScreeningDesign, ScreeningDiagnostics,
};
pub use solver::{
    CoordinateDescent, HybridCoordinateDescent, HybridStep, InitialPoint, Irls, ObservedSolver,
    ProximalDesign, ProximalGradient, ProximalVector, Solver, SolverObserver, SolverStep, StepKind,
    StoppingCriterion, WorkingSetDiagnostics, WorkingSetPolicy,
};

/// Matrix capabilities, borrowed columns, and lazy normalization.
pub use lazymatrix;