% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/gg_partial_varpro.R, R/gg_partialpro.R
\name{gg_partial_varpro}
\alias{gg_partial_varpro}
\alias{gg_partialpro}
\title{Partial dependence data from a varPro model}
\usage{
gg_partial_varpro(
  part_dta = NULL,
  object = NULL,
  scale = c("auto", "rmst", "mortality", "surv", "chf"),
  time = NULL,
  nvars = NULL,
  cat_limit = 10,
  model = NULL
)

gg_partialpro(
  part_dta,
  object = NULL,
  scale = c("auto", "rmst", "mortality", "surv", "chf"),
  time = NULL,
  nvars = NULL,
  cat_limit = 10,
  model = NULL
)
}
\arguments{
\item{part_dta}{Passed to \code{\link{gg_partial_varpro}}.}

\item{object}{Passed to \code{\link{gg_partial_varpro}}.}

\item{scale}{Passed to \code{\link{gg_partial_varpro}}.}

\item{time}{Passed to \code{\link{gg_partial_varpro}}.}

\item{nvars}{Passed to \code{\link{gg_partial_varpro}}.}

\item{cat_limit}{Passed to \code{\link{gg_partial_varpro}}.}

\item{model}{Passed to \code{\link{gg_partial_varpro}}.}
}
\value{
A named list of class \code{"gg_partial_varpro"} with elements:
\describe{
\item{continuous}{data.frame with columns \code{variable},
\code{parametric}, \code{nonparametric}, \code{causal}, \code{name}
(and optionally \code{model}).}
\item{categorical}{data.frame with the same columns, one row per
observation per category level.}
}
A \code{"provenance"} attribute carries \code{source}, \code{family},
\code{ntree}, \code{n}, \code{scale}, \code{rmst_tau},
\code{xvar.names}, and \code{path}.

A \code{gg_partial_varpro} object (see
\code{\link{gg_partial_varpro}}).
}
\description{
\code{varPro::partialpro} returns one list, with continuous and
categorical predictors mixed together. This function splits that list into
two tidy data frames, one for each kind, and resolves the y-axis label the
plot method will use.

\emph{Deprecated.} \code{gg_partialpro()} has been superseded by
\code{\link{gg_partial_varpro}()} and is now a thin alias for it.  It will
be removed in the release after \pkg{ggRandomForests} v3.0.0; use
\code{\link{gg_partial_varpro}()} directly.
}
\details{
\strong{Scale detection:} with \code{scale = "auto"} and an \code{object} in
hand, the scale resolves to \code{"mortality"} for a survival forest and
\code{"generic"} for a regression or classification forest.  The RMST
horizon \eqn{\tau} is \emph{not} stored in the \code{varpro} object
(varPro 3.1.0), so for RMST-labeled output you have to pass
\code{scale = "rmst", time = tau} yourself.

\strong{Ensemble mortality (scale = "mortality"):} here the y-axis is
\emph{ensemble mortality}, the expected number of events a subject would
see if they were exposed to the study-average cumulative hazard.  It is
the same quantity as the \code{rfsrc} \code{predicted} value for survival
forests (Ishwaran, Kogalur, Blackstone & Lauer, 2008
\url{doi:10.1214/08-AOAS169}).  This is an \strong{unbounded relative-risk
score}, \emph{not} a survival probability and not \eqn{1 - S(t)}; don't
read it as one.  If you want output on the probability scale, refit with
\code{varpro(..., rmst = tau)} and use \code{scale = "rmst"}.
}
\section{What partialpro is doing}{

A partial dependence curve answers the question, "if I hold a single
variable at a grid of values and average out everything else, how does
the model's prediction move?" That is the same question \code{rfsrc}
partial dependence answers. What \code{varPro::partialpro} adds is two
wrinkles that are worth understanding before you read the curves.

First, \code{partialpro} filters the partial grid through an isolation
forest (Unlimited Virtual Twins, or UVT) so that unlikely combinations
of the focal variable with the rest of the data are downweighted. The
\code{rfsrc} version, by contrast, averages over the full marginal grid
regardless of plausibility. So when a covariate is highly correlated
with others, the two methods can disagree, and \code{partialpro}'s
curve is the one restricted to the data manifold.

Second, \code{partialpro} fits a local polynomial model to the
predicted values rather than just plotting their mean. That gives
three parallel curves per variable, stored as \code{yhat.par},
\code{yhat.nonpar}, and \code{yhat.causal}, which the plot method
overlays so you can see whether a smooth parametric story and the
raw forest predictions are telling you the same thing.

Interpretation of the y-axis depends on the outcome (per
\code{varPro::partialpro}): response scale for regression, log-odds of
the target class for classification, and either ensemble mortality
(default) or RMST (if the original \code{varpro} call set
\code{rmst}) for survival.
}

