addresses #17

tlienart · tlienart · commit 2111955e1924 · 2020-05-17T13:15:41.000+02:00
diff --git a/src/mlj/classifiers.jl b/src/mlj/classifiers.jl
@@ -2,6 +2,32 @@
    LOGISTIC CLASSIFIER
    =================== =#
 
+"""
+$SIGNATURES
+
+Logistic Classifier (typically called "Logistic Regression"). This model is
+a standard classifier for both binary and multiclass classification.
+In the binary case it corresponds to the LogisticLoss, in the multiclass to the
+Multinomial (softmax) loss. An elastic net penalty can be applied with
+overall objective function
+
+``L(y, Xθ) + λ|θ|₂²/2 + γ|θ|₁``
+
+Where `L` is either the logistic or multinomial loss and `λ` and `γ` indicate
+the strength of the L2 (resp. L1) regularisation components.
+
+## Parameters
+* `penalty` (Symbol or String): the penalty to use, either `:l2`, `:l1`, `:en`
+                                (elastic net) or `:none`. (Default: `:l2`)
+* `lambda` (Real): strength of the regulariser if `penalty` is `:l2` or `:l1`.
+                   Strength of the L2 regulariser if `penalty` is `:en`.
+* `gamma` (Real): strength of the L1 regulariser if `penalty` is `:en`.
+* `fit_intercept` (Bool): whether to fit an intercept (Default: `true`)
+* `penalize_intercept` (Bool): whether to penalize intercept (Default: `false`)
+* `solver` (Solver): type of solver to use, default if `nothing`.
+* `multi_class` (Bool): whether it's a binary or multi class classification
+                        problem. This is usually set automatically.
+"""
 @with_kw_noshow mutable struct LogisticClassifier <: MMI.Probabilistic
     lambda::Real             = 1.0
     gamma::Real              = 0.0
@@ -25,6 +51,12 @@ descr(::Type{LogisticClassifier}) = "Classifier corresponding to the loss functi
    MULTINOMIAL CLASSIFIER
    ====================== =#
 
+"""
+$SIGNATURES
+
+See `LogisticClassifier`, it's the same except that `multi_class` is set
+to `true` by default. The other parameters are the same.
+"""
 @with_kw_noshow mutable struct MultinomialClassifier <: MMI.Probabilistic
     lambda::Real             = 1.0
     gamma::Real              = 0.0
diff --git a/src/mlj/regressors.jl b/src/mlj/regressors.jl
@@ -28,6 +28,22 @@ descr(::Type{LinearRegressor}) = "Regression with objective function ``|Xθ - y|
    RIDGE REGRESSOR
    =============== =#
 
+"""
+$SIGNATURES
+
+Ridge regression model with objective function
+
+``|Xθ - y|₂²/2 + λ|θ|₂²/2``
+
+## Parameters
+
+* `lambda` (Real): strength of the L2 regularisation.
+* `fit_intercept` (Bool): whether to fit the intercept or not.
+* `penalize_intercept` (Bool): whether to penalize the intercept.
+* `solver`: type of solver to use (if `nothing` the default is used). The
+            solver is Cholesky by default but can be Conjugate-Gradient as
+            well. See `?Analytical` for more information.
+"""
 @with_kw_noshow mutable struct RidgeRegressor <: MMI.Deterministic
     lambda::Real             = 1.0
     fit_intercept::Bool      = true
@@ -46,6 +62,22 @@ descr(::Type{RidgeRegressor}) = "Regression with objective function ``|Xθ - y|
    LASSO REGRESSOR
    =============== =#
 
+"""
+$SIGNATURES
+
+Lasso regression model with objective function
+
+``|Xθ - y|₂²/2 + λ|θ|₁``
+
+## Parameters
+
+* `lambda` (Real): strength of the L1 regularisation.
+* `fit_intercept` (Bool): whether to fit the intercept or not.
+* `penalize_intercept` (Bool): whether to penalize the intercept.
+* `solver`: type of solver to use (if `nothing` the default is used). Either
+            `FISTA` or `ISTA` can be used (proximal methods, with/without
+            acceleration).
+"""
 @with_kw_noshow mutable struct LassoRegressor <: MMI.Deterministic
     lambda::Real             = 1.0
     fit_intercept::Bool      = true
