bubbleHeatmap {bubbleHeatmap}

Generate bubbleHeatmap Plot Object

Description

This function creates a gTree for a bubbleHeatmap plot. These plots have a grid of "bubbles" with the color and size each scaled according to the values of a different variable. They can be used as an alternative to forest plots for visualizing estimates and errors that can be organised in a grid format, correlograms, and any other two variable matrices.

Usage

bubbleHeatmap(
  colorMat,
  sizeMat = colorMat,
  treeName = "Plot",
  context = gpar(cex = 0.8),
  colorSeq = c("#053061", "#2166AC", "#4393C3", "#92C5DE", "#D1E5F0", "#FDDBC7",
    "#F4A582", "#D6604D", "#B2182B", "#67001F"),
  unitBase = unit(0.5, "cm"),
  diameter = 0.8,
  colorLim = c(NA, NA),
  sizeLim = c(NA, NA),
  showTopLabels = TRUE,
  showLeftLabels = TRUE,
  leftLabelsTitle = FALSE,
  showRowBracket = FALSE,
  rowTitle = FALSE,
  showColBracket = FALSE,
  colTitle = FALSE,
  plotTitle = FALSE,
  xTitle = FALSE,
  yTitle = FALSE,
  showColorLegend = TRUE,
  showBubbleLegend = TRUE,
  colorBreaks = NULL,
  sizeBreaks = NULL,
  legendHeight = 8,
  legendTitles = c(expression("-log"[10] * "P"), "Estimate (SD)")
)

Arguments

colorMat, sizeMat

Numeric matrices containing values to be mapped to bubble color and size respectively. The dimensions, rownames and colnames of these matrices must match.

treeName

Identifying character string for gTree.

context

gpar object to provide drawing context. Will be applied to the parent viewport in the childrenvp slot of the gTree.

colorSeq

Character vector of colors to be used in creating color scale.

unitBase

unit object indicating the size of one plot grid box.

diameter

Maximum diameter of bubbles as multiple of unitBase.

colorLim, sizeLim

Numeric vectors indicating limits (min/max) outside which the values of color/size matrices should be truncated. NOTE! These data ranges are separate from the scale ranges, which are taken from the min/max values of colorBreaks and sizeBreaks.

showTopLabels

Logical, should matrix column names be printed above plot?

showLeftLabels

Logical, should matrix row names be printed above plot?

leftLabelsTitle

Heading to print over the column of row names.

showRowBracket

Logical vector, should vertical bracket be printed to the right of the plot (to label a row of plots in a final figure layout)?

rowTitle

Label to be printed to the right of the plot, outside row bracket if present, to label a row of plots in a final figure layout.

showColBracket

Logical, should horizontal bracket be printed below the plot (to label a column of plots in a final figure layout)?

colTitle

Label to be printed below plot, outside col bracket if present, to label a column of plots in a final figure layout.

plotTitle

Plot title string, to be centered above plot.

xTitle

X-axis title string, displayed left of LeftLabels.

yTitle

Y-axis title string, displayed above TopLabels.

showColorLegend, showBubbleLegend

Should plot include legends for color scale/bubble size?

colorBreaks, sizeBreaks

Character vectors of legend tick labels. The min/max values will represent the range of color/size scales. If not supplied then these will be generated using pretty, to a range outside data values (after values truncated to colorLim\sizeLim if applicable).

legendHeight

Numeric, preferred height of legends in multiples of unitBase. This will be supplied to pretty function. If sizeBreaks vector is supplied then this will be ignored and legend height will be length(sizeBreaks).

legendTitles

Character vector of legend titles. First string should be the size legend title, second for the color legend.

Value

This function creates a bubbleHeatmap using the grid graphics package. It does not draw any output but produces a gTree object which can be drawn using the grid.draw function. Returned trees always include a viewport object with a 7x6 layout and a given plot element is always positioned in the same cell, to assist with aligning elements when combining multiple plots in a single figure (see vignette, matchLayoutHeights, matchLayoutWidths). NOTE: A cairo output device with gradient support is necessary to correctly render the color legend.

See Also

Other build functions: bubbleHMLegends(), bubbleHeatmapList(), multiPlotInput()

Examples

# Example 1 - Available plot features#
names <- list(paste0("leftLabels", 1:6), paste0("topLabels", 1:10))
colorMat <- matrix(rnorm(60), nrow = 6, ncol = 10, dimnames = names)
sizeMat <- matrix(abs(rnorm(60)), nrow = 6, ncol = 10, dimnames = names)
tree <- bubbleHeatmap(colorMat, sizeMat,
  treeName = "example",
  leftLabelsTitle = "leftLabelsTitle", showRowBracket = TRUE,
  rowTitle = "rowTitle", showColBracket = TRUE, colTitle = "colTitle",
  plotTitle = "plotTitle", xTitle = "xTitle", yTitle = "yTitle",
  legendTitles = c("legendTitles[1]", "legendTitles[2]")
)
grid.draw(tree)