%\VignetteIndexEntry{PICASSO 2.0.0 user guide}
%\VignettePackage{picasso}
%\VignetteEncoding{UTF-8}

\documentclass[11pt,a4paper]{article}
\usepackage[T1]{fontenc}
\usepackage[margin=1in]{geometry}
\usepackage{array}
\usepackage{hyperref}
\hypersetup{colorlinks=true,linkcolor=blue,urlcolor=blue}
\setlength{\parindent}{0pt}
\setlength{\parskip}{0.55em}

\title{PICASSO 2.0.0 User Guide}
\author{PICASSO authors}
\date{July 2026}

\begin{document}
\maketitle

\begin{abstract}
PICASSO fits sparse regularization paths with lasso, MCP, and SCAD penalties.
This guide summarizes the current R interface, solver choices, accuracy modes,
diagnostics, prediction, assessment, and cross-validation.
\end{abstract}

\section{Supported models}

\begin{center}
\begin{tabular}{>{\ttfamily}p{0.19\textwidth}p{0.31\textwidth}p{0.38\textwidth}}
\hline
family & response & native optimization \\
\hline
gaussian & finite numeric & active-set coordinate descent \\
binomial & exactly two levels; factor levels are retained & active-set Proximal Newton/IRLS \\
poisson & non-negative integer counts; at least one positive & active-set Proximal Newton/IRLS \\
sqrtlasso & finite numeric & active-set quadratic-MM updates \\
multinomial & at least three observed classes & class-coupled active-set Proximal Newton/IRLS \\
\hline
\end{tabular}
\end{center}

Every family supports \verb|method = "l1"|, \verb|"mcp"|, or \verb|"scad"|.
MCP requires \verb|gamma > 1| and SCAD requires \verb|gamma > 2|.
Generated paths request up to 100 decreasing lambda values by default, with a
nominal endpoint at 0.05 times the null-model maximum. The returned prefix may
be shorter after normal path stopping. An explicit path must be finite,
non-negative, and strictly decreasing.

\section{Basic fitting}

\begin{verbatim}
library(picasso)
set.seed(1)
n <- 120; d <- 30
X <- matrix(rnorm(n * d), n, d)
y <- 0.5 + X[, 1] - 0.7 * X[, 2] + rnorm(n)

fit <- picasso(X, y, family = "gaussian", method = "l1",
               nlambda = 30)
fit$type.gaussian.requested
fit$type.gaussian
coef(fit, lambda.idx = fit$nlambda, beta.idx = 1:5)
predict(fit, X[1:5, ], lambda.idx = fit$nlambda)
\end{verbatim}

R uses one-based \verb|lambda.idx| and \verb|beta.idx| values. Prediction by
lambda value is also available through \verb|s|; coefficients are linearly
interpolated inside the fitted path and clamped at its endpoints.

\section{Gaussian backend selection}

The public default is \verb|type.gaussian = "auto"|. It uses covariance
updates only when the path has at least eight lambdas, the design is not wide,
and at most 1024 features are present. Within those guards, covariance updates
are selected for at least one of the following: at most 160 features, a
requested/generated path endpoint ratio of at least 0.10, a ratio of at
least 0.05 with
\(n \mathrel{\geq} 4d\), or \(n \mathrel{\geq} 16d\). The feature guard caps a
fully populated numeric Gram cache at 8 MiB.

Set \verb|type.gaussian = "naive"| or \verb|"covariance"| to pin a backend.
Fit objects record both the requested and resolved modes. Cross-validation
reuses the full-data decision in every fold.

\section{Adaptive LLA and accuracy}

For MCP and SCAD binomial, Poisson, square-root-lasso, and multinomial fits,
PICASSO solves a sequence of weighted-L1 subproblems using adaptive local
linear approximation (LLA). The minimum and default maximum are three total
stages: one L1 master and two weighted-L1 updates. A larger
\verb|lla.max.stages| allows additional stages; after the minimum three, the
solver stops when target stationarity is no larger than \verb|prec|.
Gaussian MCP/SCAD uses its direct coordinate-descent implementation instead.

\verb|fast.mode = FALSE| is the default; \verb|prec| then defaults to
\verb|1e-7| and may be set to another positive value.
\verb|fast.mode = TRUE| uses benchmark-calibrated achieved-accuracy tolerances:
\verb|4e-4| for Poisson, \verb|1e-4| for binomial, square-root-lasso, and
multinomial, and \verb|1e-7| for Gaussian. These values are not literal copies
of another solver's stopping parameter. Custom \verb|prec| values are
available only with fast mode disabled.

\section{Offsets, standardization, and path stopping}

Binomial and Poisson fits accept one offset per observation:

\begin{verbatim}
exposure <- runif(n, 0.5, 2)
off <- log(exposure)
count <- rpois(n, exp(off + 0.2 + X[, 1]))
pfit <- picasso(X, count, family = "poisson", offset = off)
mu <- predict(pfit, X[1:5, ], lambda.idx = pfit$nlambda,
              newoffset = off[1:5])
\end{verbatim}

Offsets are added on the link scale. Response/link prediction, assessment,
and binomial class prediction from an offset-fitted model require a matching
\verb|newoffset|; support extraction does not. With
\verb|standardize = TRUE|, predictors are centered only when an intercept is
included; no-intercept models preserve the original zero point.

\verb|dfmax| stops a path when its nonzero count becomes too large. Generated
multinomial paths may also omit a saturated tail after at least five fitted
lambdas. Explicit multinomial paths disable only this saturation rule; they
may still return a prefix after \verb|dfmax| stopping or a hard failure.

\section{Diagnostics and usable termination}

Non-Gaussian fit objects include \verb|status|, \verb|status.code|,
\verb|failure|, and per-lambda \verb|diagnostics|. Diagnostics report native
runtime, objective, weighted-L1 KKT residual, and target stationarity. Scalar
families also report completed LLA stages; multinomial fits report outer
iterations, inner sweeps, and coordinate updates.

Status codes 0 (completed), 1 (\verb|dfmax_reached|), and 10
(\verb|lla_stationarity_limit|) return usable models. Code 10 means the stage
budget ended before stationarity certification; it is not a hard failure.
A later hard failure retains only the committed path prefix and records the
failed lambda and stage.

\section{Assessment and cross-validation}

\begin{verbatim}
metrics <- assess.picasso(fit, X, y)
cv <- cv.picasso(X, y, family = "gaussian", nfolds = 5,
                 nlambda = 30)
cv$lambda.min
coef(cv, s = "lambda.1se", beta.idx = 1:5)
\end{verbatim}

Assessment reports family-appropriate deviance, MSE, MAE, or class error.
Confusion matrices are available for binomial and multinomial fits.
Categorical CV folds are stratified by default and retain the full-data class
map. Normal stopping may shorten the initial full-data generated path. That
fixed retained path is then passed explicitly to every fold, and a truncated
or otherwise unusable fold is reported as an error. If a very deep scalar path
triggers such saturation, request fewer lambdas or a less aggressive endpoint.

\section{Further information}

The package help page \verb|?picasso| is the authoritative argument and return
value reference. Reproducible R and Python examples are in the repository's
\verb|tutorials| directory. The
\href{https://www.jmlr.org/papers/v20/17-722.html}{original PICASSO paper}
describes the pathwise active-set framework; newer interfaces documented here
were added after that publication.

\end{document}