Shrinkage
Shrinkage is a Rust library for regularized statistical models. It currently fits Gaussian lasso models with dense or sparse CSC input through a statically dispatched coordinate-descent solver. Compositional and runtime APIs are planned for later milestones. See DESIGN.md for the architecture and statistical conventions, and TODO.md for the implementation checklist.
Gaussian lasso
Enable the faer feature for this example:
use Mat;
use ;
let x = from_fn;
let fit = new.fit?;
assert_eq!;
let predictions = fit.predict?;
Lasso::new(lambda) defaults to an unpenalized intercept, training-column means
and population standard deviations, an absolute KKT tolerance of 1e-6, and a
limit of 10,000 coordinate sweeps. The objective is
$$ \frac{1}{2n}|y - \widetilde X\theta
- \widetilde b\mathbf1|_2^2 + \lambda|\theta|_1. $$
The penalty acts on the normalized coefficients. coefficients(),
intercept(), and predict() use the original input scale. Fitted centers and
scales remain available through preprocessing(); prediction does not estimate
new statistics.
Choose normalization with .normalize(Normalization::...):
| Option | Centering | Scaling |
|---|---|---|
Auto (default) |
Mean when fitting an intercept; otherwise none | Population standard deviation |
None |
None | None |
Center |
Mean | None |
Standardize |
Mean | Population standard deviation |
MinMax |
Minimum | Range |
MaxAbs |
None | Maximum absolute value |
L1 |
None | L1 norm |
L2 |
None | L2 norm |
Custom { center, scale } |
Selected independently | Selected independently |
Custom choices reuse LazyMatrix's enums, re-exported from Shrinkage:
use ;
let model = new.normalize;
Scales based on norms or maximum absolute values are computed after centering.
Use Normalization::None for the raw design. Only Auto changes centering when
.fit_intercept(false) is selected. Explicit centering is honored even without
a fitted intercept, and its induced original-scale intercept is retained.
Builder call order does not change this behavior. Fitted preprocessing exposes
the resolved centering() and scaling() rules as well as their values.
Computed zero scales become one, and zero-norm normalized columns stay at zero.
Inputs must be finite, and the solver does not impute missing values.
A successful Result contains a finite fit, which may have reached the
iteration limit. Check termination() before treating it as converged. The
result reports iterations(), objective(), and kkt_violation(). The KKT
check uses the averaged loss gradient and includes the intercept condition; it
is confirmed on reconstructed residuals before reporting convergence. Invalid
input, numerical failures, and backend preprocessing failures return distinct
LassoError variants, with backend error sources preserved.
The solver keeps sparse centering in a scalar residual offset. Coordinate dots
and updates touch stored column entries, with residual refreshes every 50 sweeps
and before final reporting. Solver storage is O(n + p); fitting does not
materialize a normalized design or form a Gram matrix.
Run the dense and CSC fitting example:
cargo run --locked --example lasso --features faer
Matrix dependency
The crate pins LazyMatrix 0.3.0 from crates.io. No matrix backend is enabled by default. Versioned features select LazyMatrix's integrations for a particular release line; the short names remain convenience aliases:
| Versioned feature | Alias | Dependencies | Supported input |
|---|---|---|---|
faer_v0_24 |
faer |
faer 0.24 | Dense matrices, dense views, and sparse CSC matrices |
nalgebra_v0_34 |
nalgebra |
nalgebra 0.34 and nalgebra-sparse 0.11 | Dense matrices, dense views, and sparse CSC matrices |
ndarray_v0_17 |
ndarray |
ndarray 0.17 | Two-dimensional arrays and borrowed views |
sprs_v0_11 |
sprs |
sprs 0.11 | Sparse CSC matrices and views wrapped in SprsCsc |
Match your direct matrix dependency to the selected release line. Each versioned feature works independently of its alias, including the faer examples and benchmarks. Shrinkage currently exposes one release line per backend. LazyMatrix 0.3.0 implements traits only for the newest enabled release of each backend, so another dependency enabling a newer adapter on the same LazyMatrix package can remove support for older matrix types.
With ndarray_v0_17 or its ndarray alias, fit directly against an array or
borrowed view:
use array;
use Lasso;
let x = array!;
let fit = new.fit?;
let predictions = fit.predict?;
Row-major, column-major, and strided arrays are supported. Column-major storage keeps each column contiguous for coordinate descent.
With sprs_v0_11 or its sprs alias, wrap CSC storage in
shrinkage::lazymatrix::SprsCsc. The wrapper checks storage orientation without
copying entries:
use ;
use CsMat;
let x = new_csc;
let columns = try_new.unwrap;
let fit = new.fit?;
let predictions = fit.predict?;
SprsCsc::try_new accepts owned matrices and borrowed views. It returns CSR
input unchanged as an error; explicitly convert with csr.to_csc() before
wrapping. Custom matrices can implement LazyMatrix's RawColumns<f64> and
ColumnStats<f64> capabilities.
Run the dense/sparse normalization example:
cargo run --locked --example normalization --features faer
The example checks that lazy products preserve predictions after transforming coefficients and the intercept back to the original scale. It does not fit a model.
Development
Enter the development environment and run the complete local check:
devenv shell
task check
The toolchain is pinned to Rust 1.89.0, which is also the minimum supported Rust
version. Cargo.lock and devenv.lock are tracked for reproducible
development. CI runs the same Rust checks, example, and Panache checks as
task check.
Useful focused commands are:
task format
task lint
task test
task bench
task bench measures end-to-end dense and CSC fitting time, including
validation and preprocessing, with only the faer backend enabled. Dataset
construction is outside the timed region. Allocation and memory profiling remain
later work.
Modules use name.rs and name/child.rs; the repository does not use mod.rs.
Releases
Versionary prepares release pull requests after CI passes on main and manages
CHANGELOG.md. Before enabling releases on GitHub, configure the
RELEASE_TOKEN repository secret with access to contents, pull requests, and
issues. Registry publication is not configured.
License
MIT. See LICENSE.