@@ -64,6 +96,23 @@ descr(::Type{LassoRegressor}) = "Regression with objective function ``|Xθ - y|
    ELASTIC NET REGRESSOR
    ===================== =#
 
+"""
+$SIGNATURES
+
+Elastic net regression model with objective function
+
+``|Xθ - y|₂²/2 + λ|θ|₂²/2 + γ|θ|₁``
+
+## Parameters
+
+* `lambda` (Real): strength of the L2 regularisation.
+* `gamma` (Real): strength of the L1 regularisation.
+* `fit_intercept` (Bool): whether to fit the intercept or not.
+* `penalize_intercept` (Bool): whether to penalize the intercept.
+* `solver`: type of solver to use (if `nothing` the default is used). Either
+            `FISTA` or `ISTA` can be used (proximal methods, with/without
+            acceleration).
+"""
 @with_kw_noshow mutable struct ElasticNetRegressor <: MMI.Deterministic
     lambda::Real             = 1.0
     gamma::Real              = 0.0
@@ -83,6 +132,28 @@ descr(::Type{ElasticNetRegressor}) = "Regression with objective function ``|Xθ
    ROBUST REGRESSOR (General)
    ========================== =#
 
+"""
+$SIGNATURES
+
+Robust regression model with objective function
+
+``∑ρ(Xθ - y) + λ|θ|₂² + γ|θ|₁``
+
+where `ρ` is a robust loss function (e.g. the Huber function).
+
+## Parameters
+
+* `rho` (RobustRho): the type of robust loss to use (see `HuberRho`,
+                     `TalwarRho`, ...)
+* `penalty` (Symbol or String): the penalty to use, either `:l2`, `:l1`, `:en`
+                                (elastic net) or `:none`. (Default: `:l2`)
+* `lambda` (Real): strength of the regulariser if `penalty` is `:l2` or `:l1`.
+                   Strength of the L2 regulariser if `penalty` is `:en`.
+* `gamma` (Real): strength of the L1 regulariser if `penalty` is `:en`.
+* `fit_intercept` (Bool): whether to fit an intercept (Default: `true`)
+* `penalize_intercept` (Bool): whether to penalize intercept (Default: `false`)
+* `solver` (Solver): type of solver to use, default if `nothing`.
+"""
 @with_kw_noshow mutable struct RobustRegressor <: MMI.Deterministic
     rho::RobustRho           = HuberRho(0.1)
     lambda::Real             = 1.0
@@ -105,6 +176,14 @@ descr(::Type{RobustRegressor}) = "Robust regression with objective ``∑ρ(Xθ -
    HUBER REGRESSOR
    =============== =#
 
+"""
+$SIGNATURES
+
+Huber Regression, see `RobustRegressor`, it's the same but with the robust loss
+set to `HuberRho`.  The parameters are the same apart from `delta` which
+parametrises the `HuberRho` function (radius of the ball within which the loss
+is a quadratic loss).
+"""
 @with_kw_noshow mutable struct HuberRegressor <: MMI.Deterministic
     delta::Real              = 0.5
     lambda::Real             = 1.0
@@ -127,6 +206,14 @@ descr(::Type{HuberRegressor}) = "Robust regression with objective ``∑ρ(Xθ -
    QUANTILE REGRESSOR
    ================== =#
 
+"""
+$SIGNATURES
+
+Quantile Regression, see `RobustRegressor`, it's the same but with the robust
+loss set to `QuantileRho`.  The parameters are the same apart from `delta`
+which parametrises the `QuantileRho` function (indicating the  quantile to use
+with default `0.5` for the median regression).
+"""
 @with_kw_noshow mutable struct QuantileRegressor <: MMI.Deterministic
     delta::Real              = 0.5
     lambda::Real             = 1.0
@@ -149,6 +236,17 @@ descr(::Type{QuantileRegressor}) = "Robust regression with objective ``∑ρ(Xθ
    LEAST ABSOLUTE DEVIATION REGRESSOR
    ================================== =#
 
+"""
+$SIGNATURES
+
+Least Absolute Deviation regression with with objective function
+
+``∑ρ(Xθ - y) + λ|θ|₂² + γ|θ|₁``
+
+where `ρ` is the absolute loss.
+
+See also `RobustRegressor`.
+"""
 @with_kw_noshow mutable struct LADRegressor <: MMI.Deterministic
     lambda::Real             = 1.0
     gamma::Real              = 0.0
