% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/gg_variable.R
\name{gg_variable}
\alias{gg_variable}
\alias{gg_variable.rfsrc}
\alias{gg_variable.randomForest}
\alias{gg_variable.random}
\title{Marginal variable dependence data object.}
\usage{
gg_variable(object, ...)
}
\arguments{
\item{object}{A \code{\link[randomForestSRC]{rfsrc}} or
\code{\link[randomForest]{randomForest}} object, or a
\code{\link[randomForestSRC]{plot.variable}} result.}

\item{...}{Optional arguments such as \code{time}, \code{time_labels}, and
\code{oob} that tailor the marginal dependence extraction.}
}
\value{
A \code{gg_variable} object: a \code{data.frame} of all predictor
  columns from the training data paired with the OOB (or in-bag) predicted
  response. For survival forests each requested time horizon produces an
  additional column named by \code{time_labels}. The object carries a
  \code{"family"} class attribute (\code{"regr"}, \code{"class"}, or
  \code{"surv"}) used by \code{\link{plot.gg_variable}} for dispatch.
}
\description{
\code{\link[randomForestSRC]{plot.variable}} generates a
\code{data.frame} containing the marginal variable dependence or the
partial variable dependence. The \code{gg_variable} function creates a
\code{data.frame} of containing the full set of covariate data (predictor
variables) and the predicted response for each observation. Marginal
dependence figures are created using the \code{\link{plot.gg_variable}}
function.
For \code{randomForest} fits the original model frame is rebuilt
from the stored call so that the same predictors can be paired with the
in-sample predictions.

Optional arguments include \code{time} (scalar or vector of survival times
of interest), \code{time_labels} (labels for multiple survival horizons) and
\code{oob} which toggles between out-of-bag and in-bag predictions when the
forest stores both.
}
\details{
The marginal variable dependence is determined by comparing
relation between the predicted response from the randomForest and a
covariate of interest.

The \code{gg_variable} function operates on a
\code{\link[randomForestSRC]{rfsrc}} object, the output from the
\code{\link[randomForestSRC]{plot.variable}} function, or on a fitted
\code{\link[randomForest]{randomForest}} object via the formula interface.
}
\examples{
## ------------------------------------------------------------
## classification (small, runs on CRAN)
## ------------------------------------------------------------
## -------- iris data
set.seed(42)
rfsrc_iris <- rfsrc(Species ~ ., data = iris, ntree = 50)

gg_dta <- gg_variable(rfsrc_iris)
plot(gg_dta, xvar = "Sepal.Width")

\donttest{
## ------------------------------------------------------------
## Additional classification / regression / survival examples are
## guarded with \donttest because the cumulative example time exceeds
## the 10-second CRAN budget. Run locally with `R CMD check
## --run-donttest` (or `devtools::check(run_dont_test = TRUE)`) to
## exercise them.
## ------------------------------------------------------------
plot(gg_dta, xvar = "Sepal.Length")
plot(gg_dta, xvar = rfsrc_iris$xvar.names, panel = TRUE)

## ------------------------------------------------------------
## regression
## ------------------------------------------------------------

## -------- air quality data
rfsrc_airq <- rfsrc(Ozone ~ ., data = airquality, ntree = 50)
gg_dta <- gg_variable(rfsrc_airq)

# an ordinal variable
gg_dta[, "Month"] <- factor(gg_dta[, "Month"])

plot(gg_dta, xvar = "Wind")
plot(gg_dta, xvar = "Temp")
plot(gg_dta, xvar = "Solar.R")
plot(gg_dta, xvar = c("Solar.R", "Wind", "Temp", "Day"), panel = TRUE)
plot(gg_dta, xvar = "Month", notch = TRUE)

## -------- motor trend cars data
rfsrc_mtcars <- rfsrc(mpg ~ ., data = mtcars, ntree = 50)

gg_dta <- gg_variable(rfsrc_mtcars)

# mtcars$cyl is an ordinal variable
gg_dta$cyl <- factor(gg_dta$cyl)
gg_dta$am <- factor(gg_dta$am)
gg_dta$vs <- factor(gg_dta$vs)
gg_dta$gear <- factor(gg_dta$gear)
gg_dta$carb <- factor(gg_dta$carb)

plot(gg_dta, xvar = "cyl")
plot(gg_dta, xvar = "disp")
plot(gg_dta, xvar = "hp")
plot(gg_dta, xvar = "wt")
plot(gg_dta, xvar = c("disp", "hp", "drat", "wt", "qsec"), panel = TRUE)
plot(gg_dta,
  xvar = c("cyl", "vs", "am", "gear", "carb"), panel = TRUE,
  notch = TRUE
)

## -------- Boston data
if (requireNamespace("MASS", quietly = TRUE)) {
  data(Boston, package = "MASS")
  rf_boston <- randomForest::randomForest(medv ~ ., data = Boston)
  gg_dta <- gg_variable(rf_boston)
  plot(gg_dta)
  plot(gg_dta, panel = TRUE)
}

## ------------------------------------------------------------
## survival examples
## ------------------------------------------------------------

## -------- veteran data
data(veteran, package = "randomForestSRC")
rfsrc_veteran <- rfsrc(Surv(time, status) ~ ., veteran,
  nsplit = 10,
  ntree = 50
)

# get the 90-day survival time.
gg_dta <- gg_variable(rfsrc_veteran, time = 90)

# Generate variable dependence plots for age and diagtime
plot(gg_dta, xvar = "age")
plot(gg_dta, xvar = "diagtime")

# Generate coplots
plot(gg_dta, xvar = c("age", "diagtime"), panel = TRUE, se = FALSE)

# Compare survival at 30, 90, and 365 days simultaneously
gg_dta <- gg_variable(rfsrc_veteran, time = c(30, 90, 365))
plot(gg_dta, xvar = "age")
}

}
\seealso{
\code{\link{plot.gg_variable}},
  \code{\link[randomForestSRC]{plot.variable}}
}
