% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/gg_roc.R
\name{gg_roc.rfsrc}
\alias{gg_roc.rfsrc}
\alias{gg_roc}
\alias{gg_roc.randomForest}
\title{ROC (Receiver Operating Characteristic) curve data from a classification forest.}
\usage{
\method{gg_roc}{rfsrc}(object, which_outcome, oob = TRUE, per_class = FALSE, ...)
}
\arguments{
\item{object}{A classification \code{\link[randomForestSRC]{rfsrc}} or
\code{\link[randomForest]{randomForest}} object. Only forests with
\code{family == "class"} (rfsrc) or \code{type == "classification"}
(randomForest) are supported.}

\item{which_outcome}{Integer index or character name of the class to score.
For binary forests this is usually \code{1} or \code{2}; for multi-class
forests, any valid class index or level name. \code{which_outcome = "all"}
or \code{0} behaves differently by engine:
\describe{
\item{\code{randomForest} method}{Returns a macro-averaged
one-vs-rest ROC computed over the per-class probabilities.}
\item{\code{rfsrc} method}{Warns and falls back to class 1. The
macro-average and per-class faceting for the \code{rfsrc} path
are tracked separately under issue #72.}
}}

\item{oob}{Logical; if \code{TRUE} (default), build the curve from
out-of-bag predicted probabilities, otherwise from full in-bag
predictions. For \code{randomForest}, \code{TRUE} uses the out-of-bag
vote probabilities in \code{object$votes}; \code{FALSE} uses in-bag
\code{predict(type = "prob")}.}

\item{per_class}{Logical; if \code{TRUE} and the forest has more than two
classes, return one ROC curve per class, each class scored against all
the others. The result is a long-format \code{data.frame} with a
\code{class} factor column and a named AUC vector attribute, ordered by
descending AUC. Binary forests treat \code{per_class = TRUE} as a no-op.
Honoured by the \code{randomForest} method only.}

\item{...}{Extra arguments (currently unused).}
}
\value{
A \code{gg_roc} \code{data.frame}, one row per unique prediction
threshold, with columns:
\describe{
\item{sens}{Sensitivity (true positive rate) at the threshold.}
\item{spec}{Specificity (true negative rate) at the threshold.}
\item{pct}{The probability threshold used for that row.}
}
Pass it to \code{\link{calc_auc}} for the area under the curve.
}
\description{
A classifier does not hand you a class; it hands you a predicted probability,
and you pick a threshold. Slide that threshold from 0 to 1 and the trade-off
between catching the positives and crying wolf shifts the whole way. The ROC
curve traces that trade-off. For one class of a classification
\code{\link[randomForestSRC]{rfsrc}} or
\code{\link[randomForest]{randomForest}} forest, \code{gg_roc} walks every
threshold and records sensitivity (the true positive rate) against
specificity (1 minus the false positive rate).
}
\examples{
## ------------------------------------------------------------
## classification example
## ------------------------------------------------------------
## -------- iris data
rfsrc_iris <- randomForestSRC::rfsrc(Species ~ ., data = iris)

# ROC for setosa
gg_dta <- gg_roc(rfsrc_iris, which_outcome = 1)
plot(gg_dta)

# ROC for versicolor
gg_dta <- gg_roc(rfsrc_iris, which_outcome = 2)
plot(gg_dta)

# ROC for virginica
gg_dta <- gg_roc(rfsrc_iris, which_outcome = 3)
plot(gg_dta)

## -------- iris data
rf_iris <- randomForest::randomForest(Species ~ ., data = iris)

# ROC for setosa
gg_dta <- gg_roc(rf_iris, which_outcome = 1)
plot(gg_dta)

# ROC for versicolor
gg_dta <- gg_roc(rf_iris, which_outcome = 2)
plot(gg_dta)

# ROC for virginica
gg_dta <- gg_roc(rf_iris, which_outcome = 3)
plot(gg_dta)

}
\seealso{
\code{\link{plot.gg_roc}}, \code{\link{calc_roc}},
\code{\link{calc_auc}},
\code{\link[randomForestSRC]{rfsrc}},
\code{\link[randomForest]{randomForest}}
}