\section{What's in the output}{

We split \code{partialpro}'s mixed list into two tidy data frames so
the plot method does not have to. A variable with more than
\code{cat_limit} distinct grid points goes into \code{$continuous},
one row per grid point with the column means of \code{yhat.par},
\code{yhat.nonpar}, and \code{yhat.causal} stored as
\code{parametric}, \code{nonparametric}, and \code{causal}. A
variable at or below \code{cat_limit} goes into \code{$categorical},
one row per observation per category level, carrying the same three
columns unaveraged so the plot method can draw boxplots. Path C
(\code{scale \%in\% c("surv","chf")}) takes a different route: we
hand the underlying \code{rfsrc} forest to \code{gg_partial_rfsrc} so
you get a survival-probability or cumulative-hazard curve on the
usual rfsrc scale instead.
}

\section{What you use this for}{

\itemize{
\item read the marginal shape of a relationship the varpro model
found important: monotone, threshold, U-shape, flat;
\item compare the three partialpro estimators on the same variable
and flag the ones where parametric and nonparametric disagree,
those are the candidates for closer inspection;
\item report a survival partial dependence on the probability or
cumulative-hazard scale (\code{scale = "surv"} or \code{"chf"})
rather than the unbounded mortality scale.
}
A varpro partial dependence curve is a description of the model, not
a causal effect. The \code{causal} column is varpro's local
estimator, not a structural causal claim about the data-generating
process.
}

\examples{
set.seed(42)
n_obs <- 30; n_pts <- 15
mock_data <- list(
  age = list(
    xvirtual    = seq(30, 80, length.out = n_pts),
    xorg        = sample(seq(30, 80, by = 5), n_obs, replace = TRUE),
    yhat.par    = matrix(rnorm(n_obs * n_pts), nrow = n_obs),
    yhat.nonpar = matrix(rnorm(n_obs * n_pts), nrow = n_obs),
    yhat.causal = matrix(rnorm(n_obs * n_pts), nrow = n_obs)
  ),
  sex = list(
    xvirtual    = c(0, 1),
    xorg        = sample(c(0, 1), n_obs, replace = TRUE),
    yhat.par    = matrix(rnorm(n_obs * 2), nrow = n_obs),
    yhat.nonpar = matrix(rnorm(n_obs * 2), nrow = n_obs),
    yhat.causal = matrix(rnorm(n_obs * 2), nrow = n_obs)
  )
)
result <- gg_partial_varpro(mock_data)
head(result$continuous)
head(result$categorical)

}
\references{
Ishwaran H, Kogalur UB, Blackstone EH, Lauer MS (2008).
Random survival forests. \emph{The Annals of Applied Statistics},
\bold{2}(3), 841--860. \doi{10.1214/08-AOAS169}.
}
\seealso{
\code{\link{plot.gg_partial_varpro}},
\code{\link{gg_varpro}}, \code{\link{gg_vimp}},
\code{\link{gg_partialpro}} (deprecated),
\code{\link{gg_partial_rfsrc}}, \code{\link{varpro_feature_names}}

\code{\link{gg_partial_varpro}}
}
