Learn R Programming

ggRandomForests: Visually Exploring Random Forests

ggRandomForests provides ggplot2-based diagnostic and exploration plots for random forests. It reads rfsrc fits from randomForestSRC::rfsrc(), varpro fits from varPro::varpro(), and rhf fits from randomForestRHF::rhf(), a random-hazard forest for time-to-event data whose predictor values can change during follow-up. It also supports randomForest fits. Supported minimum versions are randomForestSRC 3.4.0, varPro 3.3.0, and randomForestRHF 2.0.3. The package keeps the data step apart from the figure step, so you can inspect, save, or reuse the tidy object on its own.

Listed in the ggplot2 extensions gallery.

Installation

# CRAN (stable)
install.packages("ggRandomForests")

# Development version from GitHub
# install.packages("remotes")
remotes::install_github("ehrlinger/ggRandomForests")

Quick start

library(randomForestSRC)
library(ggRandomForests)

# 1. Fit a forest (regression)
rf <- rfsrc(medv ~ ., data = MASS::Boston, importance = TRUE)

# 2. Check convergence: did the forest grow enough trees?
plot(gg_error(rf))

# 3. Rank predictors by importance
plot(gg_vimp(rf))

# 4. Marginal dependence for top variables
gg_v <- gg_variable(rf)
plot(gg_v, xvar = "lstat")
plot(gg_v, xvar = rf$xvar.names, panel = TRUE, se = FALSE)

# 5. Partial dependence for a single predictor
pv <- plot.variable(rf, xvar.names = "lstat", partial = TRUE, show.plots = FALSE)
pd <- gg_partial(pv)
plot(pd)

For survival forests, see the package vignette:

vignette("ggRandomForests")

For Random Hazard Forests with predictors that change during follow-up, see the RHF vignette:

vignette("rhf", package = "ggRandomForests")

For variable importance with varPro (partial dependence, importance z-scores, beta importance, individual/local importance, and isolation forests), see the dedicated vignette:

vignette("varpro", package = "ggRandomForests")

The unsupervised varPro tools, gg_udependent(), gg_beta_uvarpro(), and gg_sdependent(), read structure off a varPro::uvarpro() fit with no outcome. They have their own short vignette:

vignette("uvarpro", package = "ggRandomForests")

Function reference

Grouped by what you are trying to look at. The first column is the function you call, the second is what you hand it.

The forest itself

FunctionInputWhat you get
gg_error()rfsrc / randomForestOOB error vs. number of trees
gg_vimp()rfsrc / randomForestVariable importance ranking
gg_rfsrc()rfsrc / randomForestPredicted vs. observed values
gg_variable()rfsrc / randomForestMarginal dependence data frame

Partial dependence

FunctionInputWhat you get
gg_partial()plot.variable outputPartial dependence (continuous + categorical)
gg_partial_rfsrc()rfsrc modelPartial dependence via partial.rfsrc
surv_partial.rfsrc()rfsrc survival forestSurvival partial dependence, one or more predictors
quantile_pts()numeric vectorQuantile cut points for coplot panels

Survival

FunctionInputWhat you get
gg_survival()rfsrc survival forest, or a data frameKaplan–Meier / Nelson–Aalen estimates
gg_brier()rfsrc (survival)Time-resolved Brier score and CRPS
kaplan()data frame + interval/censor columnsNonparametric Kaplan–Meier estimate
nelson()data frame + interval/censor columnsNonparametric Nelson–Aalen estimate

Classification and ROC

FunctionInputWhat you get
gg_roc()rfsrc / randomForest (class)ROC curve data
calc_roc()rfsrc / randomForest (class)The sensitivity/specificity sweep behind gg_roc()
calc_auc()gg_roc objectArea under the curve

Random Hazard Forests

For time-to-event data with predictors that change during follow-up, these read an rhf fit or a saved tree-size tuning object. A hazard is the event-risk rate at a particular time.

FunctionInputWhat you get
gg_rhf()rhf fitCase-specific hazard or cumulative-hazard curves
gg_auct()rhf fitTime-varying AUC curve for event-risk discrimination
gg_rhf_importance()rhf fitVariable-priority matrix across time windows
gg_tune_rhf()tune.treesize.rhf objectInspected tree-size tuning path

varPro (variable priority)

These read a varpro fit rather than a forest. varPro::varpro() is the supervised fit; varPro::uvarpro() is the unsupervised one, which needs no outcome.

FunctionInputWhat you get
gg_varpro()varpro fitRelease-rule variable importance
gg_beta_varpro()varpro fitPer-variable lasso-beta importance
gg_ivarpro()varpro fitIndividual (local) variable importance
gg_partial_varpro()varpro fitPartial dependence (alias: gg_partialpro())
gg_isopro()isopro fitIsolation-forest anomaly scores
gg_udependent()uvarpro fitVariable dependency graph
gg_beta_uvarpro()uvarpro fitPer-variable lasso-beta importance
gg_sdependent()uvarpro fitSignal-variable detection
varpro_feature_names()character vectorOriginal names behind one-hot encoded features
varpro_coverage()varpro fitShare of trees that tested each variable, next to its z

