Skip to contents
library(GGally)
#> Loading required package: ggplot2

GGally::ggmatrix()

ggmatrix() is a function for managing multiple plots in a matrix-like layout. It was designed to adapt to any number of columns and rows. This allows for very customized plot matrices.

Generic Example

The examples below use plots labeled 1 to 6 to distinguish where the plots are being placed.

plotList <- list()
for (i in 1:6) {
  plotList[[i]] <- ggally_text(paste("Plot #", i, sep = ""))
}

# bare minimum of plotList, nrow, and ncol
pm <- ggmatrix(plotList, 2, 3)
pm

Two-by-three plot matrix of text panels labelled Plot #1 to Plot #6, filled row by row, with no axis labels or title.


# provide more information
pm <- ggmatrix(
  plotList,
  nrow = 2, ncol = 3,
  xAxisLabels = c("A", "B", "C"),
  yAxisLabels = c("D", "E"),
  title = "Matrix Title"
)
pm

Two-by-three plot matrix titled Matrix Title with column labels A, B, C and row labels D, E. Text panels Plot #1 to Plot #6 are filled row by row, so the top row reads 1, 2, 3.


# display plots in column order
pm <- ggmatrix(
  plotList,
  nrow = 2, ncol = 3,
  xAxisLabels = c("A", "B", "C"),
  yAxisLabels = c("D", "E"),
  title = "Matrix Title",
  byrow = FALSE
)
pm

Two-by-three plot matrix titled Matrix Title with column labels A, B, C and row labels D, E. Text panels Plot #1 to Plot #6 are filled column by column, so the top row reads 1, 3, 5.

Matrix Subsetting

Individual plots may be retrieved from the plot matrix and can be placed in the plot matrix.

pm <- ggmatrix(
  plotList,
  nrow = 2, ncol = 3,
  xAxisLabels = c("A", "B", "C"),
  yAxisLabels = c("D", "E"),
  title = "Matrix Title"
)
pm

Two-by-three plot matrix titled Matrix Title with column labels A, B, C and row labels D, E, showing text panels Plot #1 to Plot #6 in row order.

p2 <- pm[1, 2]
p3 <- pm[1, 3]
p2

Single text panel reading Plot #2, taken from row 1, column 2 of the matrix.

p3

Single text panel reading Plot #3, taken from row 1, column 3 of the matrix.

pm[1, 2] <- p3
pm[1, 3] <- p2
pm

Two-by-three plot matrix titled Matrix Title after swapping two panels: the top row now reads Plot #1, Plot #3, Plot #2, and the bottom row is unchanged.

Themes

library(ggplot2)
pm <- ggmatrix(
  plotList,
  nrow = 2, ncol = 3,
  xAxisLabels = c("A", "B", "C"),
  yAxisLabels = c("D", "E"),
  title = "Matrix Title",
  byrow = FALSE
)
pm <- pm + theme_bw()
pm

Two-by-three plot matrix titled Matrix Title with column labels A, B, C and row labels D, E, showing text panels Plot #1 to Plot #6 in column order, drawn with the black-and-white theme (white backgrounds, grey grid lines, panel borders).

Axis Control

The X and Y axis have booleans to turn on/off the individual plot’s axes on the bottom and left sides of the plot matrix. To save time, showAxisPlotLabels can be set to override showXAxisPlotLabels and showYAxisPlotLabels.

pm <- ggmatrix(
  plotList,
  nrow = 2, ncol = 3,
  xAxisLabels = c("A", "B", "C"),
  yAxisLabels = c("D", "E"),
  title = "No Left Plot Axis",
  showYAxisPlotLabels = FALSE
)
pm

Two-by-three plot matrix titled No Left Plot Axis showing text panels Plot #1 to Plot #6; the bottom axis tick labels are shown but the left axis tick labels are removed.

pm <- ggmatrix(
  plotList,
  nrow = 2, ncol = 3,
  xAxisLabels = c("A", "B", "C"),
  yAxisLabels = c("D", "E"),
  title = "No Bottom Plot Axis",
  showXAxisPlotLabels = FALSE
)
pm

Two-by-three plot matrix titled No Bottom Plot Axis showing text panels Plot #1 to Plot #6; the left axis tick labels are shown but the bottom axis tick labels are removed.

pm <- ggmatrix(
  plotList,
  nrow = 2, ncol = 3,
  xAxisLabels = c("A", "B", "C"),
  yAxisLabels = c("D", "E"),
  title = "No Plot Axes",
  showAxisPlotLabels = FALSE
)
pm

Two-by-three plot matrix titled No Plot Axes showing text panels Plot #1 to Plot #6 with both the left and bottom axis tick labels removed.

Strips Control

By default, the plots in the top row and the right most column will display top-side and right-side strips respectively (showStrips = NULL). If all strips need to appear in each plot, showStrips may be set to TRUE. If all strips should not be displayed, showStrips may be set to FALSE.

data(tips)
subPlot <- function(smoker_value, sex_value) {
  ggplot(
    data = tips[tips$smoker == smoker_value & tips$sex == sex_value, ],
    aes(x = !!as.name("total_bill"), y = !!as.name("tip"))
  ) +
    geom_point() +
    facet_grid(time ~ day)
}
plotList <- list(
  subPlot("No", "Female"),
  subPlot("Yes", "Female"),
  subPlot("No", "Male"),
  subPlot("Yes", "Male")
)

pm <- ggmatrix(
  plotList,
  nrow = 2, ncol = 2,
  yAxisLabels = c("Female", "Male"),
  xAxisLabels = c("Non Smoker", "Smoker"),
  title = "Total Bill vs Tip",
  showStrips = NULL # default
)
pm

Two-by-two plot matrix titled Total Bill vs Tip with columns Non Smoker and Smoker and rows Female and Male. Each cell is a scatterplot of tip versus total bill faceted by time and day; with the default setting, day strips appear only on the top row and time strips only on the right column.

pm <- ggmatrix(
  plotList,
  nrow = 2, ncol = 2,
  yAxisLabels = c("Female", "Male"),
  xAxisLabels = c("Non Smoker", "Smoker"),
  title = "Total Bill vs Tip",
  showStrips = TRUE
)
pm

The same two-by-two Total Bill vs Tip plot matrix by smoker and sex, now with day and time facet strips shown on every panel.

pm <- ggmatrix(
  plotList,
  nrow = 2, ncol = 2,
  yAxisLabels = c("Female", "Male"),
  xAxisLabels = c("Non Smoker", "Smoker"),
  title = "Total Bill vs Tip",
  showStrips = FALSE
)
pm

The same two-by-two Total Bill vs Tip plot matrix by smoker and sex with all facet strips hidden, so the day and time facets are unlabelled.