The autoimage package makes it easy to 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 features to the images, 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 data that is not on a grid.
The most important functions in autoimage are the
autoimage functions. We illustrate the basic usage of these functions using two data sets: the first is data on an irregular grid and the second is non-gridded data.
The first data set we utilize comes from the North American Regional Climate Change Assessment Program (NARCCAP, https://www.narccap.ucar.edu/). Specifically, the data are the maximum daily surface air temperature (K) (abbreviated tasmax) for the five consecutive days of May 15, 2041 to May 19, 2041 simulated using the Canadian Regional Climate Model (Caya and Laprise, 1999) forced by the Community Climate System Model atmosphere-ocean general circular model (Collins et al., 2006). The data set contains
lon, a 140 \(\times\) 115 matrix of longitude coordinates,
lat, a 140 \(\times\) 115 matrix of latitude coordinates, and
tasmax, a 140 \(\times\) 115 \(\times\) 5 array, where each element of the third dimension of the array corresponds to the
tasmax measurements of the respective day.
The second data set we utilize is geochemical measurements obtained by the United States Geological Survey (USGS) in the state of Colorado. The data are stored as a data frame with 960 rows and 31 columns.
longitude variables are provided in the data frame, as well as Aluminum (
Al), Calcium (
Ca), Iron (
Fe), and many more chemical measurements.
autoimage function is a generalization of the
pimage function, so we discuss the
pimage function first.
The most important arguments of the
pimage function are
y are the coordinate locations and
z is the responses associated with the coordinates.
We create a basic image plot by providing
z to the
data(narccap) pimage(x = lon, y = lat, z = tasmax[,,1])
z can have differing formats depending on the type of data. If the data are observed on a regular grid, then
z will be matrix with dimensions matching the dimensions of the grid and
y will be vectors of increasing values that define the grid lines. If the data are observed on an irregular grid (e.g., a regular grid that is rotated or projected), then
z will be a matrix with dimensions matching the dimensions of the grid and
y will be matrices whose coordinates specify the x and y coordinates of each value in
z. If the data are not on a grid, then
y will be vectors specifying the coordinate locations, and
z will be the vector of responses at each coordinate. If the data are not on a grid, then multilevel B-splines are used to automatically predict the response on a grid before plotting (using the
mba.surf function in the MBA package).
We create a heat map using the non-gridded Aluminum measurements for the state of Colorado.
data(co, package = "gear") pimage(co$longitude, co$latitude, co$Al, xlab = "lon", ylab = "lat")
We now discuss the basic options of the
The color scheme used for an image plot can be of great importance. We use the
Viridis color palette from the colorspace package by default. This approximates the
"viridis" palette in the viridisLite package. As stated in the
viridis function in the viridisLite package, the color map is, “… designed in such a way that [it] will analytically be perfectly perceptually-uniform, both in regular form and also when converted to black-and-white. [It is] also designed to be perceived by readers with the most common form of color blindness.” The colors of the color scale can be modified by passing a vector of colors to the
col argument through
..., as in the
image function in graphics. We use 6 colors from the
Plasma color palette in the colorspace package in the next example.
pimage(lon, lat, tasmax[,,1], col = colorspace::sequential_hcl(n = 6, palette = "Plasma"))
The orientation of the color scale can be changed by changing the
legend argument. The default is
legend = "horizontal". The color scale can be removed by specifying
legend = "none" or rotated to a vertical orientation by specifying
legend = "vertical".
The following code creates a heat map with a vertical color scale.
pimage(x = lon, y = lat, z = tasmax[,,1], legend = "vertical")
The longitude and latitude coordinates can be projected before plotting by specifying the
orientation arguments of
pimage. Prior to plotting, the coordinates are projected using the
mapproject function in the mapproj package.
proj specifies the name of the projection to utilize (the default is
parameters argument specifies the parameter values of the chosen projection and
orientation can be used to change the orientation of the projection. See the
mapproject function in the mapproj package for more details regarding these arguments.
We now create a heat map with projected coordinates. We will utilize the Bonne projection using 45 degrees as the standard parallel. A grid is automatically added to projected images because latitude and longitude parallels are not straight for most projections.
pimage(x = lon, y = lat, z = tasmax[,,1], proj = "bonne", parameters = 45)
Several maps can be automatically added to the image by specifying the
map argument. The maps come from the maps package, and include the
nz (New Zealand),
We add national boundaries to our previous map.
pimage(x = lon, y = lat, z = tasmax[,,1], proj = "bonne", parameters = 45, map = "world")
The last major argument to the
pimage function is the
lratio argument. This argument controls the relative height or width of the color scale in comparison with the main plotting area. Increasing
lratio increases the thickness of the color scale, while decreasing
lratio decreases the thickness of the color scale.
Additional arguments can be passed to the
pimage function via
.... These will be discussed at a later time in this vignette.
autoimage function generalizes the
pimage function to allow for multiple images in the same plot. Most of the arguments are the same as the
pimage function, and we do not replicate their discussion except when necessary.
The structure of
z will vary slightly from the
pimage function. Specifically, if multiple gridded images are to be constructed, then
z will be a three-dimensional array instead of a matrix. Each element of the third dimension of
z corresponds to the matrix of gridded values for each image. If images for multiple non-gridded variables are to be constructed, then
z will be a matrix with each column corresponding to a different variable.
Passing a three-dimensional array to
autoimage constructs a sequence of images with a common legend.
autoimage(lon, lat, tasmax)
Passing a two-dimensional matrix for
z (where the number of rows matches the length of
y) constructs a sequence of images for non-gridded data with a common legend. Titles are added to each image using the
main argument by providing a character vector whose length matches the number of plotted images.
autoimage(co$longitude, co$latitude, co[,c("Al", "Ca", "Fe", "K")], main = c("(a) Aluminum %", "(b) Calcium %", "(c) Iron %", "(d) Potassium %"), xlab = "lon", ylab = "lat")
Separate color scales will be used for each image when
common.legend = FALSE.
autoimage(co$longitude, co$latitude, co[,c("Al", "Ca", "Fe", "K")], common.legend = FALSE, main = c("(a) Aluminum %", "(b) Calcium %", "(c) Iron %", "(d) Potassium %"), xlab = "lon", ylab = "lat")
The dimensions of the plotting matrix can be changed by specifying the
size argument. If not provided, then a sensible choice is automatically chosen via the
autosize function. The
size argument should be a two-dimensional vector where the first element corresponds to the number of rows of images and the second dimension corresponds to the number of columns.
We create a 1 \(\times\) 3 matrix of images for the NARCCAP data.
autoimage(lon, lat, tasmax[,,1:3], size = c(1, 3))
A common title is sometimes desired for a sequence of images. This can easily be added by specifying the
outer.title argument. The margins of the common title can be controlled via the
oma argument of
par. However, if
oma is not specified beforehand, then a sensible value is automatically chosen (while showing a warning to the user.)
We add a common title to the NARCCAP data.
autoimage(lon, lat, tasmax, outer.title = "tasmax for 5 days")
## Warning in autolayout(size, legend = legend, common.legend = common.legend, : There is no room in the outer margin for an outer title. ## Setting par(oma = c(0, 0, 3, 0)).
The mercator projection can sometimes be problematic for various reasons, especially with the world map as horizontal lines appear across the plot area. We have attempted to solve this issue by clipping x and y coordinates that are outside the range of
autoimage(x = lon, y = lat, z = tasmax[,,1], map = "world", xlab = "longitude", ylab = "latitude", proj = "mercator", axes = FALSE)
Suppose we want to add custom features to a sequences of images, with each image receiving different features. One can create a richer sequence of images using the
autolayout function partitions the graphic device into the sections needed to create a sequence of images. The most important function arguments include
lratio, which correspond to the same arguments in the
autoimage function. The
outer argument specifies whether an
outer.title is desired. The default is
FALSE. By default, numbers identify the plotting order of the sections, though these can be hidden by setting
show = FALSE. As an initial example, we create a 2 \(\times\) 3 grid of images with a common vertical legend.
autolayout(c(2, 3), legend = "v")
The images should be created using the
pimage function while specifying
legend = "none". After the desired image or set of images is created, one can automatically add the appropriate legend by calling
autolegend function recovers relevant legend parameters from the most recent
pimage call. Consequently, if a common legend is desired, then it is important to specify a common
zlim argument among all relevant
Various features can be added to the images using the
ppolygon functions. These are analogues of the
polygon functions in the graphics package, to be used with images containing projected coordinates.
We now create a complicated (though unrealistic) example of this. We first extract the borders of Hawaii and Alaska from the
"world" map in the maps package and store it as the
hiak list. We then select a small subset of cities in Colorado from the
us.cities dataset in the maps package and store this in the
codf data frame. Lastly, we select the U.S. capitals from the
us.cities dataset and store this in the
capdf data frame.
# load world map data(worldMapEnv, package = "maps") # extract hawaii and alaskan borders <- maps::map("world", c("USA:Hawaii", "USA:Alaska"), hiak plot = FALSE) # load us city information data(us.cities, package = "maps") # extract colorado cities from us.cities <- us.cities[us.cities$country.etc == "CO", ] codf # select smaller subset of colorado cities # extract capitals from us.cities <- us.cities[us.cities$capital == 2,]capdf
Having obtained the relevant information, we setup a 1 \(\times\) 2 matrix of images with individual horizontal legends and an area for a common title. We create an image plot of NARCCAP data using the mercator projection and including grey state borders. The borders of Hawaii and Alaska are added using the
plines function. The state capitals are added to the image using the
ppoints function. The first image is then titled using the
title function. The legend is then added using the
autolegend function. Next, an image of the Colorado Aluminum measurements is created. The coordinates are projected using the Bonne projection, the color scheme is customized, grey county borders are added to the plot, but the grid lines are removed. The
ppoints function is then used to add locations for several Colorado cities to the image. The
ptext function is then used to add the names of these cities to the image. The second image is then titled using the
title function. The appropriate legend is then added using the
autolegend function. Lastly, a common title is added using the
# setup plotting area autolayout(c(1, 2), legend = "h", common.legend = FALSE, outer = TRUE)
## Warning in autolayout(c(1, 2), legend = "h", common.legend = FALSE, outer = TRUE): There is no room in the outer margin for an outer title. ## Setting par(oma = c(0, 0, 3, 0)).
# create image of NARCCAP data. # xlim is chosen so to include alaska and hawaii # add grey state borders pimage(lon, lat, tasmax[,,1], legend = "none", proj = "mercator", map = "state", xlim = c(-180, 20), lines.args = list(col = "grey"))
## Warning in paxes(xlim = c(-180, 20), ylim = c(20.5263919830322, ## 73.0147552490234: The x axis tick positions are not between -180 and 180, which ## creates problems with the mercator projection. Attempting to automatically ## correct the issue. The user may need to specify xaxp, or for more control, the ## xat argument of the paxes.args list.
# add hawaii and alaskan borders plines(hiak, proj = "mercator", col = "grey") # add state captials to image ppoints(capdf$lon, capdf$lat, proj = "mercator", pch = 16) # title image title("tasmax for North America") # add legend for plot autolegend() # load colorado geochemical data data(co, package = "gear") # create image for colorado aluminum measurements # use bonne projection # customize legend colors # add grey county borders # exclude grid pimage(co$lon, co$lat, co$Al, map = "county", legend = "none", proj = "bonne", parameters = 39, paxes.args = list(grid = FALSE), col = fields::tim.colors(64), lines.args = list(col = "grey"), xlab = "lon", ylab = "lat") # add colorado city points to image ppoints(codf$lon, codf$lat, pch = 16, proj = "bonne") # add names of colorado cities to image ptext(codf$lon, codf$lat, labels = codf$name, proj = "bonne", pos = 4) # title plot title("Colorado Aluminum levels (%)") # add legend to current image autolegend() # add common title for plots mtext("Two complicated maps", col = "purple", outer = TRUE, cex = 2)
The plots generated by the
autoimage functions can be customized in numerous ways by passing additional arguments through the
... argument of the functions. The customizations are mostly the same for both functions, so we illustrate these customizations using the
pimage function when possible for simplicity.
Lines or points can be added to each image by passing the
points arguments to the functions. Each argument should be a named list with
y components specifying the coordinates to join (for
lines) or plot for
points. Note that if multiple unconnected lines are to be drawn, then each line should be separated by an
NA value, similar to how maps are constructed in the maps package.
To illustrate usage of these arguments, we extract United States state boundaries from the maps package and reformat the
us.cities dataset from the maps package. Note that
statepoly is automatically a list with
y components, while this must be created manually for the
data(stateMapEnv, package = "maps") <- maps::map("state", plot = FALSE) statepoly <- list(x = us.cities$long, y = us.cities$lat)citylist
We now add these state lines and city locations to the image.
pimage(lon, lat, tasmax[,,1], lines = statepoly, points = citylist)
The appearance of the lines and points can be customized by passing the
points.args arguments through
.... Each argument should be a named list with components matching the arguments of the
points functions in the graphics package.
We change the appearance of the lines and points in the previous plot by specifying these arguments.
pimage(lon, lat, tasmax[,,1], lines = statepoly, points = citylist, lines.args = list(lwd = 2, lty = 3, col = "white"), points.args = list(pch = 20, col = "blue"))
Text can be added to each image by passing the
text argument through
text should be a named list with components
y, which specify the locations to draw the text, and
labels, which specifies the text to write at each location. The appearance of the text can be customized by passing the
text.args should be a named list with components matching the non-
labels arguments of the
text function in the graphics package.
We add the names and locations of two Colorado cities to the Colorado geochemical data.
= list(x = c(-104.98, -104.80), y = c(39.74, 38.85), citypoints labels = c("Denver", "Colorado Springs")) autoimage(co$lon, co$lat, co[,c("Al", "Ca")], common.legend = FALSE, main = c("Aluminum", "Cadmium"), points = citypoints, points.args = list(pch = 20, col = "white"), text = citypoints, text.args = list(pos = 3, col = "white"), xlab = "lon", ylab = "lat")
When projections are used, the grid lines do not always go as far as they should. Thus, axis customization is desired. Additionally, the appearance of the grid lines might need improving. The appears of the axis (and the locations of the grid lines) can be changed by passing
axis.args should be a named list with components matching the arguments of the
axis function in graphics. The exception is that
yat arguments are used instead of
at so that ticks on the x and y axes can be specified separately. The appearance of the grid lines can be changed by passing the desired changes through the
paxes.args argument. This is a named list with components matching the arguments in the
Consider the following poor graphic.
pimage(lon, lat, tasmax[,,1], proj = "bonne", parameters = 40)
The grid lines do not extend nearly far enough. There are only two tick marks on the y axis. The legend is too thin. We can add additional longer grid lines by specifying
axis.args. We can also further change the appearance of the axes via other components of
axis.args. We change the appearance of the grid lines by specifying choices in
paxes.args. We change the appearance of the legend by specifying choices in
legend.axis.args. We change the legend thickness by specifying
pimage(lon, lat, tasmax[,,1], proj = "bonne", parameters = 40, axis.args = list(yat = seq(-10, 70, by = 10), xat = seq(-220, 20, by = 20), col.axis = "darkgrey", cex.axis = 0.9), paxes.args = list(col = "grey", lty = 2), legend.axis.args = list(cex.axis = 0.9), lratio = 0.3)
The breaks and colors of the scale can be modified by specifying the
col arguments, as in the
image function in graphics. Additional changes can be made by specifying
legend.axis.args, a named list with components matching the arguments of the
axis function, which is used in creating the legend.
pimage(lon, lat, tasmax[,,1], col = colorspace::sequential_hcl(6, palette = "Plasma"), breaks = c(0, 275, 285, 295, 305, 315, 325), legend.axis.args = list(col.axis = "blue", las = 2, cex.axis = 0.75))
When non-gridded data are used, the settings for the gridded surface approximation can be passed through
... by specifying
interp.args, a named list with components matching the non-
xyz arguments of the
mba.surf function in the MBA package. We project the Colorado Aluminum measurements onto a finer grid in the following plot.
pimage(co$lon, co$lat, co$Al, interp.args = list(no.X = 100, no.Y = 100), xlab = "lon", ylab = "lat")
The appearance of
outer.title can be modified by passing
mtext.args should be a named list with components matching the arguments of
mtext, which is the function used to create the common title.
autoimage(lon, lat, tasmax, outer.title = "tasmax for 5 days", mtext.args = list(col = "blue", cex = 2))
## Warning in autolayout(size, legend = legend, common.legend = common.legend, : There is no room in the outer margin for an outer title. ## Setting par(oma = c(0, 0, 3, 0)).
The various options of the labeling, axes, and legend are largely independent. e.g., passing
... will not affect the axis unless it is passed as part of the named list
axis.args. However, one can set the various
par options prior to plotting to simultaneously affect the appearance of multiple aspects of the plot.
reset.par can be used to reset the graphics device options to their default values. We provide an example below.
par(cex.axis = 0.5, cex.lab = 0.5, mgp = c(1.5, 0.5, 0), mar = c(2.1, 2.1, 2.1, 0.2), col.axis = "orange", col.main = "blue", family = "mono") pimage(lon, lat, tasmax[,,1]) title("very customized plot")
Mearns, L.O., et al., 2007, updated 2012. The North American Regional Climate Change Assessment Program dataset, National Center for Atmospheric Research Earth System Grid data portal, Boulder, CO. Data downloaded 2016-08-12.
Mearns, L. O., W. J. Gutowski, R. Jones, L.-Y. Leung, S. McGinnis, A. M. B. Nunes, and Y. Qian: A regional climate change assessment program for North America. EOS, Vol. 90, No. 36, 8 September 2009, pp. 311-312.
D. Caya and R. Laprise. A semi-implicit semi-Lagrangian regional climate model: The Canadian RCM. Monthly Weather Review, 127(3):341–362, 1999.
M. Collins, B. B. Booth, G. R. Harris, J. M. Murphy, D. M. Sexton, and M. J. Webb. Towards quantifying uncertainty in transient climate change. Climate Dynamics, 27(2-3):127–147, 2006.