SHAP

FunctionInputWhat you get
gg_shap()rfsrc / randomForestShapley additive explanation values
shap_importance()gg_shap objectGlobal importance bar chart
shap_beeswarm()gg_shap objectBeeswarm summary plot
shap_dependence()gg_shap objectDependence plot for one predictor

Each gg_* function has a matching plot() S3 method that hands back a single plottable object: a ggplot you extend with +, or a patchwork composite for the multi-panel methods. Every gg_* object also has print() and summary() methods: print() shows a short header at the REPL rather than dumping every row (use head() when you want the rows), and summary() gives you a diagnostics object you can print or keep.

Why ggRandomForests?

The package is built on one decision: keep the data step and the figure step apart. The gg_* functions pull a tidy data object out of the forest; the plot() methods turn that object into a ggplot2 figure. Two things follow from that split.

First, 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.

Second, you are never locked into the default figure. Because a plot() method returns a single plottable object (a ggplot, or a patchwork composite for the multi-panel methods), you can add layers, swap scales, or apply a theme; and if the default is not what you want, you can ignore it entirely and build the figure from the tidy data yourself.

Recent changes

See NEWS.md for the full changelog. Recent highlights:

  • v4.0.0 (development) Random Hazard Forests: gg_rhf() for case-specific event-risk curves, gg_auct() for time-varying discrimination, gg_rhf_importance() for variable priority across time windows, and gg_tune_rhf() for inspecting a saved tree-size tuning path.
  • v3.5.1 gg_roc() on an rfsrc forest now honors the documented which_outcome = 0, which had been returning an unusable two-row object; gg_partial_rfsrc() rejects a non-forest with a real error instead of "argument is of length zero". Also a test-only fix for the gcc-UBSAN report filed against 3.5.0.
  • v3.5.0 varPro fixes: plot.gg_varpro() no longer draws a phantom "NA" category, gg_partial_varpro() warns when you name a variable the fit cannot reach, and scale = "chf" now honors xvar.names instead of computing every variable. Vignette figures render with ragg, which cut the source tarball from 4.7 MB to 2.3 MB.
  • v3.4.0 Unsupervised varPro wrappers (gg_beta_uvarpro(), gg_sdependent()) with their own vignette; gg_partial_rfsrc() now handles factor predictors correctly.
  • v3.3.0 varPro partial plots default to interpretable scales: probability for classification, survival S(τ) for survival.
  • v3.1.0 varPro integration: release-rule importance, partial dependence, local importance, anomaly scores, and the dependency graph.

References

Breiman, L. (2001). Random forests, Machine Learning, 45:5–32.

Ishwaran H. and Kogalur U.B. (2026). Fast Unified Random Forests for Survival, Regression, and Classification (RF-SRC). R package version 3.6.2. 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.

Lu M. and Ishwaran H. (2024). Model-independent variable selection via the rule-based variable priority framework. arXiv preprint arXiv:2409.09003. https://arxiv.org/abs/2409.09003

Ishwaran H. and Kogalur U.B. (2026). Model-Independent Variable Selection via the Rule-Based Variable Priority. R package version 3.2.0. https://cran.r-project.org/package=varPro

Ishwaran H., Hsich E.M., Kogalur U.B. and Lee D.K.K. (2026). Random Hazard Forests. arXiv preprint arXiv:2608.21597. https://doi.org/10.48550/arXiv.2608.21597

Ishwaran H. and Kogalur U.B. (2026). randomForestRHF: Random Hazard Forests. R package version 2.0.0. https://cran.r-project.org/package=randomForestRHF

Liaw A. and Wiener M. (2002). Classification and Regression by randomForest. R News 2(3), 18–22.

Wickham H. (2009). ggplot2: Elegant Graphics for Data Analysis. Springer New York.

Copy Link

Version

Install

install.packages('ggRandomForests')

Monthly Downloads

959

Version

4.0.0

License

MIT + file LICENSE

Issues

Pull Requests

Stars

Forks

Maintainer

John Ehrlinger

Last Published

November 3rd, 2026

Functions in ggRandomForests (4.0.0)

.varpro_cut_layer

The dashed selection line: the cutoff, or the noise bar
.varpro_noise_caption

Caption line naming the noise bar for each kind
.varpro_coverage_extract

One release-rule extraction, scored as importance() scores it
.varpro_coverage_map

Original variable of each encoded term, from varPro's stored map
.varpro_noise_annotator

Check noise and build the step that judges $imp against it
gg_brier

Brier score and CRPS for survival forests
.varpro_noise_judge

Judge each row against tested noise of its own kind
.varpro_coverage_guard

Stop when too many real variables went untested
.varpro_noise_warn

Warn when the noise check is empty or borrows another kind's bar
.varpro_coverage_imp

Unconditional importance table from importance(), whatever the family
gg_beta_uvarpro

Per-variable lasso-beta importance from an unsupervised varPro fit
gg_auct

