The aim of the package plot.matrix is to visualize a matrix as is with a heatmap. Automatic reordering of rows and columns is only done if necessary. This is different as in similar function like heatmap. Additionally it should be user-friendly and give access to a lot of options if necessary.

Currently the package implements the S3 functions below such that you can use the generic plot function to plot matrices as heatmaps:

The plot itself is composed by a heatmap (usually left) where colors represent matrix entries and a key (usually right) which links the colors to the values.

First examples

# numeric matrix
x <- matrix(runif(35), ncol=5) # create a numeric matrix object
#> [1] "matrix" "array"
par(mar=c(5.1, 4.1, 4.1, 4.1)) # adapt margins

# logical matrix
m <- matrix(runif(35)<0.5, ncol=7)

# text matrix
s <- matrix(sample(letters[1:10], 35, replace=TRUE), ncol=5)

data <- na.omit(bfi[,1:25])
fa <- fa(data, 5, rotate="varimax")
par(mar=c(5.1, 4.1, 4.1, 4.1)) # adapt margins
plot(loadings(fa), cex=0.5)

Assigning colors and breaks

plot.matrix uses the command assignColors, also part of plot.matrix, assigns to each value in x a color based on the parameters breaks, col and na.col given.

In case of a numeric matrix breaks can be

  • a number, giving the number of intervals covering the range of x,
  • a vector of two numbers, given the range to cover with 10 intervals, or
  • a vector with more than two numbers, specify the interval borders

In case of a non-numeric vector breaks must contain all values which are will get a color. If breaks is not given then a sensible default is chosen: in case of a numeric vector derived from pretty and otherwise all unique values/levels are used.

col can be either be a vector of colors or a function which generates via col(n) a set of n colors. The default is to use heat.colors.

Choosing color palettes/functions

In case that you want to provide your own color palettes/functions for plotting there are several good choices within R packages:

Source: Datanovia - Top R Color Palettes to Know for Great Data Visualization

Structure of the plot

The plot is created in several steps

  1. a call to the plot command to create the basic plot
  2. draw colored polygons for each matrix entry with the polygon command
  3. if necessary add the value of each matrix entry with the text command in a polygon
  4. if necessary draw x- and y-axis with the axis command into the plot
  5. if necessary draw the key with the axis and the polygon command

Formal parameters

#> Warning in kable_pipe(x = structure(c("plot.matrix(", "", "", "", "", "", : The
#> table should have a header (column names)
plot.matrix( x,
y = NULL,
breaks = NULL,
col = heat.colors,
na.col = “white”,
na.cell = TRUE,
na.print = TRUE,
digits = NA,
fmt.cell = NULL,
fmt.key = NULL,
polygon.cell = NULL,
polygon.key = NULL,
text.cell = NULL,
key = list(side = 4, las = 1),
axis.col = list(side = 1),
axis.row = list(side = 2),
axis.key = NULL,
max.col = 70,

You may influence the appearance by setting your own parameters:

  1. ... all parameters given here will be given to the plot command, e.g. xlab, ylab, ….
  2. polygon.cell list of parameters for drawing polygons for matrix entries
  3. text.cell list of parameters for putting for matrix entries as texts
  4. axis.col and axis.row list of parameters for drawing for row and column axes
  5. key, axis.key and polygon.key to draw the key
  6. max.col to determine when text color and background color to near

Set global parameters

You may set global parameters for all subsequent calls of axis, polygon and text via the .... The following parameters are supported

function parameter(s)
axis cex.axis, col.axis, col.ticks, font, font.axis, hadj, las, lwd.ticks, line , outer, padj, tck, tcl, tick
polygon angle, border, density
text cex, font, vfont
par(mar=c(5.1, 4.1, 4.1, 4.1)) # adapt margins
# omit all borders
plot(x, border=NA)

Frequently asked questions

How can I delete the grid lines?

Use the parameter border=NA.

How can I get squared boxes?

Use the parameter asp=TRUE.

How can I rotate the axis labels such they do no overlap?

Use the parameter las, the style of axis labels, in axis.coland/or axis.row with

  • 0 = always parallel to the axis [default],
  • 1 = always horizontal,
  • 2 = always perpendicular to the axis, and
  • 3 = always vertical.
x <- matrix(runif(35), ncol=5) # create a numeric matrix object
par(mar=c(5.1, 4.1, 4.1, 4.1)) # adapt margins such that all labels are visible
plot(x, axis.col=list(side=1, las=2), axis.row = list(side=2, las=1))

Modifying a plot


The default plot always draws a heatmap and a key where the colors and breaks are determined by the entries of x. In case of a numeric matrix ten colors from heat.colors are chosen and eleven breaks with cover the range of entries with an equidistant grid. In case of a non-numeric matrix each unique element gets a color determined from heat.colors.

Modifying the breaks

In case of a numeric matrix the breaks give the interval borders for a color otherwise for each unique matrix entry breaks should contain a value. If breaks are not given then they will be determined from the matrix object by using the pretty function of base R.

par(mar=c(5.1, 4.1, 4.1, 4.1))   # adapt margins
# we only want the range of x
plot(x, breaks=range(x))