% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/gg_beta_varpro.R
\name{gg_beta_varpro}
\alias{gg_beta_varpro}
\title{Per-variable lasso-beta importance from a varPro fit}
\usage{
gg_beta_varpro(object, ..., cutoff = NULL, beta_fit = NULL, which_class = NULL)
}
\arguments{
\item{object}{A \code{varpro} fit from \code{\link[varPro:varpro]{varPro::varpro()}} (regression or
classification family).}

\item{...}{Forwarded to \code{\link[varPro:beta.varpro]{varPro::beta.varpro()}} when \code{beta_fit = NULL};
ignored otherwise (with a warning). Documented forwardables: \code{use.cv},
\code{use.1se}, \code{nfolds}, \code{maxit}, \code{thresh}, \code{max.rules.tree}, \code{max.tree}.}

\item{cutoff}{Selection threshold on \code{beta_mean}. \code{NULL} (default) means
\code{mean(beta_mean)} across released variables. Numeric scalar otherwise.}

\item{beta_fit}{Optional pre-computed \code{\link[varPro:beta.varpro]{varPro::beta.varpro()}} result for
the same \code{object}. \code{NULL} (default) means the wrapper runs \code{beta.varpro()}
itself. When supplied, must be a \code{varpro}-class object whose \verb{$results}
has columns \code{tree / branch / variable / n.oob / imp}.}

\item{which_class}{For a classification fit, name of a single response
level to subset on. \code{NULL} (default) returns all classes (binary fits
resolve to the \emph{last} factor level, the positive-class convention
used by \code{glm} and \code{gg_roc}). Ignored with a warning on regression
fits.}
}
\value{
A \code{data.frame} of class \code{c("gg_beta_varpro", "data.frame")}.
For a regression fit: one row per released variable, sorted by
\code{beta_mean} descending. For a classification fit: long-format with
an extra \code{class} column, one row per (variable, class) pair;
\code{variable} is a factor whose levels are set by
\verb{mean(|sum-of-class-beta|)} descending so every facet / panel shares
the same row order. \code{which_class} (or the binary default
last-factor-level) collapses the output to a single class.
}
\description{
Tidy wrapper around \code{\link[varPro:beta.varpro]{varPro::beta.varpro()}} for the regression or
classification family.
Aggregates the per-rule lasso coefficient \eqn{\hat{\beta}}{beta hat} by
variable into the mean absolute value
\eqn{\mathrm{mean}(|\hat{\beta}|)}{mean(|beta hat|)} and flags variables
above a scalar cutoff. Optional
\code{beta_fit} argument lets callers compute the expensive
\code{beta.varpro()} step once and reuse the result.
}
\note{
Multivariate regression (\verb{regr+}) and survival families are out
of scope for this release and tracked for v3.1.0. The
unsupported-family path errors with a message pointing at that work.
}
\section{What this is doing}{

Think of the varPro release-rule mechanism as asking: "given a region of
the feature space that the forest carved out, what changes when I remove
the constraint on this one variable and let observations leave?" The
standard importance answer (from \code{\link[=gg_varpro]{gg_varpro()}}) measures that change as a
z-scored contrast between local estimators: no synthetic data, no
permutation. \code{beta.varpro()} asks the same question with a different
ruler: for each rule (a tree-branch pair), it fits a one-predictor lasso
regression of the response on the released variable's values, restricted
to the OOB observations inside the rule's region. The wrapper aggregates
those per-rule coefficients into one number per variable.

The key distinction from \code{\link[=gg_vimp]{gg_vimp()}}, which measures Breiman-Cutler
permutation importance by perturbing a variable's values and watching OOB
error climb, is that neither \code{\link[=gg_varpro]{gg_varpro()}} nor \code{gg_beta_varpro()}
touches the data synthetically: all contrasts are between real subsets
defined by the forest's rules.
}

