Repository files navigation

Copyright 2016Dean Attali. Licensed underthe MIT license.

ggExtra is a collection of functions and layers to enhance ggplot2.The flagship function isggMarginal, which can be used to add marginalhistograms/boxplots/density plots to ggplot2 scatterplots. You can viewalive interactivedemo to test itout!

Most other functions/layers are quite simple but are useful because theyare fairly common ggplot2 operations that are a bit verbose.

This is an instructional document, but I also wrotea blogpost about thereasoning behind and development of this package.

Note: it was brought to my attention that several years ago there was adifferent package calledggExtra, by Baptiste (the author ofgridExtra). That oldggExtra package was deleted in 2011 (two yearsbefore I even knew what R is!), and this package has nothing to do withthe old one.

ggExtra is available through both CRAN and GitHub.

To install the CRAN version:

install.packages("ggExtra")

To install the latest development version from GitHub:

install.packages("devtools")devtools::install_github("daattali/ggExtra")

ggExtra comes with an addin forggMarginal(), which lets youinteractively add marginal plots to a scatter plot. To use it, simplyhighlight the code for a ggplot2 plot in your script, and selectggplot2 Marginal Plots from the RStudioAddins menu. Alternatively,you can call the addin directly by callingggMarginalGadget(plot) witha ggplot2 plot.

We’ll first load the package and ggplot2, and then see how all thefunctions work.

library("ggExtra")library("ggplot2")

ggMarginal() is an easy drop-in solution for adding marginal densityplots/histograms/boxplots to a ggplot2 scatterplot. The easiest way touse it is by simply passing it a ggplot2 scatter plot, andggMarginal() will add the marginal plots.

As a simple first example, let’s create a dataset with 500 points wherethe x values are normally distributed and the y values are uniformlydistributed, and plot a simple ggplot2 scatterplot.

set.seed(30)df1 <- data.frame(x = rnorm(500, 50, 10), y = runif(500, 0, 50))p1 <- ggplot(df1, aes(x, y)) + geom_point() + theme_bw()p1

And now to add marginal density plots:

ggMarginal(p1)

That was easy. Notice how the syntax does not follow the standardggplot2 syntax -you don’t “add” a ggMarginal layer withp1 + ggMarginal(), but rather ggMarginal takes the object as anargument and returns a different object. This means that you can usemagrittr pipes, for examplep1 %>% ggMarginal().

Let’s make the text a bit larger to make it easier to see.

ggMarginal(p1 + theme_bw(30) + ylab("Two\nlines"))

Notice how the marginal plots occupy the correct space; even when themain plot’s points are pushed to the right because of larger text orlonger axis labels, the marginal plots automatically adjust.

If your scatterplot has a factor variable mapping to a colour (ie.points in the scatterplot are colour-coded according to a variable inthe data, by usingaes(colour = ...)), then you can usegroupColour = TRUE and/orgroupFill = TRUE to reflect thesegroupings in the marginal plots. The result is multiple marginal plots,one for each colour group of points. Here’s an example using the irisdataset.

piris <- ggplot(iris, aes(Sepal.Length, Sepal.Width, colour = Species)) +  geom_point()ggMarginal(piris, groupColour = TRUE, groupFill = TRUE)

You can also show histograms instead.

ggMarginal(p1, type = "histogram")

There are several more parameters, here is an example with a few morebeing used. Note that you can use any parameters that thegeom_XXX()layers accept, such ascol andfill, and they will be passed tothese layers.

ggMarginal(p1, margins = "x", size = 2, type = "histogram",           col = "blue", fill = "orange")

In the above example,size = 2 means that the main scatterplot shouldoccupy twice as much height/width as the margin plots (default is 5).Thecol andfill parameters are simply passed to the ggplot layerfor both margin plots.

If you want to specify some parameter for only one of the marginalplots, you can use thexparams oryparams parameters, like this:

ggMarginal(p1, type = "histogram", xparams = list(binwidth = 1, fill = "orange"))

Last but not least - you can also save the output fromggMarginal()and display it later. (This may sound trivial, but it was not an easyproblem to solve -see thisdiscussion).

p <- ggMarginal(p1)p

You can also create marginal box plots and violin plots. For moreinformation, see?ggExtra::ggMarginal.

If you try including aggMarginal() plot inside an R Notebook orRmarkdown code chunk, you’ll notice that the plot doesn’t get output. Inorder to get aggMarginal() to show up in an these contexts, you needto save the ggMarginal plot as a variable in one code chunk, andexplicitly print it using thegrid package in another chunk, likethis:

```{r}library(ggplot2)library(ggExtra)p <- ggplot(mtcars, aes(wt, mpg)) + geom_point()p <- ggMarginal(p)``````{r}grid::grid.newpage()grid::grid.draw(p)```

This is just a convenience function to save a bit of typing andmemorization. Minor grid lines are always removed, and the major x or ygrid lines can be removed as well (default is to remove both).

removeGridX is a shortcut forremoveGrid(x = TRUE, y = FALSE), andremoveGridY is similarly a shortcut for….

df2 <- data.frame(x = 1:50, y = 1:50)p2 <- ggplot2::ggplot(df2, ggplot2::aes(x, y)) + ggplot2::geom_point()p2 + removeGrid()

For more information, see?ggExtra::removeGrid.

Often times it is useful to rotate the x axis labels to be vertical ifthere are too many labels and they overlap. This function accomplishesthat and ensures the labels are horizontally centered relative to thetick line.

df3 <- data.frame(x = paste("Letter", LETTERS, sep = "_"),                  y = seq_along(LETTERS))p3 <- ggplot2::ggplot(df3, ggplot2::aes(x, y)) + ggplot2::geom_point()p3 + rotateTextX()

For more information, see?ggExtra::rotateTextX.

This is a convenience function to quickly plot a bar plot of count(frequency) data. The input must be either a frequency table (obtainedwithbase::table) or a data.frame with 2 columns where the firstcolumn contains the values and the second column contains the counts.

An example using a table:

plotCount(table(infert$education))

An example using a data.frame:

df4 <- data.frame("vehicle" = c("bicycle", "car", "unicycle", "Boeing747"),                  "NumWheels" = c(2, 4, 1, 16))plotCount(df4) + removeGridX()

For more information, see?ggExtra::plotCount.

Visual tests (comparing plot output against expected snapshots) are essential for ensuringggMarginal() produces correct plots. However, these tests are very sensitive to operating system and environment differences, which can cause test failures even when plots seem to be visually identical. To solve this, we use Docker containers to provide a reproducible testing environment with pinned package versions.

When tests are run outside of Docker, the visual tests will be skipped by default unless you set theRunVisualTests environment variable to"yes". To run the visual tests, first build a Docker container and then run it:

docker build -t ggextra-test --build-arg GGPLOT2_VERSION=3.5.0 .docker run --rm ggextra-test

If you want to run the tests against the latest version of {ggplot2}, simply omit the build argument from thedocker build command.

When adding newggMarginal() tests (intests/testthat/helper-funs.R), you'll need to first generate the expected plots because there is nothing to test against yet. Use the samedocker build command, but add an argument to therun command that will mount the container's folder onto your file system:

docker run --rm -v "$(pwd):/pkg" ggextra-test

Now the new snapshots will be created in your computer and you can review them to make sure they look correct. If you're happy with them, you can commit them to GitHub, and any further tests will use these images as the expectation.

On GitHub, the visual tests are run against a few {ggplot2} versions that are defined inthe GitHub Action workflow.