Plot: Plot: Fast, optimally arranged, multipanel plotting function with SpaDES

Description

The main plotting function accompanying SpaDES. This can take objects of type Raster*, SpatialPoints*, SpatialPolygons*, and any combination of those. It can also handle ggplot2 objects or base::histogram objects via call to exHist <- hist(1:10, plot = FALSE). Customization of the ggplot2 elements can be done as a normal ggplot2 plot, then added with Plot(ggplotObject).

Re-plot to a specific device

Usage

Plot(..., new = FALSE, addTo = NULL, gp = gpar(), gpText = gpar(),
  gpAxis = gpar(), axes = FALSE, speedup = 1, size = 5, cols = NULL,
  zoomExtent = NULL, visualSqueeze = NULL, legend = TRUE,
  legendRange = NULL, legendText = NULL, pch = 19, title = TRUE,
  na.color = "#FFFFFF00", zero.color = NULL, length = NULL)
## S3 method for class 'ANY':
Plot(..., new = FALSE, addTo = NULL, gp = gpar(),
  gpText = gpar(), gpAxis = gpar(), axes = FALSE, speedup = 1,
  size = 5, cols = NULL, zoomExtent = NULL, visualSqueeze = NULL,
  legend = TRUE, legendRange = NULL, legendText = NULL, pch = 19,
  title = TRUE, na.color = "#FFFFFF00", zero.color = NULL,
  length = NULL)
## S3 method for class 'simList':
Plot(..., new = FALSE, addTo = NULL, gp = gpar(),
  gpText = gpar(), gpAxis = gpar(), axes = FALSE, speedup = 1,
  size = 5, cols = NULL, zoomExtent = NULL, visualSqueeze = NULL,
  legend = TRUE, legendRange = NULL, legendText = NULL, pch = 19,
  title = TRUE, na.color = "#FFFFFF00", zero.color = NULL,
  length = NULL)
rePlot(toDev = dev.cur(), fromDev = dev.cur(), ...)

Arguments

...

A combination of spatialObjects or some non-spatial objects. See details.

new

Logical. If TRUE, then the previous plot is wiped and a new one made; if FALSE, then the ... plots will be added to the current device, adding or rearranging the plot layout as necessary. Default is FALSE

addTo

Character vector, with same length as .... This is for overplotting, when the overplot is not to occur on the plot with the same name, such as plotting a SpatialPoints* object on a RasterLayer.

A gpar object, created by gpar function, to change plotting parameters (see grid package).

gpText

A gpar object for the title text. Default gpar(col = "black").

gpAxis

A gpar object for the axes. Default gpar(col = "black").

axes

Logical or "L", representing the left and bottom axes, over all plots.

speedup

Numeric. The factor by which the number of pixels is divided by to plot rasters. See Details.

size

Numeric. The size, in points, for SpatialPoints symbols, if using a scalable symbol.

cols

Character vector or list of character vectors of colours. Default terrain.color(). See Details.

zoomExtent

An Extent object. Supplying a single extent that is smaller than the rasters will call a crop statement before plotting. Defaults to NULL. This occurs after any downsampling of rasters, so it may produce very pixelated maps.

visualSqueeze

Numeric. The proportion of the white space to be used for plots. Default is 0.75.

legend

Logical idicating whether a legend should be drawn. Default is TRUE.

legendRange

Numeric vector giving values that, representing the lower and upper bounds of a legend (i.e., 1:10 or c(1,10) will give same result) that will override the data bounds contained within the grobToPlot.

legendText

Character vector of legend value labels. Defaults to NULL, which results in a pretty numeric representation. If Raster* has a Raster Attribute Table (rat; see raster package), this

pch

see ?par.

title

Logical indicating whether the names of each plot should be written above plots.

na.color

Character string indicating the color for NA values. Default transparent.

zero.color

Character string indicating the color for zero values, when zero is the minimum value, otherwise, zero is treated as any other color. Default transparent.

length

Numeric. Optional length, in inches, of the arrow head.

toDev

Numeric. Which device should the new rePlot be plotted to. Default is current device.

fromDev

Numeric. Which device should the replot information be taken from. Default is current device

Value

Invisibly returns the .spadesPlot class object. If this is assigned to an object, say obj, then this can be plotted again with Plot(obj). This object is also stored in the locked .spadesEnv, so can simply be replotted with rePlot() or on a new device with rePlot(n), where n is the new device number.

Details

NOTE: Plot uses the grid package; therefore, it is NOT compatible with base R graphics. Also, because it does not by default wipe the plotting device before plotting, a call to clearPlot could be helpful to resolve many errors.

If new = TRUE, a new plot will be generated. This is equivalent to calling clearPlot(); Plot(Object), i.e,. directly before creating a new Plot. When new = FALSE, any plot that already exists will be overplotted, while plots that have not already been plotted will be added. This function rearranges the plotting device to maximize the size of all the plots, minimizing white space. If using the RStudio IDE, it is recommended to make and use a new device with dev(), because the built in device is not made for rapid redrawing. The function is based on the grid package.

