Skip to contents

Plot a (Possibly Sparse) Matrix as a False-Colour Image

Source: R/plotmat.R
plotmat.Rd

Plot a numeric matrix (dense or sparse) as a raster image with a colour gradient. The function optionally down-scales large matrices to respect a maximum resolution, applies a gamma transformation for contrast enhancement, and maps the values to a user-supplied or default colour palette. Internally, the image is drawn on an index grid (x = 1:nrow, y = 1:ncol); if numeric row/column names are available, custom axes are added afterwards and tick labels reflect those values.

Usage

plotmat(M, maxresolution = 2000, gamma = 0.13, axes = TRUE,
        cols = grDevices::colorRampPalette(
          c("black","black","blue","green","yellow","orange","red"))(1000),
        signed = FALSE, ...)

Arguments

M

A numeric matrix or a sparse matrix from the Matrix package (e.g., dgCMatrix).

maxresolution

Integer. Maximum number of pixels in either dimension after down-scaling. Set to NULL to disable down-scaling. Default 2000.

gamma

Positive numeric. Gamma correction applied to matrix values prior to colour mapping (\(v^\gamma\)). Smaller values enhance contrast in low-intensity regions. Default 0.13.

axes

Logical. If TRUE (default), draw custom axes after plotting on the index grid. If row/column names are fully numeric they are used to label ticks; otherwise default index ticks are used. Set FALSE to draw no axes.

cols

A character vector of colours (e.g., created by colorRampPalette). Defaults to a 1000-colour palette.

signed

Preserve negative values and use the signed gamma transform \(\operatorname{sign}(v)|v|^\gamma\). Default FALSE truncates negative values to zero. Supply a diverging palette for signed data.

...

Further arguments passed to image (e.g., xlab, ylab, main, graphical parameters).

Value

Invisibly returns the list produced by image. The primary purpose of the function is its graphical side-effect.

Details

  • Down-scaling: If the matrix exceeds maxresolution in either dimension, it is down-scaled by block averaging (see downscale()).

  • Sparse input: Sparse matrices are converted to dense form via as.matrix. Missing values are set to zero and negative values truncated to zero unless signed=TRUE.

  • Axes: The image is rendered on the index grid with axes = FALSE in the internal image call. When axes = TRUE, tick locations are computed by mapping "value space" (from numeric row/column names, if available) to index positions via linear interpolation; if names are missing or not all numeric, integer index ticks are used.

See also

image, colorRampPalette, Matrix

Author

Tom Wenseleers tom.wenseleers@kuleuven.be \ Laboratory of Socioecology and Social Evolution, KU Leuven \ https://bio.kuleuven.be/eeb/tw/research \ ORCID: 0000-0002-1434-861X

Examples

## Dense matrix example: plot a GC/MS chromatogram
M = simulate_GCMS()$D # simulated GC/MS chromatogram
plotmat(M = M, 
        gamma = 0.13, 
        xlab = "Elution time (mins)", 
        ylab = "Mass (m/z)",
        main = "GC/MS chromatogram")