pretty_mat: Plot pretty matrices

In edwardlavender/prettyGraphics: Pretty Graphics with R

Plot pretty matrices

Description

This function is a wrapper for image.plot designed to streamline the visualisation of pretty matrices. The function returns a plot which can be customised.

Usage

pretty_mat(
  z,
  retain_orientation = FALSE,
  zlim = NULL,
  col = (grDevices::colorRampPalette(c("white", "yellow", "orange", "red")))(100),
  col_diag = NULL,
  grid = NULL,
  add_axes = TRUE,
  xtick_every_n = 1,
  ytick_every_n = xtick_every_n,
  cex.axis = 1,
  las = TRUE,
  xlab = "",
  ylab = "",
  ...
)

Arguments

z	A matrix to be plotted.
retain_orientation	A logical input which defines whether or not the plot should retain the same orientation as the printed matrix. The default is FALSE, in which case the underlying plotting function (image.plot) rotates the matrix by 90 degrees counter-clockwise in the plot. In contrast, retain_orientation = TRUE forces the matrix and the plot to retain the same orientation (see Details).
zlim	A numeric vector of length two which specifies the z axis limits (see image.plot),
col	A colour table to use for the image (see image.plot).
col_diag	(optional) A colour which, if provided, is used to shade the diagonal of the matrix. This is useful for symmetric square matrices.
grid	(optional) A named list which, if provided, is passed to add_grid_rect_xy to draw grid lines around each matrix cell. Arguments x and y default to the positions of each matrix cell and do not need to be provided. To use add_grid_rect_xy's default graphical options, simply specify grid = list().
add_axes	A logical input which defines whether or not to add axes to the plot. Axes tick marks are given every nth column and every nth row (see below).
xtick_every_n	A numeric input which defines the spacing between sequential tick marks for the x axis. Tick marks are given every xtick_every_n (see Details).
ytick_every_n	A numeric input which defines the spacing between sequential tick marks for the other axis. Tick marks are given every ytick_every_n (see Details).
cex.axis	A number which specifies the axis font size (see par).
las	The style of axis labels (see par).
xlab	The x axis label.
ylab	The y axis label.
...	Additional arguments passed to image.plot. These should not include x, y, xlim, ylim or axes which are controlled internally.

Details

The limits of the plot are set between (0.5, number of rows + 0.5) and (0.5, number of cols + 0.5). Axes are added by default, but can be suppressed. If available, matrix row/column names are used to define axis labels. Otherwise, an index is used. Axes labels are added every xtick_every_n and ytick_every_n. If retain_orientation is FALSE, the plot is rotated 90 degrees counter-clockwise relative to the input matrix and thus read from the bottom-left to the top-right (like a map), so that matrix columns and corresponding tick mark labels are represented along the y axis whereas matrix rows and corresponding tick mark labels are represented along the x axis. In contrast, if retain_orientation is TRUE, the plot is read from the top-left to bottom-right.

Value

The function returns a plot of a matrix with coloured cells.

Author(s)

Edward Lavender

Examples

#### Define an example square matrix
n <- 25
mat <- matrix(sample(0:100, size = n^2, replace = TRUE), ncol = 25, nrow = 25)

#### Example (1): The default options
pretty_mat(mat)

#### Example (2): Customisation
# Adjust labelling and note how under the default settings the plot
# ... is rotated by 90 degrees counter-clockwise
rownames(mat) <- colnames(mat) <- LETTERS[1:nrow(mat)]
pretty_mat(mat)
pretty_mat(mat, xlab = "ID", ylab = "ID")
# Adjust the number of labels
pretty_mat(mat, xlab = "ID", ylab = "ID",
           xtick_every_n = 5, ytick_every_n = 2)
# Compare to plot with retained orientation
pretty_mat(mat, xlab = "ID", ylab = "ID",
           xtick_every_n = 5, ytick_every_n = 2,
           retain_orientation = TRUE)
# Adjust z limits
pretty_mat(mat, zlim = c(0, 200))
# Adjust colour scheme
pretty_mat(mat, col = grey.colors(100))
# Colour the diagonal (useful for symmetric square matrices)
pretty_mat(mat, col_diag = "black")
# Add a grid using default options
pretty_mat(mat, grid = list())
# Customise the grid
pretty_mat(mat, grid = list(col = "black", lty = 1))

#### Example (3) Rectangular matrices function similarly
# Define matrix
n1 <- 5; n2 <- 10
mat <- matrix(sample(0:100, size = n1*n2, replace = TRUE), ncol = n1, nrow = n2)
utils::str(mat)
# Visualise matrix with default options
pretty_mat(mat)
# Adjust names
rownames(mat) <- LETTERS[1:nrow(mat)]
colnames(mat) <- LETTERS[1:ncol(mat)]
pretty_mat(mat)
# Other options can be implemented as above
pretty_mat(mat, grid = list(lty = 1))
# However, adding colours along the diagonal may not make sense for asymmetric matrices
pretty_mat(mat, col_diag = "grey")

#' #### Example (4): Understanding the retain_orientation argument:
# ... Under the default option (retain_orientation is FALSE), R plots a
# ... 90 degree counter-clockwise rotation of the conventional
# ... printed layout of a matrix. This can be difficult to interpret.
# ... retain_orientation = TRUE ensures the matrix is plotted in the
# ... correct orientation
# Define a simple matrix
n <- 3
mat <- matrix(1:9, ncol = 3, nrow = 3)
# Distinguish row names from column names
rownames(mat) <- LETTERS[1:ncol(mat)]
# Check matrix
mat
# Visualise 'default' versus 'expected' matrix
pp <- par(mfrow = c(1, 2))
pretty_mat(mat, retain_orientation = FALSE, main = "default (rotated)")
pretty_mat(mat, retain_orientation = TRUE, main = "custom (original orientation)")
par(pp)

edwardlavender/prettyGraphics documentation built on Jan. 19, 2025, 2:47 p.m.