Consolidate plotting into plot(); deprecate plotPartial()

- plot.partial/plot.ice/plot.cice gain a lattice argument; lattice = TRUE
  reuses the existing lattice workhorses (3-predictor panels, wireframe)
  through the single plot() interface, printing the trellis and returning
  it invisibly
- plotPartial() soft-deprecated with a pointer to plot(..., lattice = TRUE);
  internal callers (including partial(plot = TRUE)) bypass the deprecated
  generic so no warning is signaled
- Vignette gains a lattice section with paper-style 3-D and three-predictor
  displays; tests updated and extended (test_plot.R)
- pkgdown workflow now removes AGENTS.md before building the site (pkgdown
  renders every top-level .md file)

Author: bgreenwell

.github/workflows/pkgdown.yaml

@@ -36,6 +36,11 @@ jobs:
           extra-packages: any::pkgdown, local::.
           needs: website
 
+      # pkgdown renders every top-level .md file into a page; AGENTS.md is
+      # agent/contributor tooling and should not be published on the site
+      - name: Exclude agent instructions from the site
+        run: rm -f AGENTS.md
+
       - name: Build site
         run: pkgdown::build_site_github_pages(new_process = FALSE, install = FALSE)
         shell: Rscript {0}

NEWS.md

@@ -1,5 +1,14 @@
 # pdp (development version)
 
+## Deprecations
+
+* `plotPartial()` is deprecated in favor of the consolidated `plot()`
+interface: the `plot()` methods gained a `lattice` argument, so
+`plot(..., lattice = TRUE)` now produces the same lattice-based displays
+(including 3-D wireframe surfaces and paneled three-predictor plots).
+`plotPartial()` continues to work (with a warning) but will be removed in a
+future release.
+
 ## Bug fixes
 
 * Plotting now works for non-syntactic predictor names (e.g., names containing

R/partial.R

@@ -262,22 +262,21 @@
 #' partial(boston.rf, pred.var = c("lstat", "rm"), grid.resolution = 40,
 #'         plot = TRUE, chull = TRUE, progress = TRUE)
 #'
-#' # The plotPartial function offers more flexible plotting
+#' # The plot method produces lightweight base R graphics via the tinyplot
+#' # package by default; set `lattice = TRUE` for lattice graphics (e.g., for
+#' # 3-D surfaces or paneled three-predictor displays)
 #' pd <- partial(boston.rf, pred.var = c("lstat", "rm"), grid.resolution = 40)
-#' plotPartial(pd, levelplot = FALSE, zlab = "cmedv", drape = TRUE,
-#'             colorkey = FALSE, screen = list(z = -20, x = -60))
-#'
-#' # The plot method can be used to produce lightweight base R graphics via
-#' # the tinyplot package
 #' plot(pd, contour = TRUE)
+#' plot(pd, lattice = TRUE, levelplot = FALSE, zlab = "cmedv", drape = TRUE,
+#'      colorkey = FALSE, screen = list(z = -20, x = -60))
 #'
 #' #
 #' # Individual conditional expectation (ICE) curves
 #' #
 #'
 #' # Use partial to obtain ICE/c-ICE curves
 #' rm.ice <- partial(boston.rf, pred.var = "rm", ice = TRUE)
-#' plotPartial(rm.ice, rug = TRUE, train = boston, alpha = 0.2)
+#' plot(rm.ice, rug = TRUE, train = boston, alpha = 0.2)
 #' plot(rm.ice, center = TRUE, alpha = 0.2, rug = TRUE, train = boston)
 #'
 #' #
@@ -546,17 +545,19 @@ partial.default <- function(
       }
       return(invisible(pd.df))
     }
