pub mod runtime;
pub use runtime::{
MatrixDesign, RuntimeDesign, RuntimeMultivariateProblem, RuntimePathProblem, RuntimeProblem,
};
use crate::error::{finite, invalid};
use crate::solver::{ObservedSolver, Solver, SolverObserver, coordinate};
use crate::{Centering, LassoError, LassoFit, Normalization, Preprocessing, Scaling};
pub use crate::{datafit::Gaussian, penalty::L1, solver::CoordinateDescent};
use lazymatrix::{ColumnStats, LazyMatrix, RawColumn, RawColumns};
#[derive(Clone, Debug)]
pub struct Problem<X, D, P> {
design: X,
datafit: D,
penalty: P,
normalization: Normalization,
supplied_centers: Option<Vec<f64>>,
supplied_scales: Option<Vec<f64>>,
}
impl<X, D, P> Problem<X, D, P> {
pub fn new(design: X, datafit: D, penalty: P) -> Self {
Self {
design,
datafit,
penalty,
normalization: Normalization::Auto,
supplied_centers: None,
supplied_scales: None,
}
}
pub fn design(&self) -> &X {
&self.design
}
pub fn datafit(&self) -> &D {
&self.datafit
}
pub fn penalty(&self) -> &P {
&self.penalty
}
pub fn normalization(&self) -> Normalization {
self.normalization
}
pub fn centers(&self) -> Option<&[f64]> {
self.supplied_centers.as_deref()
}
pub fn scales(&self) -> Option<&[f64]> {
self.supplied_scales.as_deref()
}
pub fn fit_with<S: Solver<Self>>(&self, solver: &S) -> Result<S::Fit, S::Error> {
solver.solve(self)
}
pub fn fit_with_observer<S: ObservedSolver<Self>, O: SolverObserver + ?Sized>(
&self,
solver: &S,
observer: &mut O,
) -> Result<S::Fit, S::Error> {
solver.solve_with_observer(self, observer)
}
pub fn fit_from_with_observer<S: ObservedSolver<Self>, O: SolverObserver + ?Sized>(
&self,
solver: &S,
initial: crate::InitialPoint<'_>,
observer: &mut O,
) -> Result<S::Fit, S::Error> {
solver.solve_from_with_observer(self, Some(initial), observer)
}
pub fn fit_path_with<S, Q>(
&self,
solver: &S,
penalties: Vec<Q>,
) -> Result<crate::PathFit<S::Fit, Q>, S::Error>
where
S: crate::PathSolver<Self, Q>,
{
crate::PathSolver::solve_path(solver, self, penalties)
}
pub fn fit_regularization_path_with<S: crate::RegularizationPathSolver<Self>>(
&self,
solver: &S,
options: &crate::PathOptions,
) -> Result<crate::PathFit<S::Fit, S::Penalty>, S::Error> {
solver.solve_regularization_path(self, options)
}
pub fn maximum_penalty_with<S: crate::RegularizationPathSolver<Self>>(
&self,
solver: &S,
) -> Result<crate::PenaltyMaximum, S::Error> {
solver.maximum_penalty(self)
}
pub fn normalize(mut self, normalization: Normalization) -> Self {
self.normalization = normalization;
self
}
pub fn with_centers(mut self, centers: Vec<f64>) -> Self {
self.supplied_centers = Some(centers);
self
}
pub fn with_scales(mut self, scales: Vec<f64>) -> Self {
self.supplied_scales = Some(scales);
self
}
}
impl<M> Solver<Problem<&M, Gaussian<'_>, L1>> for CoordinateDescent
where
M: RawColumns<f64> + ColumnStats<f64> + ?Sized,
{
type Fit = LassoFit;
type Error = LassoError<M::Error>;
fn solve(&self, problem: &Problem<&M, Gaussian<'_>, L1>) -> Result<Self::Fit, Self::Error> {
problem.fit_coordinate(self)
}
}
impl<M> ObservedSolver<Problem<&M, Gaussian<'_>, L1>> for CoordinateDescent
where
M: RawColumns<f64> + ColumnStats<f64> + ?Sized,
{
fn solve_from_with_observer<O: SolverObserver + ?Sized>(
&self,
problem: &Problem<&M, Gaussian<'_>, L1>,
initial: Option<crate::InitialPoint<'_>>,
observer: &mut O,
) -> Result<Self::Fit, Self::Error> {
problem.fit_coordinate_observed(self, initial, observer)
}
}
impl<M> Problem<&M, Gaussian<'_>, L1>
where
M: RawColumns<f64> + ColumnStats<f64> + ?Sized,
{
fn fit_coordinate(&self, solver: &CoordinateDescent) -> Result<LassoFit, LassoError<M::Error>> {
self.penalty.validate()?;
solver.validate(solver.criterion(self.penalty))?;
self.datafit.validate(self.design.nrows())?;
let prepared = self.prepare(self.datafit.fit_intercept)?;
let solution = coordinate::solve(&prepared.matrix, self.datafit, self.penalty, solver)?;
LassoFit::from_solution(solution, prepared.into_preprocessing())
}
fn fit_coordinate_observed<O: SolverObserver + ?Sized>(
&self,
solver: &CoordinateDescent,
initial: Option<crate::InitialPoint<'_>>,
observer: &mut O,
) -> Result<LassoFit, LassoError<M::Error>> {
self.penalty.validate()?;
solver.validate(solver.criterion(self.penalty))?;
self.datafit.validate(self.design.nrows())?;
let prepared = self.prepare(self.datafit.fit_intercept)?;
if let Some(initial) = initial {
initial.validate(prepared.matrix.ncols(), self.datafit.fit_intercept)?;
}
let solution = coordinate::solve_observed(
&prepared.matrix,
self.datafit,
self.penalty,
solver,
initial,
observer,
)?;
LassoFit::from_solution(solution, prepared.into_preprocessing())
}
}
impl<M, D, P> Problem<&M, D, P>
where
M: RawColumns<f64> + ColumnStats<f64> + ?Sized,
{
pub(crate) fn prepare(
&self,
fit_intercept: bool,
) -> Result<Prepared<&M>, LassoError<M::Error>> {
let x = self.design;
if x.nrows() == 0 {
return Err(invalid("training data must have at least one observation"));
}
validate_matrix(x)?;
self.prepare_normalization(fit_intercept)
}
}
impl<M, D, P> Problem<&M, D, P>
where
M: lazymatrix::MatrixShape + ColumnStats<f64> + ?Sized,
{
pub(crate) fn prepare_normalization(
&self,
fit_intercept: bool,
) -> Result<Prepared<&M>, LassoError<M::Error>> {
prepare_normalization(
self.design,
self.normalization,
self.centers(),
self.scales(),
fit_intercept,
)
}
}
pub(crate) fn prepare_normalization<'a, M>(
x: &'a M,
normalization: Normalization,
supplied_centers: Option<&[f64]>,
supplied_scales: Option<&[f64]>,
fit_intercept: bool,
) -> Result<Prepared<&'a M>, LassoError<M::Error>>
where
M: lazymatrix::MatrixShape + ColumnStats<f64> + ?Sized,
{
if x.nrows() == 0 {
return Err(invalid("training data must have at least one observation"));
}
let spec = normalization.specification(fit_intercept);
validate_supplied(supplied_centers, x.ncols(), false)?;
validate_supplied(supplied_scales, x.ncols(), true)?;
let center_rule = if supplied_centers.is_some() {
Centering::None
} else {
spec.center
};
let scale_rule = if supplied_scales.is_some() {
Scaling::None
} else {
spec.scale
};
let centered_scale = supplied_centers.is_some()
&& matches!(scale_rule, Scaling::L1 | Scaling::L2 | Scaling::MaxAbs);
let stats_spec = lazymatrix::ColumnNormalization::new(
center_rule,
if centered_scale {
Scaling::None
} else {
scale_rule
},
);
let (computed_centers, mut computed_scales) =
if stats_spec.center != Centering::None || stats_spec.scale != Scaling::None {
x.normalization_stats(stats_spec)
.map_err(|source| LassoError::Backend {
operation: "computing training normalization statistics",
source,
})?
} else {
(None, None)
};
if centered_scale {
let centers = supplied_centers.unwrap();
computed_scales = Some(
match scale_rule {
Scaling::L1 => x.col_l1_centered(centers),
Scaling::L2 => x.col_l2_centered(centers),
Scaling::MaxAbs => x.col_maxabs_centered(centers),
_ => unreachable!(),
}
.map_err(|source| LassoError::Backend {
operation: "computing training normalization statistics",
source,
})?,
);
}
let centers = supplied_centers.map(<[f64]>::to_vec).or(computed_centers);
let mut scales = supplied_scales.map(<[f64]>::to_vec).or(computed_scales);
validate_statistics(
¢ers,
x.ncols(),
supplied_centers.is_some() || spec.center != Centering::None,
"column centers",
)?;
validate_statistics(
&scales,
x.ncols(),
supplied_scales.is_some() || spec.scale != Scaling::None,
"column scales",
)?;
if let Some(scales) = &mut scales {
for scale in scales {
if *scale < 0.0 {
return Err(invalid(
"matrix backend returned a negative normalization scale",
));
}
if *scale == 0.0 {
*scale = 1.0;
}
}
}
Ok(Prepared {
matrix: LazyMatrix::from_column_parts(x, centers, scales),
spec,
supplied_centers: supplied_centers.is_some(),
supplied_scales: supplied_scales.is_some(),
})
}
pub(crate) struct Prepared<M> {
pub matrix: LazyMatrix<M>,
spec: lazymatrix::ColumnNormalization,
supplied_centers: bool,
supplied_scales: bool,
}
impl<M: lazymatrix::MatrixShape> Prepared<M> {
#[cfg(feature = "experimental-block-reader")]
pub(crate) fn map_data<N: lazymatrix::MatrixShape>(
self,
transform: impl FnOnce(M) -> N,
) -> Prepared<N> {
let (matrix, params) = self.matrix.into_parts();
Prepared {
matrix: LazyMatrix::from_parts(transform(matrix), params),
spec: self.spec,
supplied_centers: self.supplied_centers,
supplied_scales: self.supplied_scales,
}
}
pub fn into_preprocessing(self) -> Preprocessing {
let (_, params) = self.matrix.into_parts();
let (_, centers, scales) = params.into_parts();
Preprocessing {
spec: self.spec,
centers,
scales,
supplied_centers: self.supplied_centers,
supplied_scales: self.supplied_scales,
}
}
}
pub(crate) fn validate_matrix<M: RawColumns<f64> + ?Sized, E>(x: &M) -> Result<(), LassoError<E>> {
for j in 0..x.ncols() {
let column = x.raw_column(j);
if column.len() != x.nrows() || column.stored_len() > x.nrows() {
return Err(invalid(format!(
"matrix backend returned invalid dimensions for column {j}"
)));
}
let mut valid = true;
column.for_each_stored(|i, value| {
valid &= i < x.nrows() && value.is_finite();
});
if !valid {
let mut invalid_row = None;
column.for_each_stored(|i, value| {
if (i >= x.nrows() || !value.is_finite()) && invalid_row.is_none() {
invalid_row = Some(i);
}
});
let i = invalid_row.unwrap();
return Err(invalid(format!(
"invalid matrix entry at row {i}, column {j}: expected an in-bounds, finite value"
)));
}
}
Ok(())
}
fn validate_statistics<E>(
values: &Option<Vec<f64>>,
ncols: usize,
expected: bool,
operation: &'static str,
) -> Result<(), LassoError<E>> {
if values.is_some() != expected || values.as_ref().is_some_and(|v| v.len() != ncols) {
return Err(invalid(format!(
"matrix backend returned unexpected {operation}"
)));
}
if let Some(values) = values {
for &value in values {
finite(value, operation, 0)?;
}
}
Ok(())
}
fn validate_supplied<E>(
values: Option<&[f64]>,
ncols: usize,
scales: bool,
) -> Result<(), LassoError<E>> {
if let Some(values) = values {
let name = if scales { "scales" } else { "centers" };
if values.len() != ncols {
return Err(invalid(format!(
"supplied {name} length {} does not match {ncols} columns",
values.len()
)));
}
for (j, &value) in values.iter().enumerate() {
if !value.is_finite() || (scales && value <= 0.0) {
return Err(invalid(format!("invalid supplied {name} at column {j}")));
}
}
}
Ok(())
}