% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/gg_partial_rfsrc.R
\name{gg_partial_rfsrc}
\alias{gg_partial_rfsrc}
\title{Partial dependence data from an rfsrc model}
\usage{
gg_partial_rfsrc(
  rf_model,
  xvar.names = NULL,
  xvar2.name = NULL,
  newx = NULL,
  partial.time = NULL,
  partial.type = c("surv", "chf", "mort"),
  cat_limit = 10,
  n_eval = 25
)
}
\arguments{
\item{rf_model}{A fitted \code{\link[randomForestSRC]{rfsrc}} object.}

\item{xvar.names}{Character vector of predictor names for which partial
dependence should be computed. Must be a subset of \code{rf_model$xvar.names}.}

\item{xvar2.name}{Optional single character name of a grouping variable in
\code{newx}. When supplied, partial dependence is computed separately for
each unique level of this variable and a \code{grp} column is appended.}

\item{newx}{Optional \code{data.frame} of predictor values to evaluate
partial effects at. Defaults to the training data stored in
\code{rf_model$xvar}. All column names must match \code{rf_model$xvar.names}.}

\item{partial.time}{Numeric vector of desired time points for survival
forests (ignored for regression/classification).  Values are automatically
snapped to the nearest entry in \code{rf_model$time.interest}; see the
\strong{Survival forests} section below.  When \code{NULL} (default),
three quartile points of \code{time.interest} are used.}

\item{partial.type}{Character; type of predicted value for survival
forests, passed through to \code{\link[randomForestSRC]{partial.rfsrc}}.
One of \code{"surv"} (default), \code{"chf"}, or \code{"mort"}. Ignored
for non-survival forests. \code{partial.rfsrc()} requires a non-\code{NULL}
value for survival families; supplying it here avoids a cryptic
\dQuote{argument is of length zero} error from the underlying C code.}

\item{cat_limit}{Variables with fewer than \code{cat_limit} unique values in
\code{newx} are treated as categorical; all others are continuous.
Defaults to 10.}

\item{n_eval}{Number of evaluation points for continuous variables. Instead
of passing all observed values (which can be slow, especially for survival
forests), continuous predictors are evaluated on a quantile grid of this
many points. Categorical variables always use all unique levels.
Defaults to 25.}
}
\value{
A named list with two elements:
\describe{
\item{continuous}{A \code{data.frame} with columns \code{x} (numeric),
\code{yhat}, \code{name} (variable name), and optionally \code{grp}
(the level of \code{xvar2.name}) and \code{time} (survival forests
only) for all continuous predictors.}
\item{categorical}{A \code{data.frame} with the same columns but
\code{x} kept as character, for low-cardinality predictors.}
}
}
\description{
A partial dependence curve marginalizes the forest's prediction over all
other predictors: for each evaluation point of the target variable, the
forest scores every training observation with that value substituted in,
then averages the result.  What you get is the average effect of the target
variable after "integrating out" the rest -- a curve that would be flat if
the variable carried no signal.
}
\details{
This function builds those curves for one or more predictors by calling
\code{\link[randomForestSRC]{partial.rfsrc}} and then tidy-stacking the
results into separate data frames for continuous and categorical variables.
Unlike \code{\link{gg_partial}} (which wraps \code{plot.variable}), you
pass the fitted \code{rfsrc} object directly -- no intermediate
\code{plot.variable} step.

For survival forests, the marginalized quantity depends on
\code{partial.type}: survival probability (\code{"surv"}), cumulative
hazard function (\code{"chf"}), or expected mortality (\code{"mort"}).
You can request the curve at one or more time horizons via
\code{partial.time}; the resulting data have a \code{time} column so the
plot layers them as separate coloured lines.
}
\section{Survival forests and \code{partial.time}}{

\code{\link[randomForestSRC]{partial.rfsrc}} expects every value in
\code{partial.time} to be an exact member of the model's
\code{time.interest} vector, the unique observed event times stored in the
fitted object.  Pass an arbitrary time, even a plausible one such as
\code{c(1, 3)} for a study measured in years, and you get a C-level
prediction error from inside \code{partial.rfsrc}.

\code{gg_partial_rfsrc} takes care of this: every element of
\code{partial.time} is silently snapped to its nearest
\code{time.interest} value before the call.  To target a specific
follow-up horizon, find the closest grid point yourself and pass it
explicitly:

\preformatted{
ti  <- rf_model$time.interest
t1  <- ti[which.min(abs(ti - 1))]   # nearest to 1 year
pd  <- gg_partial_rfsrc(rf_model, xvar.names = "x", partial.time = t1)
}
}

\section{Logical predictor columns}{

\code{\link[randomForestSRC]{partial.rfsrc}} does not handle
\code{logical} predictor columns correctly in survival forests
(randomForestSRC <= 3.5.1).  If your training data contains binary 0/1
columns, convert them to \code{\link{factor}} rather than \code{logical}
before fitting the model.
}

\examples{
## ------------------------------------------------------------
##
## regression
##
## ------------------------------------------------------------

airq.obj <- randomForestSRC::rfsrc(Ozone ~ ., data = airquality)

## partial effect for wind
prt_dta <- gg_partial_rfsrc(airq.obj,
                       xvar.names = c("Wind"))

}
\seealso{
\code{\link{gg_partial}}, \code{\link[randomForestSRC]{partial.rfsrc}},
\code{\link[randomForestSRC]{get.partial.plot.data}}
}
