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} is a utility package for
#' \code{randomForestSRC} (Ishwaran and Kogalur) for survival,
#' regression and classification forests and uses the \code{ggplot2}
#' (Wickham 2009) package for plotting results. \code{ggRandomForests} is
#' structured to extract data objects from the random forest and provides S3
#' functions for printing and plotting these objects.
#' Requires \code{randomForestSRC} >= 3.4.0.
#'
#' The \code{randomForestSRC} package provides a unified treatment of
#' Breiman's (2001) random forests for a variety of data settings. Regression
#' and classification forests are grown when the response is numeric or
#' categorical (factor) while survival and competing risk forests
#' (Ishwaran et al. 2008, 2012) are grown for right-censored survival data.
#'
#' Many of the figures created by the \code{ggRandomForests} package are also
#' available directly from within the \code{randomForestSRC} package. However,
#' \code{ggRandomForests} offers the following advantages:
#' \itemize{
#' \item Separation of data and figures: \code{ggRandomForest} contains
#' functions that operate on either the \code{\link[randomForestSRC]{rfsrc}}
#' forest object directly, or on the output from \code{randomForestSRC} post
#' processing functions (i.e. \code{plot.variable}) to generate intermediate
#' \code{ggRandomForests}
#' data objects. S3 functions are provide to further process these objects and
#' plot results using the \code{ggplot2} graphics package. Alternatively,
#' users can use these data objects for additional custom plotting or
#' analysis operations.
#'
#' \item Each data object/figure is a single, self contained object. This
#' allows simple modification and manipulation of the data or \code{ggplot2}
#' objects to meet users specific needs and requirements.
#'
#' \item The use of \code{ggplot2} for plotting. We chose to use the
#' \code{ggplot2} package for our figures to allow users flexibility in
#' modifying the figures to their liking. Each S3 plot function returns either
#' a single \code{ggplot2} object, or a \code{list} of \code{ggplot2} objects,
#' allowing users to use additional \code{ggplot2} functions or themes to
#' modify and customize the figures to their liking.
#' }
#'
#' The \code{ggRandomForests} package contains the following data functions:
#' \itemize{
#' \item \code{\link{gg_rfsrc}}: randomForest[SRC] predictions.
#' \item \code{\link{gg_error}}: randomForest[SRC] convergence rate based on
#' the OOB error rate.
#' \item \code{\link{gg_roc}}: ROC curves for randomForest classification
#' models.
#' \item \code{\link{gg_vimp}}: Variable Importance ranking for variable
#' selection.
#' (Ishwaran et.al. 2010).
#' \item \code{\link{gg_variable}}: Marginal variable dependence.
#'
#' \item \code{\link{gg_survival}}: Kaplan-Meier/Nelson-Aalen hazard analysis.
#' }
#'
#' Each of these data functions has an associated S3 plot function that
#' returns \code{ggplot2} objects, either individually or as a list, which can
#' be further customized using standard \code{ggplot2} commands.
#'
#' @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