% 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{
Computes partial dependence for one or more predictors by calling
\code{\link[randomForestSRC]{partial.rfsrc}} internally, then splits the
results into separate data frames for continuous and categorical variables.
Unlike \code{\link{gg_partial}}, no separate \code{plot.variable} call is
required — supply the fitted \code{rfsrc} object directly.
}
\section{Survival forests and \code{partial.time}}{

\code{\link[randomForestSRC]{partial.rfsrc}} requires that every value in
\code{partial.time} be an exact member of the model's \code{time.interest}
vector (the unique observed event times stored in the fitted object).
Passing arbitrary time values — even plausible ones such as \code{c(1, 3)}
for a study measured in years — causes a C-level prediction error inside
\code{partial.rfsrc}.

\code{gg_partial_rfsrc} handles this automatically: every element of
\code{partial.time} is silently snapped to its nearest \code{time.interest}
value before the call is made.  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 <- 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}}
}
