linfa_elasticnet/
lib.rs

1#![doc = include_str!("../README.md")]
2
3use linfa::Float;
4use ndarray::{Array1, Array2};
5
6#[cfg(feature = "serde")]
7use serde_crate::{Deserialize, Serialize};
8
9mod algorithm;
10mod error;
11mod hyperparams;
12
13pub use error::{ElasticNetError, Result};
14pub use hyperparams::{
15    ElasticNetParams, ElasticNetParamsBase, ElasticNetValidParams, ElasticNetValidParamsBase,
16    MultiTaskElasticNetParams, MultiTaskElasticNetValidParams,
17};
18
19#[cfg_attr(
20    feature = "serde",
21    derive(Serialize, Deserialize),
22    serde(crate = "serde_crate")
23)]
24/// Elastic Net model
25///
26/// This struct contains the parameters of a fitted elastic net model. This includes the seperating
27/// hyperplane, (optionally) intercept, duality gaps and the number of step needed in the
28/// computation.
29///
30/// ## Model implementation
31///
32/// The coordinate descent algorithm is used to solve the lasso and ridge problem. It optimizes
33/// each parameter seperately, holding all the others fixed. This cycles as long as the
34/// coefficients have not stabilized or the maximum number of iterations is reached.
35///
36/// See also:
37/// * [Talk on Fast Regularization Paths](https://web.stanford.edu/~hastie/TALKS/glmnet.pdf)
38/// * [Regularization Paths for Generalized Linear Models via Coordinate Descent](http://www.jstatsoft.org/v33/i01/paper)
39#[derive(Debug, Clone)]
40pub struct ElasticNet<F> {
41    hyperplane: Array1<F>,
42    intercept: F,
43    duality_gap: F,
44    n_steps: u32,
45    variance: Result<Array1<F>>,
46}
47
48impl<F: Float> ElasticNet<F> {
49    /// Create a default parameter set for construction of ElasticNet model
50    ///
51    /// By default, an intercept will be fitted. To disable fitting an
52    /// intercept, call `.with_intercept(false)` before calling `.fit()`.
53    ///
54    /// To additionally normalize the feature matrix before fitting, call
55    /// `fit_intercept_and_normalize()` before calling `fit()`. The feature
56    /// matrix will not be normalized by default.
57    pub fn params() -> ElasticNetParams<F> {
58        ElasticNetParams::new()
59    }
60
61    /// Create a ridge only model
62    pub fn ridge() -> ElasticNetParams<F> {
63        ElasticNetParams::new().l1_ratio(F::zero())
64    }
65
66    /// Create a LASSO only model
67    pub fn lasso() -> ElasticNetParams<F> {
68        ElasticNetParams::new().l1_ratio(F::one())
69    }
70}
71
72#[cfg_attr(
73    feature = "serde",
74    derive(Serialize, Deserialize),
75    serde(crate = "serde_crate")
76)]
77/// MultiTask Elastic Net model
78///
79/// This struct contains the parameters of a fitted multi-task elastic net model. This includes the
80/// coefficients (a 2-dimensional array), (optionally) intercept (a 1-dimensional array), duality gaps
81/// and the number of steps needed in the computation.
82///
83/// ## Model implementation
84///
85/// The block coordinate descent is widely used to solve generalized linear models optimization problems,
86/// like Group Lasso, MultiTask Ridge or MultiTask Lasso. It cycles through a group of parameters and update
87/// the groups separately, holding all the others fixed. The optimization routine stops when a criterion is
88/// satisfied (dual sub-optimality gap or change in coefficients).
89#[derive(Debug, Clone)]
90pub struct MultiTaskElasticNet<F> {
91    hyperplane: Array2<F>,
92    intercept: Array1<F>,
93    duality_gap: F,
94    n_steps: u32,
95    variance: Result<Array1<F>>,
96}
97
98impl<F: Float> MultiTaskElasticNet<F> {
99    pub fn params() -> MultiTaskElasticNetParams<F> {
100        MultiTaskElasticNetParams::new()
101    }
102
103    /// Create a multi-task ridge only model
104    pub fn ridge() -> MultiTaskElasticNetParams<F> {
105        MultiTaskElasticNetParams::new().l1_ratio(F::zero())
106    }
107
108    /// Create a multi-task Lasso only model
109    pub fn lasso() -> MultiTaskElasticNetParams<F> {
110        MultiTaskElasticNetParams::new().l1_ratio(F::one())
111    }
112}