plot_matrix: Plot Matrix with Entries Represented by Balloons of Varying...

In Upsilon: Another Test of Association for Count Data

Plot Matrix with Entries Represented by Balloons of Varying Sizes and Colors

Description

Creates a "balloon plot" to visualize numeric data in a matrix or contingency table.

Usage

plot_matrix(
  x,
  title = "Balloon plot",
  shape.color = c("tomato"),
  s.min = 1,
  s.max = 30,
  x.axis = NULL,
  y.axis = NULL,
  x.lab = "",
  y.lab = "",
  bg.color = "white",
  grid.color = "black",
  grid.width = 0.1,
  size.by = c("column", "row", "global", "none"),
  color.by = c("column", "row", "global", "none"),
  number.size = 6,
  shape.by = c("column", "row", ""),
  shapes = c(21, 22, 23, 24),
  color.contrast = 1
)

Arguments

x	a numeric matrix or table to be plotted.
title	a character string for the main title of the plot. Defaults to "Balloon plot".
shape.color	a character string specifying the color for entries (e.g., "tomato", "blue").
s.min	a numeric value specifying the minimum size of the shapes. Defaults to 1.
s.max	a numeric value specifying the maximum size of the shapes. Defaults to 30.
x.axis	a character vector for custom x-axis labels. If NULL, column names of x are used. Set to "" to hide labels.
y.axis	a character vector for custom y-axis labels. If NULL, row names of x are used. Set to "" to hide labels.
x.lab	a character string for the x-axis title. Defaults to "".
y.lab	a character string for the y-axis title. Defaults to "".
bg.color	a character string for the background color of the tiles. Defaults to "white".
grid.color	a character string specifying color of grid lines (NA to remove).
grid.width	a numeric value to specify the width of grid lines.
size.by	a character string to specify how to scale the size of balloon: "column" (Default), "row", "global", or "none".
color.by	a character string to specify how to scale the color of balloon: "column" (Default), "row", "global", or "none".
number.size	a numeric value specifying the font size for text.
shape.by	a character string to specify how to choose the shape of balloon: "column" (Default), "row", or "" (none).
shapes	a numeric vector to specify shape codes.
color.contrast	a numeric value between 0 and 1 to adjust the lightness of the lowest values. Defaults to 1.

Details

Each entry in the matrix is represented by a shape, with size and color corresponding to the magnitude of value in the entry. It offers an alternative to heatmap for displaying count data.

Value

A ggplot object.

Examples

library(ggplot2)
mat <- matrix(c(10, 20, 30, 50, 80, 60, 40, 30), nrow = 2)
rownames(mat) <- c("Row1", "Row2")
colnames(mat) <- c("C1", "C2", "C3", "C4")

# Color by Row (Row 1 = red, Row 2 = blue)
plot_matrix(mat, color.by = "row", shape.color = c("tomato", "steelblue"))

# Color by Column (Rainbow colors)
plot_matrix(mat, color.by = "column", shape.color = c("red", "green", "blue", "orange"))

Upsilon documentation built on March 7, 2026, 5:07 p.m.