% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/f2sreg.R
\name{f2sSP}
\alias{f2sSP}
\title{Overlap Group Least Absolute Shrinkage and Selection Operator for scalar-on-function regression model}
\usage{
f2sSP(
  vY,
  mX,
  mZ = NULL,
  M,
  group_weights = NULL,
  var_weights = NULL,
  weights_adaptive = FALSE,
  standardize.data = TRUE,
  splOrd = 4,
  diff_order = 1,
  lambda = NULL,
  lambda2 = NULL,
  nlambda = 30,
  lambda.min.ratio = NULL,
  intercept = FALSE,
  overall.group = FALSE,
  control = list()
)
}
\arguments{
\item{vY}{a length-\eqn{n} vector of observations of the scalar response variable.}

\item{mX}{a \eqn{(n\times r)} matrix of observations of the functional covariate.}

\item{mZ}{an \eqn{(n\times q)} full column rank matrix of scalar predictors that are not penalized.}

\item{M}{number of elements of the B-spline basis vector \eqn{\varphi(t)}.}

\item{group_weights}{a vector of length \eqn{G} containing group-specific weights. The default is square root of the group cardinality, see Bernardi et al. (2022).}

\item{var_weights}{a vector of length \eqn{M} containing basis-specific weights. The default is a vector where 
each entry is the reciprocal of the number of groups including that basis. See Bernardi et al. (2022) for details.}

\item{weights_adaptive}{logical. If \code{TRUE}, adaptive weights are computed from an initial 
least squares estimate. This option is ignored (and set to \code{FALSE}) when 
\code{group_weights} are provided by the user, since external weights override the adaptive scheme.}

\item{standardize.data}{logical. Should data be standardized?}

\item{splOrd}{the order \eqn{d} of the spline basis.}

\item{diff_order}{order of the discrete difference operator used in the smoothness penalty.
The default is 1.}

\item{lambda}{either a regularization parameter or a vector of regularization parameters.
In this latter case the routine computes the whole path. If it is NULL values for lambda are provided by the routine.}

\item{lambda2}{either a non-negative smoothing regularization parameter or a vector of
smoothing regularization parameters. If \code{NULL}, no smoothness penalty is used.}

\item{nlambda}{the number of lambda values - default is 30.}

\item{lambda.min.ratio}{smallest value for lambda, as a fraction of the maximum lambda value. If \eqn{n>M}, the default is 0.0001, and if \eqn{n<M}, the default is 0.01.}

\item{intercept}{logical. If it is TRUE, a column of ones is added to the design matrix.}

\item{overall.group}{logical. If it is TRUE, an overall group including all penalized covariates is added.}

\item{control}{a list of control parameters for the ADMM algorithm. See ‘Details’.}
}
\value{
A named list containing \describe{
\item{sp.coefficients}{a length-\eqn{M} solution vector for the parameters \eqn{\psi}, which corresponds to the minimum in-sample MSE.}
\item{sp.coef.path}{an \eqn{(n_\lambda\times M)} matrix of estimated \eqn{\psi} coefficients for each lambda.}
\item{sp.fun}{a length-\eqn{r} vector providing the estimated functional coefficient for \eqn{\psi(t)}.}
\item{sp.fun.path}{an \eqn{(n_\lambda\times r)} matrix providing the estimated functional coefficients for \eqn{\psi(t)} for each lambda.}
\item{coefficients}{a length-\eqn{q} solution vector for the parameters \eqn{\gamma}, which corresponds to the minimum in-sample MSE. 
It is provided only when either the matrix \eqn{Z} in input is not NULL or the intercept is set to TRUE.}
\item{coef.path}{an \eqn{(n_\lambda\times q)} matrix of estimated \eqn{\gamma} coefficients for each lambda. 
It is provided only when either the matrix \eqn{Z} in input is not NULL or the intercept is set to TRUE.}
\item{dof}{estimated degrees of freedom for each value of the regularization parameter.}
\item{dof.groups_active}{active groups used in the degrees-of-freedom computation for each value of the regularization parameter.}
\item{dof.coeff_active}{active coefficient indices used in the degrees-of-freedom computation for each value of the regularization parameter.}
\item{dof.vars_active}{active basis coefficients used in the degrees-of-freedom computation for each value of the regularization parameter.}
\item{bic}{Bayesian information criterion computed along the regularization path.}
\item{lambda.min}{value of lambda that attains the minimum in-sample MSE.}
\item{lambda}{sequence of lambda.}
\item{lambda2}{sequence of smoothing regularization parameters. It is \code{NULL} when no smoothness penalty is used.}
\item{mse}{in-sample mean squared error.}
\item{min.mse}{minimum value of the in-sample MSE for the sequence of lambda.}
\item{convergence}{logical. 1 denotes achieved convergence.}
\item{elapsedTime}{elapsed time in seconds.}
\item{iternum}{number of iterations.}
}

When you run the algorithm, output returns not only the solution, but also the iteration history recording
following fields over iterates,
\describe{
\item{objval}{objective function value.}
\item{r_norm}{norm of primal residual.}
\item{s_norm}{norm of dual residual.}
\item{eps_pri}{feasibility tolerance for primal feasibility condition.}
\item{eps_dual}{feasibility tolerance for dual feasibility condition.}
}
Iteration stops when both \code{r_norm} and \code{s_norm} values
become smaller than \code{eps_pri} and \code{eps_dual}, respectively.
}
\description{
Overlap Group-LASSO for scalar-on-function regression model solves the following optimization problem
\deqn{\textrm{min}_{\psi,\gamma} ~ \frac{1}{2} \sum_{i=1}^n \left( y_i - \int x_i(t) \psi(t) dt-z_i^\intercal\gamma \right)^2 + \lambda \sum_{g=1}^{G} \Vert S_{g}T\psi \Vert_2}
to obtain a sparse coefficient vector \eqn{\psi\in\mathbb{R}^{M}} for the functional penalized predictor \eqn{x(t)} and a coefficient vector \eqn{\gamma\in\mathbb{R}^q} for the unpenalized scalar predictors \eqn{z_1,\dots,z_q}. The regression function is \eqn{\psi(t)=\varphi(t)^\intercal\psi}
where \eqn{\varphi(t)} is a B-spline basis of order \eqn{d} and dimension \eqn{M}. For each group \eqn{g}, each row of 
the matrix \eqn{S_g\in\mathbb{R}^{d\times M}} has non-zero entries only for those bases belonging 
to that group. These values are provided by the arguments \code{groups} and \code{group_weights} (see below). 
Each basis function belongs to more than one group. The diagonal matrix \eqn{T\in\mathbb{R}^{M\times M}} contains 
the basis-specific weights. These values are provided by the argument \code{var_weights} (see below).
The regularization path is computed for the overlap group-LASSO penalty at a grid of values for the regularization 
parameter \eqn{\lambda} using the alternating direction method of multipliers (ADMM). See Boyd et al. (2011) and Lin et al. (2022) 
for details on the ADMM method.
}
\section{Details}{
 The control argument is a list that can supply any of the following components:\describe{
\item{adaptation}{logical. If it is TRUE, ADMM with adaptation is performed. The default value is TRUE. See Boyd et al. (2011) for details.}
\item{rho}{an augmented Lagrangian parameter. The default value is 1.}
\item{tau.ada}{an adaptation parameter greater than one. Only needed if adaptation = TRUE. The default value is 2. See Boyd et al. (2011) and Lin et al. (2022) for details.}
\item{mu.ada}{an adaptation parameter greater than one. Only needed if adaptation = TRUE. The default value is 10. See Boyd et al. (2011) and Lin et al. (2022) for details.}
\item{dof.toler_c}{tolerance parameter used in the degrees-of-freedom computation to determine active constraints.}
\item{dof.toler_d}{tolerance parameter used in the degrees-of-freedom computation to determine active coefficients or groups.}
\item{abstol}{absolute tolerance stopping criterion. The default value is sqrt(sqrt(.Machine$double.eps)).}
\item{reltol}{relative tolerance stopping criterion. The default value is sqrt(.Machine$double.eps).}
\item{maxit}{maximum number of iterations. The default value is 100.}
\item{print.out}{logical. If it is TRUE, a message about the procedure is printed. The default value is TRUE.}
}
}

