R/help.R

In ggRandomForests: Visually Exploring Random Forests

####**********************************************************************
####**********************************************************************
####
####  ----------------------------------------------------------------
####  Written by:
####    John Ehrlinger, Ph.D.
####
####    email:  john.ehrlinger@gmail.com
####    URL:    https://github.com/ehrlinger/ggRandomForests
####  ----------------------------------------------------------------
####
####**********************************************************************
####**********************************************************************
###############################################################################
# Package documentation
###############################################################################
#' @title ggRandomForests: Visually Exploring Random Forests
#'
#' @description \code{ggRandomForests} provides \code{ggplot2} (Wickham 2009)
#' diagnostic and exploration figures for random forests grown with
#' \code{\link[randomForestSRC]{rfsrc}} (>= 3.4.0) or
#' \code{\link[randomForest]{randomForest}}.
#'
#' \code{randomForestSRC} gives a unified treatment of Breiman's (2001) random
#' forests across data settings: regression and classification forests when the
#' response is numeric or categorical, survival and competing-risk forests
#' (Ishwaran et al. 2008) for right-censored data.
#'
#' @details
#' The package is built on one decision: keep the data step and the figure step
#' apart. A \code{gg_*} function pulls a tidy data object out of the forest; its
#' \code{plot()} method turns that object into a figure. Two things follow.
#'
#' The data object stands on its own. It carries everything its plot needs, so
#' you can save it, inspect it, or come back to it later without keeping the
#' original forest -- which can be large -- in memory.
#'
#' You are never locked into the default figure. Each \code{plot()} method
#' returns a single plottable object: a \code{ggplot} you extend with \code{+},
#' or a \code{patchwork} composite for the multi-panel methods. Add layers, swap
#' scales, apply a theme -- or ignore the default entirely and build the figure
#' from the tidy data yourself. Every \code{gg_*} object also carries
#' \code{print()} and \code{summary()} methods: \code{print()} shows a short
#' header rather than dumping every row, and \code{summary()} returns a
#' diagnostics object.
#'
#' \strong{Forest diagnostics}
#' \itemize{
#' \item \code{\link{gg_rfsrc}}: predicted versus observed values.
#' \item \code{\link{gg_error}}: OOB error against the number of trees.
#' \item \code{\link{gg_vimp}}: variable importance ranking
#'   (Ishwaran et al. 2010).
#' \item \code{\link{gg_variable}}: marginal variable dependence.
#' \item \code{\link{gg_roc}}: ROC curves for classification forests
#'   (see also \code{\link{calc_roc}} and \code{\link{calc_auc}}).
#' \item \code{\link{gg_survival}}: Kaplan-Meier / Nelson-Aalen estimates.
#' \item \code{\link{gg_brier}}: time-resolved Brier score and CRPS for
#'   survival forests.
#' }
#'
#' \strong{Partial dependence}
#' \itemize{
#' \item \code{\link{gg_partial}}: tidies the output of
#'   \code{randomForestSRC::plot.variable(partial = TRUE)}.
#' \item \code{\link{gg_partial_rfsrc}}: computes partial dependence from the
#'   fitted forest directly, via \code{partial.rfsrc}.
#' }
#'
#' \strong{SHAP explanations}
#' \itemize{
#' \item \code{\link{gg_shap}}: SHAP values for regression and classification
#'   forests, wrapping \code{\link[kernelshap]{kernelshap}}, with
#'   \code{\link{shap_importance}}, \code{\link{shap_beeswarm}} and
#'   \code{\link{shap_dependence}} figures.
#' }
#'
#' \strong{varPro rule-based variable selection}
#' \itemize{
#' \item \code{\link{gg_varpro}}: variable importance from a \code{varpro} fit.
#' \item \code{\link{gg_partial_varpro}} (alias
#'   \code{\link{gg_partialpro}}): partial effects on an interpretable scale.
#' \item \code{\link{gg_beta_varpro}}: per-region lasso coefficients.
#' \item \code{\link{gg_isopro}}: isolation-forest outlier scores.
#' \item \code{\link{gg_ivarpro}}: individual (per-observation) importance.
#' }
#'
#' \strong{Unsupervised varPro}
#' \itemize{
#' \item \code{\link{gg_udependent}}: variable dependency graph.
#' \item \code{\link{gg_beta_uvarpro}}: entropy-based variable ranking.
#' \item \code{\link{gg_sdependent}}: signal-variable detection.
#' }
#'
#' \pkg{varPro} is a required dependency (\code{Imports}), so the varPro
#' families are always available. \code{kernelshap} is in \code{Suggests}:
#' \code{\link{gg_shap}} checks for it and fails with a clear message when it
#' is not installed.
#'
#' @references
#' Breiman, L. (2001). Random forests, Machine Learning, 45:5-32.
#'
#' Ishwaran H. and Kogalur U.B. randomForestSRC: Random Forests for Survival,
#' Regression and Classification. R package version >= 3.4.0.
#' \url{https://cran.r-project.org/package=randomForestSRC}
#'
#' Ishwaran H. and Kogalur U.B. (2007). Random survival forests for R. R News
#' 7(2), 25--31.
#'
#' Ishwaran H., Kogalur U.B., Blackstone E.H. and Lauer M.S. (2008). Random
#' survival forests. Ann. Appl. Statist. 2(3), 841--860.
#'
#' Ishwaran, H., U. B. Kogalur, E. Z. Gorodeski, A. J. Minn, and M. S. Lauer
#' (2010). High-dimensional variable selection for survival data. J. Amer.
#' Statist. Assoc. 105, 205-217.
#'
#' Ishwaran, H. (2007). Variable importance in binary regression trees and
#' forests. Electronic J. Statist., 1, 519-537.
#'
#' Wickham, H. ggplot2: elegant graphics for data analysis. Springer New York,
#' 2009.
#'
#' @name ggRandomForests-package
#'
################
NULL