Each panel in the multipanel plot must have a name. This name is used to overplot, rearrange the plots, or overlay using addTo when necessary. If the ... are named spatialObjects, then Plot will use these names. However, this name will not persist when there is a future call to Plot that forces a rearrangement of the plots. A more stable way is to use the object names directly, and any layer names (in the case of RasterLayer or RasterStack objects). If plotting a RasterLayer and the layer name is "layer" or the same as the object name, then, for simplicity, only the object name will be used. In other words, only enough information is used to uniquely identify the plot.

cols is a vector of colours that can be understood directly, or by colorRampePalette, such as c("orange", "blue"), will give a colour range from orange to blue, interploated. If a list, it will be used, in order, for each item to be plotted. It will be recycled if it is shorter than the objects to be plotted. Note that when this approach to setting colours is used, any overplotting will revert to the colortable slot of the object, or the default for rasters, which is terrain.color()

Silently, one hidden object is made, .spadesPlot in the .spadesEnv environment, which is used for arranging plots in the device window, and identifying the objects to be replotted if rearranging is required, subsequent to a new = FALSE additional plot.

This function is optimized to allow modular Plotting. This means that several behaviours will appear unusual. For instance, if a first call to Plot is made, the legend will reflect the current color scheme. If a second or subsequent call to Plot is made with the same object but with different colours (e.g., with cols), the legend will not update. This behaviour is made with the decision that the original layer takes precedence and all subsequent plots to that same frame are overplots only.

speedup is not a precise number because it is faster to plot an un-resampled raster if the new resampling is close to the original number of pixels. At the moment, for rasters, this is set to 1/3 of the original pixels. In other words, speedup will not do anything if the factor for speeding up is not high enough (i.e., >3). If no sub-sampling is desired, use a speedup value less than 0.1.

These gp* parameters will specify plot parameters that are available with gpar(). gp will adjust plot parameters, gpText will adjust title and legend text, gpAxis will adjust the axes. size adjusts point size in a SpatialPoints object. These will persist with the original Plot call for each individual object. Multiple entries can be used, but they must be named list elements and they must match the ... items to plot. This is true for a RasterStack also, i.e., the list of named elements must be the same length as the number of layers being plotted. The naming convention used is: RasterStackName$layerName, i.e, landscape$DEM.

Examples

Run this code

library(sp)
library(raster)
library(rgdal)
library(igraph)
library(RColorBrewer)
# Make list of maps from package database to load, and what functions to use to load them
filelist <-
   data.frame(files =
     dir(file.path(
       find.package("SpaDES", quiet = FALSE), "maps"),
       full.names = TRUE, pattern= "tif"),
     functions = "rasterToMemory",
     packages = "SpaDES",
     stringsAsFactors = FALSE)

# Load files to memory (using rasterToMemory)
mySim <- loadFiles(filelist = filelist)

# put layers into a single stack for convenience
landscape <- stack(mySim$DEM, mySim$forestCover, mySim$forestAge,
   mySim$habitatQuality, mySim$percentPine)

# can change color palette
setColors(landscape, n = 50) <- list(DEM=topo.colors(50),
                           forestCover = brewer.pal(9, "Set1"),
                           forestAge = brewer.pal("Blues", n=8),
                           habitatQuality = brewer.pal(9, "Spectral"),
                           percentPine = brewer.pal("GnBu", n=8))

# Make a new raster derived from a previous one; must give it a unique name
habitatQuality2 <- landscape$habitatQuality ^ 0.3
names(habitatQuality2) <- "habitatQuality2"

# make a SpatialPoints object
caribou <- cbind(x = stats::runif (1e2, -50, 50), y = stats::runif (1e2, -50, 50)) %>%
  SpatialPoints(coords = .)

\notrun{
dev(2)
}
Plot(landscape, new = TRUE)

# Can overplot, using addTo
Plot(caribou, addTo = "landscape$forestAge", size = 4, axes = FALSE)

# can add a plot to the plotting window
Plot(caribou, new = FALSE)

# Can add two maps with same name, if one is in a stack; they are given
#  unique names based on object name
Plot(landscape, caribou, mySim$DEM)

# can mix stacks, rasters, SpatialPoint*
Plot(landscape, habitatQuality2, caribou)

# can mix stacks, rasters, SpatialPoint*, and SpatialPolygons*
Plot(landscape, caribou)
Plot(habitatQuality2, new = FALSE)
Sr1 = Polygon(cbind(c(2, 4, 4, 1, 2), c(2, 3, 5, 4, 2))*20-50)
Sr2 = Polygon(cbind(c(5, 4, 2, 5), c(2, 3, 2, 2))*20-50)
Srs1 = Polygons(list(Sr1), "s1")
Srs2 = Polygons(list(Sr2), "s2")
SpP = SpatialPolygons(list(Srs1, Srs2), 1:2)
Plot(SpP)
Plot(SpP, addTo = "landscape$forestCover", gp = gpar(lwd = 2))

Run the code above in your browser using DataLab