-    # Return a graph (i.e., a "trellis" object)
+    # Return a graph (i.e., a "trellis" object); the methods are called
+    # directly (rather than via the deprecated plotPartial() generic) so no
+    # deprecation warning is signaled
     res <- if (inherits(pd.df, what = c("ice", "cice"))) {
-      plotPartial(
+      plotPartial.ice(
         object = pd.df, plot.pdp = TRUE, rug = rug, train = train,
         alpha = alpha
       )
     } else {
-      plotPartial(pd.df, smooth = smooth, rug = rug, train = train,
-                  levelplot = levelplot, contour = contour,
-                  contour.color = contour.color,
-                  screen = list(z = -30, x = -60))  # sensible default?
+      plotPartial.partial(pd.df, smooth = smooth, rug = rug, train = train,
+                          levelplot = levelplot, contour = contour,
+                          contour.color = contour.color,
+                          screen = list(z = -30, x = -60))  # sensible default?
     }
     attr(res, "partial.data") <- pd.df  # attach PDP data as an attribute
   } else {  # return a data frame (i.e., a "data.frame" and "partial" object)

R/pdp-package.R

@@ -11,8 +11,7 @@
 #' As of right now, \code{pdp} exports the following functions:
 #' \itemize{
 #'   \item{\code{partial}} - construct partial dependence functions (i.e., objects of class \code{"partial"}) from various fitted model objects;
-#'   \item{\code{plotPartial}} - plot partial dependence functions (i.e., objects of class \code{"partial"}) using \code{\link[lattice]{lattice}} graphics;
-#'   \item{\code{plot}} - plot partial dependence functions (i.e., objects of class \code{"partial"}) using lightweight base R graphics via \code{\link[tinyplot]{tinyplot}};
+#'   \item{\code{plot}} - plot partial dependence functions (i.e., objects of class \code{"partial"}) using lightweight base R graphics via \code{\link[tinyplot]{tinyplot}} (or \code{\link[lattice]{lattice}} graphics whenever \code{lattice = TRUE});
 #'   \item{\code{exemplar}} - construct a single "exemplar" record from a data frame.
 #' }
 #' @keywords internal

R/plot.R

@@ -2,7 +2,8 @@
 #'
 #' Plot partial dependence functions (i.e., marginal effects) and individual
 #' conditional expectation (ICE) curves using lightweight base R graphics via
-#' the \href{https://grantmcdermott.com/tinyplot/}{tinyplot} package.
+#' the \href{https://grantmcdermott.com/tinyplot/}{tinyplot} package, or
+#' \code{\link[lattice]{lattice}} graphics whenever \code{lattice = TRUE}.
 #'
 #' @param x An object that inherits from class \code{"partial"}, \code{"ice"},
 #' or \code{"cice"}; typically the result of a call to \code{\link{partial}}.
@@ -62,11 +63,43 @@
 #' title of the false color level plot used for two continuous predictors.
 #' Default is \code{"yhat"}.
 #'
+#' @param lattice Logical indicating whether or not to draw the display using
+#' \code{\link[lattice]{lattice}} graphics instead of tinyplot/base graphics.
+#' The lattice engine additionally supports three-predictor (paneled) displays
+#' and 3-D surfaces; see Details. Default is \code{FALSE}.
+#'
 #' @param ... Additional optional arguments to be passed on to
 #' \code{\link[tinyplot]{tinyplot}} (e.g., \code{palette}, \code{main}, or
-#' \code{theme}).
+#' \code{theme}) or, whenever \code{lattice = TRUE}, to the underlying lattice
+#' display (see Details).
+#'
+#' @details
+#' When \code{lattice = TRUE}, the display is constructed with
+#' \code{\link[lattice]{lattice}} graphics (this subsumes the now-deprecated
+#' \code{plotPartial()} interface). In that case, additional lattice-specific
+#' options can be supplied via \code{...}:
+#' \itemize{
+#'   \item \code{levelplot} - use a false color level plot (\code{TRUE};
+#'   default) or a 3-D \code{\link[lattice]{wireframe}} surface (\code{FALSE})
+#'   for two continuous predictors;
+#'   \item \code{chull} - overlay the convex hull of the first two predictors
+#'   (requires \code{train});
+#'   \item \code{col.regions} - color palette for level/wireframe plots;
+#'   \item \code{number}/\code{overlap} - number of conditioning intervals
+#'   (and their fraction of overlap) used to panel a third (continuous)
+#'   predictor;
+#'   \item any other argument accepted by \code{\link[lattice]{xyplot}},
+#'   \code{\link[lattice]{levelplot}}, \code{\link[lattice]{wireframe}}, or
+#'   \code{\link[lattice]{dotplot}} (e.g., \code{screen} or \code{drape}).
+#' }
+#' The tinyplot-specific arguments \code{color.by}, \code{bars}, and
+#' \code{legend.title} are ignored when \code{lattice = TRUE}.
 #'
-#' @return Draws a plot as a side effect and (invisibly) returns \code{x}.
+#' @return Draws a plot as a side effect. The tinyplot engine (invisibly)
+#' returns \code{x}; the lattice engine (\code{lattice = TRUE}) (invisibly)
+#' returns the \code{"trellis"} object, which can be captured for further
+#' manipulation (e.g., arranging multiple displays with
+#' \code{gridExtra::grid.arrange()}).
 #'
 #' @rdname plot.partial
 #'
@@ -101,7 +134,20 @@ plot.partial <- function(x, center = FALSE, plot.pdp = TRUE, pdp.col = "red2",
                          pdp.lwd = 2, pdp.lty = 1, smooth = FALSE, rug = FALSE,
                          contour = FALSE, contour.color = "white", train = NULL,
                          alpha = 1, color.by = NULL, bars = FALSE,
-                         legend.title = "yhat", ...) {
+                         legend.title = "yhat", lattice = FALSE, ...) {
+
+  # Use lattice graphics instead? Calls the method directly (rather than the
+  # deprecated plotPartial() generic) so no deprecation warning is signaled
+  if (isTRUE(lattice)) {
+    res <- plotPartial.partial(
+      x, center = center, plot.pdp = plot.pdp, pdp.col = pdp.col,
+      pdp.lwd = pdp.lwd, pdp.lty = pdp.lty, smooth = smooth, rug = rug,
+      contour = contour, contour.color = contour.color, train = train,
+      alpha = alpha, ...
+    )
+    print(res)  # draw as a side effect, like the tinyplot engine
+    return(invisible(res))
+  }
 
   # Determine if object contains multiple curves
   multi <- "yhat.id" %in% names(x)
@@ -154,7 +200,16 @@ plot.partial <- function(x, center = FALSE, plot.pdp = TRUE, pdp.col = "red2",
 #' @export
 plot.ice <- function(x, center = FALSE, plot.pdp = TRUE, pdp.col = "red2",
                      pdp.lwd = 2, pdp.lty = 1, rug = FALSE, train = NULL,
-                     alpha = 1, color.by = NULL, ...) {
+                     alpha = 1, color.by = NULL, lattice = FALSE, ...) {
+  if (isTRUE(lattice)) {
+    res <- plotPartial.ice(
+      x, center = center, plot.pdp = plot.pdp, pdp.col = pdp.col,
+      pdp.lwd = pdp.lwd, pdp.lty = pdp.lty, rug = rug, train = train,
+      alpha = alpha, ...
+    )
+    print(res)
+    return(invisible(res))
+  }
   tinyplot_ice_curves(
     object = x, center = center, plot.pdp = plot.pdp, pdp.col = pdp.col,
     pdp.lwd = pdp.lwd, pdp.lty = pdp.lty, rug = rug, train = train,
@@ -169,7 +224,15 @@ plot.ice <- function(x, center = FALSE, plot.pdp = TRUE, pdp.col = "red2",
 #' @export
 plot.cice <- function(x, plot.pdp = TRUE, pdp.col = "red2", pdp.lwd = 2,
                       pdp.lty = 1, rug = FALSE, train = NULL, alpha = 1,
-                      color.by = NULL, ...) {
+                      color.by = NULL, lattice = FALSE, ...) {
+  if (isTRUE(lattice)) {
+    res <- plotPartial.cice(
+      x, plot.pdp = plot.pdp, pdp.col = pdp.col, pdp.lwd = pdp.lwd,
+      pdp.lty = pdp.lty, rug = rug, train = train, alpha = alpha, ...
+    )
+    print(res)
+    return(invisible(res))
+  }
   tinyplot_ice_curves(
     object = x, center = FALSE, plot.pdp = plot.pdp, pdp.col = pdp.col,
     pdp.lwd = pdp.lwd, pdp.lty = pdp.lty, rug = rug, train = train,

R/plotPartial.R

@@ -1,8 +1,13 @@
-#' Plotting Partial Dependence Functions
+#' Plotting Partial Dependence Functions (deprecated)
 #'
 #' Plots partial dependence functions (i.e., marginal effects) using
 #' \code{\link[lattice]{lattice}} graphics.
 #'
+#' \strong{Deprecated:} \code{plotPartial()} is deprecated and will be removed
+#' in a future release; please use \code{plot(..., lattice = TRUE)} instead,
+#' which produces the same displays through a single interface (see
+#' \code{\link{plot.partial}} for details).
+#'
 #' @param object An object that inherits from the \code{"partial"} class.
 #'
 #' @param center Logical indicating whether or not to produce centered ICE
@@ -104,6 +109,11 @@
 #' grid.arrange(p1, p2, ncol = 2)
 #' }
 plotPartial <- function(object, ...) {
+  .Deprecated(
+    msg = paste("pdp::plotPartial() is deprecated and will be removed in a",
+                "future release. Please use plot(..., lattice = TRUE)",
+                "instead; see ?pdp::plot.partial for details.")
+  )
   UseMethod("plotPartial")
 }
 

inst/tinytest/test_issues.R

@@ -16,15 +16,15 @@ pd113 <- partial(fit113, pred.var = "x-var", train = d113,
                  grid.resolution = 5)
 expect_inherits(pd113, "partial")
 pdf(NULL)
-expect_inherits(plotPartial(pd113), "trellis")
+expect_inherits(plot(pd113, lattice = TRUE), "trellis")
 expect_inherits(plot(pd113), "partial")  # tinyplot engine
 pd113.2 <- partial(fit113, pred.var = c("x-var", "x 2"), train = d113,
                    grid.resolution = 5)
-expect_inherits(plotPartial(pd113.2), "trellis")
+expect_inherits(plot(pd113.2, lattice = TRUE), "trellis")
 expect_inherits(plot(pd113.2), "partial")
 ice113 <- partial(fit113, pred.var = "x-var", train = d113, ice = TRUE,
                   grid.resolution = 5)
-expect_inherits(plotPartial(ice113), "trellis")
+expect_inherits(plot(ice113, lattice = TRUE), "trellis")
 expect_inherits(plot(ice113), "ice")
 invisible(dev.off())
 
@@ -50,7 +50,8 @@ pd.multi <- partial(fit, pred.var = c("x1", "x2"), pred.fun = pfun, train = d,
                     grid.resolution = 3)
 expect_inherits(pd.multi, "ice")
 pdf(NULL)
-expect_error(plotPartial(pd.multi), pattern = "multiple\\s+.?predictors")
+expect_error(plot(pd.multi, lattice = TRUE),
+             pattern = "multiple\\s+.?predictors")
 expect_error(plot(pd.multi), pattern = "multiple\\s+.?predictors")
 invisible(dev.off())
 

inst/tinytest/test_pkg_MASS.R

@@ -39,10 +39,10 @@ if (require(MASS, quietly = TRUE)) {
 
   # Display plots in a grid
   grid.arrange(
-    plotPartial(pd_lda),
-    plotPartial(pd_lda_prob),
-    plotPartial(ice_lda),
-    plotPartial(ice_lda_prob),
+    plot(pd_lda, lattice = TRUE),
+    plot(pd_lda_prob, lattice = TRUE),
+    plot(ice_lda, lattice = TRUE),
+    plot(ice_lda_prob, lattice = TRUE),
     nrow = 2
   )
 
@@ -68,10 +68,10 @@ if (require(MASS, quietly = TRUE)) {
 
   # Display plots in a grid
   grid.arrange(
-    plotPartial(pd_qda),
-    plotPartial(pd_qda_prob),
-    plotPartial(ice_qda),
-    plotPartial(ice_qda_prob),
+    plot(pd_qda, lattice = TRUE),
+    plot(pd_qda_prob, lattice = TRUE),
+    plot(ice_qda, lattice = TRUE),
+    plot(ice_qda_prob, lattice = TRUE),
     nrow = 2
   )
 

inst/tinytest/test_pkg_party.R

@@ -37,12 +37,12 @@ if (require(party, quietly = TRUE)) {
 
   # Display plots in a grid
   grid.arrange(
-    plotPartial(pd1),
-    plotPartial(pd2),
-    plotPartial(pd2_prob),
-    plotPartial(ice1),
-    plotPartial(ice2),
-    plotPartial(ice2_prob),
+    plot(pd1, lattice = TRUE),
+    plot(pd2, lattice = TRUE),
+    plot(pd2_prob, lattice = TRUE),
+    plot(ice1, lattice = TRUE),
+    plot(ice2, lattice = TRUE),
+    plot(ice2_prob, lattice = TRUE),
     nrow = 2
   )
 
@@ -73,12 +73,12 @@ if (require(party, quietly = TRUE)) {
 
   # Display plots in a grid
   grid.arrange(
-    plotPartial(pd3),
-    plotPartial(pd4),
-    plotPartial(pd4_prob),
-    plotPartial(ice3),
-    plotPartial(ice4),
-    plotPartial(ice4_prob),
+    plot(pd3, lattice = TRUE),
+    plot(pd4, lattice = TRUE),
+    plot(pd4_prob, lattice = TRUE),
+    plot(ice3, lattice = TRUE),
+    plot(ice4, lattice = TRUE),
+    plot(ice4_prob, lattice = TRUE),
     nrow = 2
   )
 

inst/tinytest/test_pkg_stats.R

@@ -35,10 +35,10 @@ if (require(party, quietly = TRUE)) {
 
   # Display plots in a grid
   grid.arrange(
-    plotPartial(pd1_lm),
-    plotPartial(pd1_glm),
-    plotPartial(ice1_lm),
-    plotPartial(ice1_glm),
+    plot(pd1_lm, lattice = TRUE),
+    plot(pd1_glm, lattice = TRUE),
+    plot(ice1_lm, lattice = TRUE),
+    plot(ice1_glm, lattice = TRUE),
     nrow = 2
   )
 
@@ -65,10 +65,10 @@ if (require(party, quietly = TRUE)) {
 
   # Display plots in a grid
   grid.arrange(
-    plotPartial(pd2_glm),
-    plotPartial(pd2_glm_prob),
-    plotPartial(ice2_glm),
-    plotPartial(ice2_glm_prob),
+    plot(pd2_glm, lattice = TRUE),
+    plot(pd2_glm_prob, lattice = TRUE),
+    plot(ice2_glm, lattice = TRUE),
+    plot(ice2_glm_prob, lattice = TRUE),
     nrow = 2
   )