Multiple Heat Maps for Projected Coordinates

Functions for displaying multiple images with a color scale, i.e., heat maps, possibly with projected coordinates. The package relies on the base graphics system, so graphics are rendered rapidly.

Build Statuscodecov

The autoimage R package

  fig.path = "tools/README/"


The goal of the autoimage package is to easily plot a sequence of images with corresponding color scales, i.e., a sequence of heatmaps, with straightforward, native options for projection of geographical coordinates. The package makes it simple to add lines, points, and other graphics features to these image plots, even when the coordinates are projected. The package allows for seamless creation of heat maps for data on regular or irregular grids, as well as that is not on a grid.


The release version of autoimage can be installed in R using the command install.packages("autoimage").

The development version of autoimage can be installed in R using the command: devtools::install_github("jpfrench81/autoimage")


The most important functions in autoimage are the pimage and autoimage functions. pimage creates a heat map with a color scale for data on a regular or irregular grid, and even non-gridded data (by automatically interpolating onto a grid). The autoimage function generalizes the pimage function to allow for multiple images in the same plot.

The autoimage package makes it easy to add lines and points to the images plots, with several common world maps being provided automatically through the maps package.

We illustrate some basic usage of the pimage function.

We begin by creating image plots for data on an irregular grid while also including national boundaries and a legend. The coordinates are projected in the second plot by specifying the desired projection via the proj argument and the relevant projection parameters via the parameters arguments.

# display some narccap data on an irregular grid
# heat map for data on an irregular grid with national boundaries
pimage(lon, lat, tasmax[,,1], map = "world", legend = "h")

# same plot but with projection
pimage(lon, lat, tasmax[,,1], map = "world", legend = "v",
       proj = "bonne", parameters = 45)

We next display an image for data that is not on a grid. Specifically, we create image plots for Colorado geochemical measurements. We also include the Colorado border in the image and the locations of the observed coordinates. Note that the lines.args and points.args arguments are used to customize the appearance of the lines and points.

# colorado data not on a grid
# show observed locations on image,
# along with Colorado border
data(co, package = "gear") # load colorado geochemical measurements
data(copoly) # load colorado borders
# create list with observed points
copoints <- list(x = co$lon, y = co$lat) 
pimage(co$longitude, co$latitude, co$Al, 
       lines = copoly, 
       lines.args = list(lwd = 2, col = "grey"),
       points = copoints, 
       points.args = list(pch = 21, bg = "white"),
       xlim = c(-109.1, -102),
       ylim = c(36.8, 41.1))

The autoimage function generalizes the pimage function to allow for a sequence of images in a single graphic. We display two images, first with a common legend, then with individual legends for each image.

# plot images with USA state borders and common vertical scale
autoimage(lon, lat, tasmax[,,1:2], legend = "v", map = "usa")

# with separate scales
autoimage(lon, lat, tasmax[,,1:2], common.legend = FALSE, map = "usa")



1.0 - Add pimage function to create individual projected images.

    Create autolegend to manually add legend to image created
    by pimage.  Update autoimage to rely on pimage and autolegend.
    Add plines, ppoints, etc., functions to add lines, points, 
    etc., to existing images created by pimage.  Create helper
    function to make plot similar to autoimage using ggplot2.
    Introduce incompatibilities with version 0.3.1.  Add vignette
    with examples of package capabilities.  Update License because
    of importation of akima package.

1.1 - Update package to suggest akima package. Done for GPL

    reasons.  User must install akima manually.

1.2 - Update vignette and narccap data documentation to correct

    error in climate models.  

1.3 - Add text capability to pimage and autoimage. Add new

    vignette comparing autoimage and ggplot2. Improve blank.plot()
    by reducing margins before plotting, returning to previous
    margins.  Changed behavior of lratio in autoimage
    to adapt to number of images being plotted.

2.0 - Use for grid interpolation instead of akima::interp because of rescrictive licensing. Update behavior of lratio to adapt based on the number of images being plotted. Add inarccap data.

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.


2.0 by Joshua French, 4 months ago

Report a bug at

Browse source code at

Authors: Joshua French

Documentation:   PDF Manual  

GPL (>= 2) license

Imports fields, mapproj, viridisLite, ggplot2, maps, MBA

Suggests abind, viridis, testthat, spatstat, gear, broom, gridExtra, knitr, rmarkdown

See at CRAN