\section{What \code{imp} actually is (pedantic, because the column name is misleading)}{

The \code{imp} column on \code{beta.varpro()}'s \verb{$results} is \strong{not} a
variable-importance score in the conventional sense. It is a regularised
regression coefficient. Specifically:
\itemize{
\item Per rule, \code{glmnet} fits a one-predictor lasso of the response on
the released variable inside the rule's OOB region. \code{use.cv = TRUE}
selects \eqn{\lambda}{lambda} by 10-fold CV (default \code{nfolds = 10});
\code{use.1se = TRUE} (default) picks \code{lambda.1se}. \code{use.cv = FALSE} uses the
full \eqn{\lambda}{lambda} path.
\item \code{imp} is the \strong{fitted coefficient} \eqn{\hat{\beta}}{beta hat} at the
chosen \eqn{\lambda}{lambda}. \strong{Sign is
real} (direction of local association). \strong{Magnitude depends on
the predictor's units} (raw \code{x}, no standardisation); a predictor
in millimetres has a smaller \eqn{|\hat{\beta}|}{|beta hat|} than the
same predictor in metres.
\item Lasso shrinkage can drive \eqn{\hat{\beta}}{beta hat} to \strong{exactly zero}.
Those zeros are
data, not missingness, and are kept in the aggregation. Convergence
failures land as \code{NA_real_} and are dropped.
\item The per-variable aggregate is \code{beta_mean},
\eqn{\mathrm{mean}(|\hat{\beta}|)}{mean(|beta hat|)}, across the
rules where this variable was released. It is \strong{not} a permutation
importance, \strong{not} a split-strength importance, and \strong{not} directly
comparable on the same numeric axis to \code{gg_varpro()}'s z-scores.
Disagreement with \code{gg_varpro} is often diagnostic, not a bug.
}

In code form: \code{imp_r} is the glmnet coefficient \eqn{\hat{\beta}}{beta hat}
fit on \code{y ~ x_v} restricted to rule r, with \eqn{\lambda}{lambda} chosen by
\code{use.cv} / \code{use.1se}.
}

\section{What's in the output}{

One row per released variable. Columns:
\itemize{
\item \code{variable}: predictor name.
\item \code{beta_mean}: mean of \eqn{|\hat{\beta}|}{|beta hat|} across that
variable's rules.
\item \code{n_rules}: count of rules contributing (zero-beta rules included; only
\code{NA} failures excluded).
\item \code{selected}: \code{beta_mean >= cutoff}.
}

Provenance attribute carries \code{source}, \code{family}, \code{ntree}, \code{cutoff},
\code{cutoff_default}, \code{use.cv}, \code{n_rules_total}, \code{n_rules_nonzero},
\code{precomputed}, and \code{xvar.names}.
}

\section{What you use this for}{

Picking variables when local effects matter more than aggregate
split-strength contribution. Compare side-by-side with \code{\link[=gg_varpro]{gg_varpro()}}:
a variable that scores high here but low in \code{gg_varpro} is one whose
local linear effect inside many rules is real even though its
release-rule contrast is modest.
}

\section{Caching}{

\code{beta.varpro()} is the expensive call (per-rule \code{glmnet} / \code{cv.glmnet},
often minutes on real data). Compute it once and reuse:

\if{html}{\out{<div class="sourceCode r">}}\preformatted{v <- varPro::varpro(mpg ~ ., data = mtcars, ntree = 200)
b <- varPro::beta.varpro(v, use.cv = TRUE)        # expensive, once
gg_a <- gg_beta_varpro(v, beta_fit = b)            # cheap
gg_b <- gg_beta_varpro(v, beta_fit = b, cutoff = 0.5)
}\if{html}{\out{</div>}}

Provenance carries \code{precomputed = TRUE} when \code{beta_fit} was supplied.
}

\section{Classification}{

For a varpro classification fit (\code{object$family == "class"},
binary or multi-class), the returned frame is long-format with an
extra \code{class} column: one row per (variable, class) pair. The
\code{beta_mean} column aggregates the \strong{per-class lasso coefficient}
\eqn{\hat{\beta}}{beta hat} stored in
\code{beta.varpro()}'s \verb{imp.<k>} columns (one per class level). Same
pedantic-beta semantics as regression, applied independently to each
class.

\strong{Binary default}: \code{which_class = NULL} resolves to the \emph{last}
factor level of the response, the positive-class convention used
by \code{glm} and \code{gg_roc}. For a 30-day-mortality outcome with levels
\code{c("no", "yes")}, that means the wrapper shows you \code{"yes"} (the
event) by default.

\strong{Multi-class default}: \code{which_class = NULL} returns all K
classes; the plot method renders \code{facet_wrap(~ class)} with one
cutoff line per facet.

\strong{\code{which_class = "<name>"}} filters to a single class regardless
of K. Errors if the name isn't in the response levels.

\strong{Per-class cutoffs}: \code{cutoff = NULL} resolves to each class's
\code{mean(beta_mean)}. A scalar broadcasts. A named numeric vector
overrides per class; missing names fall back to that class's mean.

Example (30-day mortality, binary):

\if{html}{\out{<div class="sourceCode r">}}\preformatted{fit <- varPro::varpro(event_30d ~ ., data = clinical, ntree = 200)
gg  <- gg_beta_varpro(fit)   # default: "yes" panel
plot(gg)
}\if{html}{\out{</div>}}
}

\section{Reproducibility}{

Byte-for-byte agreement between cached (\code{beta_fit = b}) and uncached
(\code{beta_fit = NULL}) outputs requires that \code{b} was computed by
\code{beta.varpro(object, ...)} on the same \code{object}; \code{set.seed()} alone is
not sufficient, because \code{beta.varpro}'s internal \code{cv.glmnet} fits can
pick slightly different folds across separate calls. Reuse \code{beta_fit}
when reproducibility matters.
}

\examples{
\donttest{
if (requireNamespace("varPro", quietly = TRUE)) {
  set.seed(1)
  v <- varPro::varpro(mpg ~ ., data = mtcars, ntree = 50)
  b <- varPro::beta.varpro(v)
  gg <- gg_beta_varpro(v, beta_fit = b)
  plot(gg)
}
}

}
\seealso{
\code{\link[=gg_varpro]{gg_varpro()}}, \code{\link[=gg_vimp]{gg_vimp()}}, \code{\link[=plot.gg_beta_varpro]{plot.gg_beta_varpro()}}, \code{\link[varPro:beta.varpro]{varPro::beta.varpro()}}.
}