\examples{

## generate sample data
set.seed(1)
n     <- 40
p     <- 18                                  # number of basis to GENERATE beta
r     <- 100
s     <- seq(0, 1, length.out = r)

beta_basis <- splines::bs(s, df = p, intercept = TRUE)    # basis
coef_data  <- matrix(rnorm(n*floor(p/2)), n, floor(p/2))        
fun_data   <- coef_data \%*\% t(splines::bs(s, df = floor(p/2), intercept = TRUE))     

x_0   <- apply(matrix(rnorm(p, sd=1),p,1), 1, fdaSP::softhresh, 1)  # regression coefficients 
x_fun <- beta_basis \%*\% x_0                

b     <- fun_data \%*\% x_fun + rnorm(n, sd = sqrt(crossprod(fun_data \%*\% x_fun ))/10)
l     <- 10^seq(2, -4, length.out = 30)
maxit <- 1000


## set the hyper-parameters
maxit          <- 1000
rho_adaptation <- TRUE
rho            <- 1
reltol         <- 1e-5
abstol         <- 1e-5

mod <- f2sSP(vY = b, mX = fun_data, M = p,
             group_weights = NULL, var_weights = NULL, standardize.data = FALSE, splOrd = 4,
             lambda = NULL, nlambda = 30, lambda.min = NULL, overall.group = FALSE, 
             control = list("abstol" = abstol, 
                            "reltol" = reltol, 
                            "adaptation" = rho_adaptation, 
                            "rho" = rho, 
                            "print.out" = FALSE)) 

# plot coefficiente path
matplot(log(mod$lambda), mod$sp.coef.path, type = "l", 
        xlab = latex2exp::TeX("$\\\\log(\\\\lambda)$"), ylab = "", bty = "n", lwd = 1.2)

}
\references{
\insertRef{bernardi_etal.2022}{fdaSP}

\insertRef{boyd_etal.2011}{fdaSP}

\insertRef{jenatton_etal.2011}{fdaSP}

\insertRef{lin_etal.2022}{fdaSP}
}
