README

Package ‘gginnards’ (Explore the innards of ‘ggplot2’) is a set of extensions to R package ‘ggplot2’. Two geometries and two statistics are specially useful when learning how to write ‘ggplot2’ extensions and when debugging newly defined statistics and geometries.

Objects of class "gg", or unrendered ggplot objects, are a list-like structure containing data and “instructions” to construct a plot and its layers. By editing this structure it is possible to modify the plot that will be rendered. Functions are provided for the manipulation of layers within ggobjects. These can be useful in the case extensions to ‘ggplot2’ that define functions that construct and return whole gg objects. In such cases in can be useful to programatically edit these gg objects to insert plot layers or change their order.

As the variables returned in data by many statistics depend on input, some of these tools can be also useful in everyday plotting with ‘gplot2’ as a way of diagnosing problems or getting information that is missing from their documentation or only available at runtime.

Stability

Because of its nature, this package does not always play safe and nice even if it tries to. No exported or internal function or object should be imported or used in other packages, simply because they may change at any time (as in version 0.2.0). Although I intend to maintain the package, I will not attempt to actively keep it compatible with anything but the current version of ‘ggplot2’, although it will frequently also work with some earlier versions. Please, see the blog post Playing on the same team as your dependecy by Thomas Lin Pedersen.

Alternatives

The debug statistics and geoms are defined in ‘gginnards’ using the same approach as other ‘ggplot2’ extensions, without any significant assumptions about the internals of ‘ggplot2’. Thus, they are unlikely to be affected by minor updates to ‘ggplot2’. The layer manipulation functions rely on the internal structure of "gg" objects, but mostly on aspects unlikely to change frequently.

Package ‘gginnards’ does not provide a deep view into the structure of "gg" objects or the steps involved in building these objects and rendering them into graphical objects. Package ‘ggtrace’ by June Choe provides tools for a much deeper and detailed exploration and edition of ggplots, but it is much more dependent on the undocumented internals of ‘ggplot2’ than ‘gginnards’. (Note: there exists another package named ggtrace for a different purpose. None of them are yet available through CRAN.)

History

This package was born when several functions were extracted from package ‘ggpmisc’ and packaged on their own.

Geometries

Geometries geom_debug_panel() and geom_debug_droup() by default print the data object received as input by the draw functi to the console adding a plot layer that produces no graphic output. As they take as arguments summary functions, they allows flexibility in how data objects are displayed. geom_debug_panel() and geom_debug_droup() are useful at any time when one needs to check what variables are returned by statistics. Many statistics are well documented and always return the same variables. For other statistics even if well documented the returned variables in data vary depending on grouping and/or the arguments passed to them, in which case this geometry can also be useful when debugging scripts.

Statistics

Statistics stat_debug_panel() and stat_debug_droup() echo their data input to the R console aim at easing debugging during development of new geoms and statistics. They will also help those learning how ggplot grouping, panels and layers work. As the debug geometries, they take as arguments summary functions allowing flexibility in how data objects are displayed.

For debugging, the value returned by these stats is usually not interesting, and by default, it is a copy of the data object received as input. This can be changed by passing a function as argument to fun.data. This could be useful to produce data summaries to be plotted as a layer. This may even work as a tool useful to build ad-hoc statistics with rudimentary built-in debugging.

Manipulation of layers

A set of functions easy the manipulation of layers in ggplot objects, allowing deletion of any existing layer, insertion of new layers at any position, and reordering of the existing layers.

Manipulation of embedded data

A function to drop unused variables from the data object embedded in gg and ggplot objects serves as an additional example of a manipulation that may be useful when dealing with very large datasets. Companion functions are defined to explore the embedded data object.

Examples

library(gginnards)
#> Loading required package: ggplot2

We print to the R console data as seen as input by geometries and statistics.

ggplot(mtcars, aes(cyl, mpg, color = mpg)) +
  geom_point() +
  geom_debug_panel()

ggplot(mtcars, aes(cyl, mpg, color = mpg)) +
  geom_point() +
  geom_debug_panel(dbgfun.data = colnames, dbgfun.params = NULL)

We print to the R console data as returned by stat_summary() and seen as input by geometries.

ggplot(mtcars, aes(cyl, mpg, colour = factor(cyl))) +
  stat_summary(fun.data = "mean_cl_boot") +
  stat_summary(fun.data = "mean_cl_boot", geom = "debug_panel")

We print to the R console data as seen as input by statistics that use a panel function.

ggplot(mtcars, aes(cyl, mpg, colour = factor(cyl))) +
  stat_debug_panel()

We build object p of class gg (a ggplot). We query the number of layers and the position of layers by the class of the ggproto object.

p <-
  ggplot(mtcars, aes(cyl, mpg)) +
  geom_point(size = 3) +
  stat_summary(fun.data = "mean_cl_boot", color = "red", size = 2)

  num_layers(p)
#> [1] 2
  which_layers(p, "GeomPoint")
#> geom_point 
#>          1
  which_layers(p, "StatSummary")
#> stat_summary 
#>            2

  p

  move_layers(p, "GeomPoint", position = "top")

Installation

Installation of the most recent stable version from CRAN (sources, Mac and Win binaries):

install.packages("gginnards")

Installation of the current unstable version from R-Universe CRAN-like repository (binaries for Mac, Win, Webassembly, and Linux, as well as sources available):

install.packages('gginnards', 
                 repos = c('https://aphalo.r-universe.dev', 
                           'https://cloud.r-project.org'))

# install.packages("devtools")
devtools::install_github("aphalo/gginnards")

Documentation

Contributing

Citation

If you use this package to produce scientific or commercial publications, please cite according to:

citation("gginnards")
#> To cite package 'gginnards' in publications use:
#> 
#>   Aphalo P (2024). _gginnards: Explore the Innards of 'ggplot2'
#>   Objects_. R package version 0.2.0,
#>   <https://CRAN.R-project.org/package=gginnards>.
#> 
#> A BibTeX entry for LaTeX users is
#> 
#>   @Manual{,
#>     title = {gginnards: Explore the Innards of 'ggplot2' Objects},
#>     author = {Pedro J. Aphalo},
#>     year = {2024},
#>     note = {R package version 0.2.0},
#>     url = {https://CRAN.R-project.org/package=gginnards},
#>   }

License

gginnards

Purpose