Using ggplot2 to visualize an object

ggplot2 is commonly used in packages to visualize objects (e.g., in aplot()-style function). For example, a package might define an S3 class that represents the probability of various discrete values:

mpg_drv_dist<-structure(c("4"=103/234,"f"=106/234,"r"=25/234),  class="discrete_distr")

Many S3 classes in R have aplot() method, but it is unrealistic to expect that a singleplot() method can provide the visualization every one of your users is looking for. It is useful, however, to provide aplot() method as a visual summary that users can call to understand the essence of an object. To satisfy all your users, we suggest writing a function that transforms the object into a data frame (or alist() of data frames if your object is more complicated). A good example of this approach isggdendro, which creates dendrograms using ggplot2 but also computes the data necessary for users to make their own. For the above example, the function might look like this:

discrete_distr_data<-function(x){tibble::tibble(    value=names(x),    probability=as.numeric(x))}discrete_distr_data(mpg_drv_dist)#> # A tibble: 3 × 2#>   value probability#>   <chr>       <dbl>#> 1 4           0.440#> 2 f           0.453#> 3 r           0.107

In general, users ofplot() call it for its side-effects: it results in a graphic being displayed. This is different than the behaviour of aggplot(), which is not displayed unless it is explicitlyprint()ed. Because of this, ggplot2 defines its own genericautoplot(), a call to which is expected to return aggplot() (with no side effects).

#' @importFrom ggplot2 autoplotautoplot.discrete_distr<-function(object,...){plot_data<-discrete_distr_data(object)ggplot(plot_data,aes(.data$value,.data$probability))+geom_col()+coord_flip()+labs(x="Value", y="Probability")}

Once anautoplot() method has been defined, aplot() method can then consist ofprint()ing the result ofautoplot():

#' @importFrom graphics plotplot.discrete_distr<-function(x,...){print(autoplot(x,...))}

It is considered bad practice to implement an S3 generic likeplot(), orautoplot() if you don’t own the S3 class, as it makes it hard for the package developer who does have control over the S3 to implement the method themselves. This shouldn’t stop you from creating your own functions to visualize these objects!

Creating a new theme

When creating a new theme, it’s always good practice to start with an existing theme (e.g. theme_grey()) and then%+replace% the elements that should be changed. This is the right strategy even if seemingly all elements are replaced, as not doing so makes it difficult for us to improve themes by adding new elements. There are many excellent examples of themes in theggthemes package.

#' @importFrom ggplot2 %+replace%theme_custom<-function(...){theme_grey(...)%+replace%theme(      panel.border=element_rect(linewidth=1, fill=NA),      panel.background=element_blank(),      panel.grid=element_line(colour="grey80"))}mpg_drv_summary()+theme_custom()

It is important that the theme be calculated after the package is loaded. If not, a theme object —stored as a variable in the built package— may or may not align with the installed version of ggplot2! If your package has a default theme for its visualizations, the correct way to apply this theme is by calling the constructor:

mpg_drv_summary2<-function(){mpg_drv_summary()+theme_custom()}

Testing ggplot2 output

We suggest testing the output of ggplot2 in using thevdiffr package, which is a tool to manage visual test cases (this is one of the ways we test ggplot2). If changes in ggplot2 or your code introduce a change in the visual output of a ggplot, tests will fail when you run them locally or as part of a Continuous Integration setup. To use vdiffr, make sure you are usingtestthat (you can useusethis::use_testthat() to get started) and add vdiffr toSuggests in yourDESCRIPTION. Then, usevdiffr::expect_doppleganger(<name of plot>, <ggplot object>) to make a test that fails if there are visual changes in<ggplot object>. However, you should consider whether visual testing is the best strategy because it adds a dependency on how ggplot2 performs its rendering which may change between versions. If extracting the layer data usingget_layer_data() and testing the values directly is possible it is far better as it more directly test the behaviour of your own code.

test_that("output of ggplot() is stable",{vdiffr::expect_doppelganger("A blank plot",ggplot())})

ggplot2 inSuggests

If you use ggplot2 in your package, most likely you will want to list it underImports. If you would like to list ggplot2 inSuggests instead, you will not be able to#' @importFrom ggplot2 ... (i.e., you must refer to ggplot2 objects using::). If you use infix operators from ggplot2 like%+replace% and you want to keep ggplot2 inSuggests, you can assign the operator within the function before it is used:

theme_custom<-function(...){`%+replace%`<-ggplot2::`%+replace%`ggplot2::theme_grey(...)%+replace%ggplot2::theme(panel.background=ggplot2::element_blank())}

Generally, if you add a method for a ggplot2 generic likeautoplot(), ggplot2 should be inImports. If for some reason you would like to keep ggplot2 inSuggests, it is possible to register your generics only if ggplot2 is installed usingvctrs::s3_register(). If you do this, you should copy and paste the source ofvctrs::s3_register() into your own package to avoid adding avctrs dependency.

.onLoad<-function(...){if(requireNamespace("ggplot2", quietly=TRUE)){vctrs::s3_register("ggplot2::autoplot","discrete_distr")}}