Tidy time-varying AUC from a Random Hazard Forest
ggRandomForests-package

ggRandomForests: Visually Exploring Random Forests
gg_ale_rfsrc

Accumulated Local Effects (ALE) data from an rfsrc model
gg_partial

Split partial dependence data into continuous or categorical datasets
gg_ivarpro

Individual (local) variable importance from a varPro fit
gg_rhf

Tidy hazard and cumulative-hazard curves from a Random Hazard Forest
gg_rfsrc.rfsrc

Predicted response data object
gg_isopro

Tidy data from a varPro isolation-forest fit
gg_error

Random forest error trajectory data object
.varpro_score_rules

Re-extract release rules and score them as importance() does
gg_partial_varpro

Partial dependence data from a varPro model
gg_partial_rfsrc

Partial dependence data from an rfsrc model
.varpro_sel_rule

How a gg_varpro selection was made, for print() and summary()
gg_roc.rfsrc

ROC (Receiver Operating Characteristic) curve data from a classification forest.
gg_variable

Marginal variable dependence data object.
gg_udependent

Variable dependency graph from a uvarpro model
gg_rhf_importance

Tidy time-localized variable priority from a Random Hazard Forest
gg_survival

Nonparametric survival estimates.
gg_tune_rhf

Tidy a Random Hazard Forest tuning path
ggrandomforests.news

Display the ggRandomForests NEWS file
kaplan

nonparametric Kaplan-Meier estimates
gg_sdependent

Signal-variable detection from an unsupervised varPro fit
gg_shap

SHAP (Shapley additive explanations) data object
plot.gg_brier

Plot a gg_brier object
plot.gg_error

Plot a gg_error object
plot.gg_ale_interaction

Plot a gg_ale_rfsrc interaction object
nelson

nonparametric Nelson-Aalen estimates
gg_varpro

Variable importance data from a varPro model
gg_vimp

Variable Importance (VIMP) data object
plot.gg_auct

Plot a time-varying AUC curve
plot.gg_ale_rfsrc

Plot a gg_ale_rfsrc object
plot.gg_ivarpro

Plot a gg_ivarpro object
plot.gg_rhf

Plot Random Hazard Forest hazard / cumulative-hazard curves
plot.gg_partial

Plot a gg_partial object
plot.gg_isopro

Plot a varPro isolation-forest anomaly score
plot.gg_beta_varpro

Plot a gg_beta_varpro object
plot.gg_roc

ROC plot generic function for a gg_roc object.
plot.gg_beta_uvarpro

Plot a gg_beta_uvarpro object
plot.gg_partial_varpro

Plot a gg_partial_varpro object
plot.gg_sdependent

Plot a gg_sdependent object
plot.gg_partial_rfsrc

Plot a gg_partial_rfsrc object
shap_importance

SHAP global importance bar chart
shap_dependence

SHAP dependence plot
plot.gg_rhf_importance

Plot Random Hazard Forest variable priority over time
plot.gg_shap

Plot a gg_shap object
print.gg_beta_uvarpro

Print methods for gg_* data objects
plot.gg_vimp

Plot a gg_vimp object, extracted variable importance of a rfsrc object
plot.gg_survival

Plot a gg_survival object.
quantile_pts

Quantile-based cut points for coplots
shap_beeswarm

SHAP beeswarm summary plot
summary.gg_beta_uvarpro

Summary methods for gg_* data objects
surv_partial.rfsrc

Survival partial dependence data for one or more predictors
plot.gg_varpro

Plot a gg_varpro variable importance object
plot.gg_variable

Plot a gg_variable object,
plot.gg_rfsrc

Predicted response plot from a gg_rfsrc object.
varpro_feature_names

Recover original variable names from varpro one-hot encoded feature names
varpro_coverage

How well a varpro fit tested each variable
plot.gg_tune_rhf

Plot a Random Hazard Forest tuning path
plot.gg_udependent

Plot a gg_udependent variable dependency graph
.varpro_coverage_check_max

Validate max_untested before the rules are extracted
calc_auc

Area Under the ROC Curve calculator
autoplot.gg

autoplot methods for ggRandomForests data objects
calc_roc.rfsrc

Receiver Operator Characteristic calculator
.varpro_imp_coverage

Share of scored trees with a usable release rule, per variable
.varpro_imp_stats

Compute per-variable box statistics from a per-tree importance matrix
.varpro_coverage_cut_ref

Kind of the noise that set each row's bar: its own, or the fallback's
.varpro_coverage_cut

Largest tested-noise z of the same kind; falls back to all tested noise
.build_varpro_imp_tree

Build per-tree importance matrix from varpro object results
.build_varpro_imp_dfs

Build the tidy importance data structures from importance() output
bootstrap_survival

Bootstrap pointwise confidence bands for a mean survival curve
gg_beta_varpro

Per-variable lasso-beta importance from a varPro fit
.varpro_coverage_kind

Categorical or continuous, per original variable
.varpro_coverage_term_ok

Which terms were scored often enough to be tested