Title: | A System of Plotting Optimized for Speed and Modularity |
---|---|
Description: | A high-level plotting system, compatible with `ggplot2` objects, maps from `sf`, `terra`, `raster`, `sp`. It is built primarily on the 'grid' package. The objective of the package is to provide a plotting system that is built for speed and modularity. This is useful for quick visualizations when testing code and for plotting multiple figures to the same device from independent sources that may be independent of one another (i.e., different function or modules the create the visualizations). The suggested package 'fastshp' can be installed from the repository (<https://PredictiveEcology.r-universe.dev>). |
Authors: | Eliot J B McIntire [aut, cre] , Alex M Chubaty [aut] , His Majesty the King in Right of Canada, as represented by the Minister of Natural Resources Canada [cph] |
Maintainer: | Eliot J B McIntire <[email protected]> |
License: | GPL-3 |
Version: | 1.0.2.9003 |
Built: | 2024-10-07 05:34:34 UTC |
Source: | https://github.com/PredictiveEcology/quickPlot |
quickPlot
packageA high-level plotting system, built using 'grid' graphics, that is optimized for speed and modularity. This has great utility for quick visualizations when testing code, with the key benefit that visualizations are updated independently of one another.
The suggested package fastshp can be installed with
install.packages("fastshp", repos = "https://rforge.net", type = "source")
.
Maintainer: Eliot J B McIntire [email protected] (ORCID)
Authors:
Alex M Chubaty [email protected] (ORCID)
Other contributors:
His Majesty the King in Right of Canada, as represented by the Minister of Natural Resources Canada [copyright holder]
Useful links:
Report bugs at https://github.com/PredictiveEcology/quickPlot/issues
bbox
methodFor internal use only.
.hasBbox(z, objClass, objName, objEnv)
.hasBbox(z, objClass, objName, objEnv)
z |
Logical, whether this object is a |
objClass |
The class of the object |
objName |
The character string name of the object |
objEnv |
The environment where the object can be found |
This is a generic definition that can be extended according to class. Intended only for development use.
.parseElems(tmp, elems, envir) ## S4 method for signature 'ANY' .parseElems(tmp, elems, envir)
.parseElems(tmp, elems, envir) ## S4 method for signature 'ANY' .parseElems(tmp, elems, envir)
tmp |
A evaluated object |
elems |
A character string to be parsed |
envir |
An environment |
An object, parsed from a character string and and environment
Eliot McIntire
Under some conditions, a device and its metadata need to be cleared manually.
This can be done with either the new = TRUE
argument within the call to Plot
.
Sometimes, the metadata of a previous plot will prevent correct plotting of
a new Plot
call.
Use clearPlot
to clear the device and all the associated metadata manually.
clearPlot( dev = dev.cur(), removeData = TRUE, force = FALSE, verbose = getOption("quickPlot.verbose") ) ## S4 method for signature 'numeric,logical' clearPlot( dev = dev.cur(), removeData = TRUE, force = FALSE, verbose = getOption("quickPlot.verbose") ) ## S4 method for signature 'numeric,missing' clearPlot(dev, force) ## S4 method for signature 'missing,logical' clearPlot(removeData, force) ## S4 method for signature 'missing,missing' clearPlot(dev, removeData, force)
clearPlot( dev = dev.cur(), removeData = TRUE, force = FALSE, verbose = getOption("quickPlot.verbose") ) ## S4 method for signature 'numeric,logical' clearPlot( dev = dev.cur(), removeData = TRUE, force = FALSE, verbose = getOption("quickPlot.verbose") ) ## S4 method for signature 'numeric,missing' clearPlot(dev, force) ## S4 method for signature 'missing,logical' clearPlot(removeData, force) ## S4 method for signature 'missing,missing' clearPlot(dev, removeData, force)
dev |
Numeric. Device number to clear. |
removeData |
Logical indicating whether any data that was stored in the
|
force |
Logical or "all". Sometimes the graphics state cannot be fixed by a simple
|
verbose |
Numeric or logical. If |
Eliot McIntire
if (interactive()) { Plot(1:10) clearPlot() # clears }
if (interactive()) { Plot(1:10) clearPlot() # clears }
This will extract using terra::crds
, sf::st_coordinates
and
raster::coordinates
. Other packages can create methods, as this is
generic.
## S4 method for signature 'ANY' coordinates(obj, ...)
## S4 method for signature 'ANY' coordinates(obj, ...)
obj |
An object from which to extract the coordinates (e.g., |
... |
Ignored. |
A 2 column matrix of coordinates (x and y)
library(terra) caribou <- terra::vect(x = cbind(x = stats::runif(1e1, -50, 50), y = stats::runif(1e1, -50, 50))) coordinates(caribou)
library(terra) caribou <- terra::vect(x = cbind(x = stats::runif(1e1, -50, 50), y = stats::runif(1e1, -50, 50))) coordinates(caribou)
Switch to an existing plot device, or if not already open,
launch a new graphics device based on operating system used.
On Windows and macOS, if x
is not provided, this will open or switch to the first
non-RStudio device, which is much faster than the ‘png’-based RStudio plot device.
Currently, this will not open anything new.
dev(x, ..., verbose = getOption("quickPlot.verbose"))
dev(x, ..., verbose = getOption("quickPlot.verbose"))
x |
The number of a plot device. If missing, will open a new non-RStudio plotting device |
... |
Additional arguments passed to |
verbose |
Numeric or logical. If |
For example, dev(6)
switches the active plot device to device 6.
If it does not exist, it opens it. If devices 1-5 don't exist they will be opened too.
Opens a new plot device on the screen. Invisibly returns the device number selected.
Eliot McIntire and Alex Chubaty
## Not run: dev(4) ## End(Not run)
## Not run: dev(4) ## End(Not run)
Creates a palette for the current session for a divergent-colour graphic with a non-symmetric range. Based on ideas from Maureen Kennedy, Nick Povak, and Alina Cansler.
divergentColors( start.color, end.color, min.value, max.value, mid.value = 0, mid.color = "white" ) ## S4 method for signature 'character,character,numeric,numeric' divergentColors( start.color, end.color, min.value, max.value, mid.value = 0, mid.color = "white" )
divergentColors( start.color, end.color, min.value, max.value, mid.value = 0, mid.color = "white" ) ## S4 method for signature 'character,character,numeric,numeric' divergentColors( start.color, end.color, min.value, max.value, mid.value = 0, mid.color = "white" )
start.color |
Start colour to be passed to |
end.color |
End colour to be passed to |
min.value |
Numeric minimum value corresponding to |
max.value |
Numeric maximum value corresponding to |
mid.value |
Numeric middle value corresponding to |
mid.color |
Middle colour to be passed to |
A diverging colour palette.
Eliot McIntire and Alex Chubaty
divergentColors("darkred", "darkblue", -10, 10, 0, "white")
divergentColors("darkred", "darkblue", -10, 10, 0, "white")
Assess whether a list of extents are all equal
equalExtent(extents) ## S4 method for signature 'list' equalExtent(extents)
equalExtent(extents) ## S4 method for signature 'list' equalExtent(extents)
extents |
list of extents objects |
Eliot McIntire
library(terra) files <- system.file("maps", package = "quickPlot") files <- dir(files, full.names = TRUE, pattern = "tif") maps <- lapply(files, function(x) terra::rast(x)) names(maps) <- sapply(basename(files), function(x) { strsplit(x, split = "\\.")[[1]][1] }) extnts <- lapply(maps, terra::ext) equalExtent(extnts) ## TRUE
library(terra) files <- system.file("maps", package = "quickPlot") files <- dir(files, full.names = TRUE, pattern = "tif") maps <- lapply(files, function(x) terra::rast(x)) names(maps) <- sapply(basename(files), function(x) { strsplit(x, split = "\\.")[[1]][1] }) extnts <- lapply(maps, terra::ext) equalExtent(extnts) ## TRUE
This is a wrapper around terra::ext
, sf::st_bbox
, and
raster::extent
.
## S4 method for signature 'ANY' extent(x, ...)
## S4 method for signature 'ANY' extent(x, ...)
x |
The spatial object from which to extract the extent. |
... |
Not used. |
Returns a list of length 4 with elements xmin
, xmax
, ymin
, and ymax
,
in that order.
Raster*
objectsGet and set colours for plotting Raster*
objects
setColors
works as a replacement method or a normal function call.
This function can accept RColorBrewer
colours by name. See examples.
getColors(object) setColors(object, ..., n, verbose = getOption("quickPlot.verbose")) <- value setColors(object, value, n, verbose = getOption("quickPlot.verbose"))
getColors(object) setColors(object, ..., n, verbose = getOption("quickPlot.verbose")) <- value setColors(object, value, n, verbose = getOption("quickPlot.verbose"))
object |
A |
... |
Additional arguments to |
n |
An optional vector of values specifying the number of levels from which to interpolate the colour palette. |
verbose |
Numeric or logical. If |
value |
Named list of hex colour codes (e.g., from
|
Returns a named list of colours.
Returns a Raster with the colortable
slot set to values
.
Alex Chubaty
setColors<-()
, brewer.pal()
, RColorBrewer::ColorBrewer
brewer.pal()
, RColorBrewer::ColorBrewer
,
colorRampPalette()
.
library(terra) ras <- rast(matrix(c(0, 0, 1, 2), ncol = 2, nrow = 2)) getColors(ras) ## none # Use replacement method setColors(ras, n = 3) <- c("red", "blue", "green") getColors(ras) clearPlot() Plot(ras) # Use function method ras <- setColors(ras, n = 3, c("red", "blue", "yellow")) getColors(ras) clearPlot() Plot(ras) # Using the wrong number of colors, e.g., here 2 provided, # for a raster with 3 values... causes interpolation, which may be surprising ras <- setColors(ras, c("red", "blue")) clearPlot() Plot(ras) # Real number rasters - interpolation is used ras <- rast(matrix(runif(9), ncol = 3, nrow = 3)) |> setColors(c("red", "yellow")) # interpolates when real numbers, gives warning clearPlot() Plot(ras) # Factor rasters, can be contiguous (numerically) or not, in this case not: ras <- rast(matrix(sample(c(1, 3, 6), size = 9, replace = TRUE), ncol = 3, nrow = 3)) levels(ras) <- data.frame(ID = c(1, 3, 6), Names = c("red", "purple", "yellow")) ras <- setColors(ras, n = 3, c("red", "purple", "yellow")) getColors(ras) clearPlot() Plot(ras) # if a factor raster, and not enough labels are provided, then a warning # will be given, and colors will be interpolated # The level called purple is not purple, but interpolated betwen red and yellow suppressWarnings({ ras <- setColors(ras, c("red", "yellow")) clearPlot() Plot(ras) }) # use RColorBrewer colors setColors(ras) <- "Reds" clearPlot() Plot(ras)
library(terra) ras <- rast(matrix(c(0, 0, 1, 2), ncol = 2, nrow = 2)) getColors(ras) ## none # Use replacement method setColors(ras, n = 3) <- c("red", "blue", "green") getColors(ras) clearPlot() Plot(ras) # Use function method ras <- setColors(ras, n = 3, c("red", "blue", "yellow")) getColors(ras) clearPlot() Plot(ras) # Using the wrong number of colors, e.g., here 2 provided, # for a raster with 3 values... causes interpolation, which may be surprising ras <- setColors(ras, c("red", "blue")) clearPlot() Plot(ras) # Real number rasters - interpolation is used ras <- rast(matrix(runif(9), ncol = 3, nrow = 3)) |> setColors(c("red", "yellow")) # interpolates when real numbers, gives warning clearPlot() Plot(ras) # Factor rasters, can be contiguous (numerically) or not, in this case not: ras <- rast(matrix(sample(c(1, 3, 6), size = 9, replace = TRUE), ncol = 3, nrow = 3)) levels(ras) <- data.frame(ID = c(1, 3, 6), Names = c("red", "purple", "yellow")) ras <- setColors(ras, n = 3, c("red", "purple", "yellow")) getColors(ras) clearPlot() Plot(ras) # if a factor raster, and not enough labels are provided, then a warning # will be given, and colors will be interpolated # The level called purple is not purple, but interpolated betwen red and yellow suppressWarnings({ ras <- setColors(ras, c("red", "yellow")) clearPlot() Plot(ras) }) # use RColorBrewer colors setColors(ras) <- "Reds" clearPlot() Plot(ras)
Currently only the gpar
function is imported. This is a convenience so that users
can change Plot
arguments without having to load the entire grid package.
gpar(...)
gpar(...)
... |
Any number of named arguments. |
Determine if current session is RStudio Server
isRstudioServer()
isRstudioServer()
isRstudioServer() # returns FALSE or TRUE
isRstudioServer() # returns FALSE or TRUE
There are already methods for Raster*
objects. This adds methods for
SpatialPoints*
, SpatialLines*
, and SpatialPolygons*
,
returning an empty character vector of length 1.
This function was created to give consistent, meaningful results for all
classes of objects plotted by Plot
.
layerNames(object) ## S4 method for signature 'ANY' layerNames(object)
layerNames(object) ## S4 method for signature 'ANY' layerNames(object)
object |
A |
Eliot McIntire
library(terra) ## RasterLayer objects files <- system.file("maps", package = "quickPlot") files <- dir(files, full.names = TRUE, pattern = "tif") maps <- lapply(files, function(x) terra::rast(x)) names(maps) <- sapply(basename(files), function(x) { strsplit(x, split = "\\.")[[1]][1] }) layerNames(maps) ## SpatVector objects caribou <- terra::vect(cbind(x = stats::runif(1e2, -50, 50), y = stats::runif(1e2, -50, 50))) layerNames(caribou)
library(terra) ## RasterLayer objects files <- system.file("maps", package = "quickPlot") files <- dir(files, full.names = TRUE, pattern = "tif") maps <- lapply(files, function(x) terra::rast(x)) names(maps) <- sapply(basename(files), function(x) { strsplit(x, split = "\\.")[[1]][1] }) layerNames(maps) ## SpatVector objects caribou <- terra::vect(cbind(x = stats::runif(1e2, -50, 50), y = stats::runif(1e2, -50, 50))) layerNames(caribou)
SpatialLines
object from two SpatialPoints
objectsThe primary conceived usage of this is to draw arrows following the trajectories of agents.
makeLines(from, to)
makeLines(from, to)
from |
Starting spatial coordinates ( |
to |
Ending spatial coordinates ( |
A SpatialLines
object. When this object is used within a
Plot
call and the length
argument is specified, then
arrow heads will be drawn. See examples.
Eliot McIntire
library(terra) # Make 2 objects caribou1 <- terra::vect(cbind(x = stats::runif(10, -50, 50), y = stats::runif(10, -50, 50))) caribou2 <- terra::vect(cbind(x = stats::runif(10, -50, 50), y = stats::runif(10, -50, 50))) caribouTraj <- makeLines(caribou1, caribou2) if (interactive()) Plot(caribouTraj, length = 0.1) # shows arrows # or to a previous Plot files <- dir(system.file("maps", package = "quickPlot"), full.names = TRUE, pattern = "tif") maps <- lapply(files, terra::rast) names(maps) <- lapply(maps, names) caribouTraj <- makeLines(caribou1, caribou2) if (interactive()) { clearPlot() Plot(maps$DEM) Plot(caribouTraj, addTo = "maps$DEM", length = 0.1) }
library(terra) # Make 2 objects caribou1 <- terra::vect(cbind(x = stats::runif(10, -50, 50), y = stats::runif(10, -50, 50))) caribou2 <- terra::vect(cbind(x = stats::runif(10, -50, 50), y = stats::runif(10, -50, 50))) caribouTraj <- makeLines(caribou1, caribou2) if (interactive()) Plot(caribouTraj, length = 0.1) # shows arrows # or to a previous Plot files <- dir(system.file("maps", package = "quickPlot"), full.names = TRUE, pattern = "tif") maps <- lapply(files, terra::rast) names(maps) <- lapply(maps, names) caribouTraj <- makeLines(caribou1, caribou2) if (interactive()) { clearPlot() Plot(maps$DEM) Plot(caribouTraj, addTo = "maps$DEM", length = 0.1) }
Open a new plotting window
newPlot(noRStudioGD = TRUE, ..., verbose = getOption("quickPlot.verbose")) dev.useRSGD(useRSGD = FALSE)
newPlot(noRStudioGD = TRUE, ..., verbose = getOption("quickPlot.verbose")) dev.useRSGD(useRSGD = FALSE)
noRStudioGD |
Logical Passed to |
... |
Additional arguments. |
verbose |
Numeric or logical. If |
useRSGD |
Logical indicating whether the default device should be the
RStudio graphic device, or the platform default ( |
dev.new()
is supposed to be the correct way to open a new
window in a platform-generic way; however, does not work in RStudio
(SpaDES#116).
Use dev.useRSGD(FALSE)
to avoid RStudio for the remainder of this session,
and dev.useRSGD(TRUE)
to use the RStudio graphics device.
(This sets the default device via the device
option.)
Eliot McIntire and Alex Chubaty
## Not run: ## set option to avoid using Rstudio graphics device dev.useRSGD(FALSE) ## open new plotting window newPlot() ## End(Not run)
## Not run: ## set option to avoid using Rstudio graphics device dev.useRSGD(FALSE) ## open new plotting window newPlot() ## End(Not run)
A unified function for raster::nlayers
, terra::nlyrs
, or lists of these.
Default function returns 1L
for all other classes.
numLayers(x)
numLayers(x)
x |
An object or list of objects. |
The number of layers in the object.
Eliot McIntire
library(terra) files <- system.file("maps", package = "quickPlot") files <- dir(files, full.names = TRUE, pattern = "tif") maps <- lapply(files, function(x) rast(x)) names(maps) <- sapply(basename(files), function(x) { strsplit(x, split = "\\.")[[1]][1] }) stck <- rast(maps) numLayers(maps) numLayers(stck)
library(terra) files <- system.file("maps", package = "quickPlot") files <- dir(files, full.names = TRUE, pattern = "tif") maps <- lapply(files, function(x) rast(x)) names(maps) <- sapply(basename(files), function(x) { strsplit(x, split = "\\.")[[1]][1] }) stck <- rast(maps) numLayers(maps) numLayers(stck)
Plot
: Fast, optimally arranged, multi-panel plottingThis can take objects of type Raster*
, SpatialPoints*
, SpatialPolygons*
,
and any combination of those.
These can be provided as individual objects, or a named list.
If a named list, the names either represent a different original object in the
calling environment and that will be used, or if the names don't exist in the
calling environment, then they will be copied to .quickPlotEnv
for reuse later.
It can also handle ggplot2
objects or base::histogram
objects
created via call to exHist <- hist(1:10, plot = FALSE)
. It can also take
arguments as if it were a call to plot
. In this latter
case, the user should be explicit about naming the plot area using addTo
.
Customization of the ggplot2
elements can be done as a normal
ggplot2
plot, then added with Plot(ggplotObject)
.
Plot( ..., new = FALSE, addTo = NULL, gp = gpar(), gpText = gpar(), gpAxis = gpar(), axes = FALSE, speedup = 1, size = 5, cols = NULL, col = NULL, zoomExtent = NULL, visualSqueeze = NULL, legend = TRUE, legendRange = NULL, legendText = NULL, pch = 19, title = NULL, na.color = "#FFFFFF00", zero.color = NULL, length = NULL, arr = NULL, plotFn = "plot", verbose = getOption("quickPlot.verbose") ) ## S4 method for signature 'ANY' Plot( ..., new = FALSE, addTo = NULL, gp = gpar(), gpText = gpar(), gpAxis = gpar(), axes = FALSE, speedup = 1, size = 5, cols = NULL, col = NULL, zoomExtent = NULL, visualSqueeze = NULL, legend = TRUE, legendRange = NULL, legendText = NULL, pch = 19, title = NULL, na.color = "#FFFFFF00", zero.color = NULL, length = NULL, arr = NULL, plotFn = "plot", verbose = getOption("quickPlot.verbose") ) rePlot( toDev = dev.cur(), fromDev = dev.cur(), clearFirst = TRUE, ..., verbose = getOption("quickPlot.verbose") )
Plot( ..., new = FALSE, addTo = NULL, gp = gpar(), gpText = gpar(), gpAxis = gpar(), axes = FALSE, speedup = 1, size = 5, cols = NULL, col = NULL, zoomExtent = NULL, visualSqueeze = NULL, legend = TRUE, legendRange = NULL, legendText = NULL, pch = 19, title = NULL, na.color = "#FFFFFF00", zero.color = NULL, length = NULL, arr = NULL, plotFn = "plot", verbose = getOption("quickPlot.verbose") ) ## S4 method for signature 'ANY' Plot( ..., new = FALSE, addTo = NULL, gp = gpar(), gpText = gpar(), gpAxis = gpar(), axes = FALSE, speedup = 1, size = 5, cols = NULL, col = NULL, zoomExtent = NULL, visualSqueeze = NULL, legend = TRUE, legendRange = NULL, legendText = NULL, pch = 19, title = NULL, na.color = "#FFFFFF00", zero.color = NULL, length = NULL, arr = NULL, plotFn = "plot", verbose = getOption("quickPlot.verbose") ) rePlot( toDev = dev.cur(), fromDev = dev.cur(), clearFirst = TRUE, ..., verbose = getOption("quickPlot.verbose") )
... |
A combination of |
new |
Logical. If |
addTo |
Character vector, with same length as |
gp |
A |
gpText |
A |
gpAxis |
A |
axes |
Logical or |
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 |
cols |
(also |
col |
(also |
zoomExtent |
An |
visualSqueeze |
Numeric. The proportion of the white space to be used for plots. Default is 0.75. |
legend |
Logical indicating whether a legend should be drawn.
Default is |
legendRange |
Numeric vector giving values that, representing the lower
and upper bounds of a legend (i.e., |
legendText |
Character vector of legend value labels.
Defaults to |
pch |
see |
title |
Logical or character string. If logical, it
indicates whether to print the object name as the title
above the plot. If a character string, it will print this
above the plot. NOTE: the object name is used with |
na.color |
Character string indicating the colour for |
zero.color |
Character string indicating the colour for zero values, when zero is the minimum value, otherwise, zero is treated as any other colour. Default transparent. |
length |
Numeric. Optional length, in inches, of the arrow head. |
arr |
A vector of length 2 indicating a desired arrangement of plot areas indicating number of rows, number of columns. Default NULL, meaning let Plot function do it automatically. |
plotFn |
An optional function name to do the plotting internally, e.g., "barplot" to get a barplot() call. Default "plot". |
verbose |
Numeric or logical. If |
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 |
clearFirst |
Logical. Should |
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()
is helpful to resolve
many errors. Careful use of the other device tools, such as dev.off()
and
dev.list()
might also clear problems that may arise.
If new = TRUE
, a new plot will be generated, but only in the figure region that
has the same name as the object being plotted.
This is different than calling clearPlot(); Plot(Object)
,
i.e,. directly before creating a new Plot. clearPlot()
will clear the entire
plotting device.
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.
For modularity, Plot
must have access to the original objects that were plotted.
These objects will be used if a subsequent Plot event forces a rearrangement of the plot device.
Rather than saving all the plot information (including the data) at each Plot
call
(this is generally too much data to constantly make copies),
the function saves a pointer to the original R object. If the plot needs
to be rearranged because of a future addition, then Plot
will search for that
original object that created the first plots, and replot them.
This has several consequences.
First, that object must still exist and in the same environment.
Second, if that object has changed between the first time it is plot and any
subsequent time it is replotted (via a forced rearrangement), then it will take
the object as it exists, not as it existed. Third, if passing a named list
of objects, Plot will either create a link to objects with those names in the
calling environment (e.g., .GlobalEnv
) or, if they do not exist, then Plot
will make a copy in the hidden .quickPlotEnv
for later reuse.
cols
is a vector of colours that can be understood directly, or by
colorRampPalette()
, such as c("orange", "blue")
,
will give a colour range from orange to blue, interpolated.
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()
cols
can also accept RColorBrewer
colours by keyword if it is
character vector of length 1. i.e., this cannot be used to set many objects by keyword in
the same Plot call. Default terrain.color()
. See Details.
Some colouring will be automatic. If the object being plotted is a Raster, then
this will take the colorTable
slot (can be changed via setColors()
or other ways).
If this is a SpatialPointsDataFrame
, this function will use a column called colors
and apply these to the symbols.
For SpatialPolygons
, cols
can accept RColorBrewer
colours by keyword as a
character vector of length 1. For more control, pass a vector of colours to cols
or
to gp = gpar(fill = vectorOfColours)
.
In this second approach, the length of the vectorOfColours
can be either less then or equal
to the number of polygons in the SpatialPolygons
object – each polygon within
a Polygons
object will share the same colour – or it can be greater than this number
to give a different colour to each Polygon
(of which there can be MANY more than
Polygons
. Plot
will recycle these colours if there are not enough. The order
provided will be the order assigned to each Polygons
or Polygon
object.
Silently, one hidden object is made, .quickPlot
in the
.quickPlotEnv
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 colour 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 over-plots only.
speedup
is not a precise number because it is faster to plot an
non-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
.
Invisibly returns the .quickPlot
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 .quickPlotEnv
, so can simply be
replotted with rePlot()
or on a new device with rePlot(n)
,
where n
is the new device number.
Eliot McIntire
clearPlot()
, rePlot()
, gpar()
, raster::raster()
,
par()
, sp::SpatialPolygons()
, grid.polyline()
,
ggplot2::ggplot()
, dev()
, terra::vect()
, terra::rast()
if (requireNamespace("RColorBrewer") && interactive()) { library(terra) files <- dir(system.file("maps", package = "quickPlot"), full.names = TRUE, pattern = "tif") maps <- lapply(files, rast) names(maps) <- lapply(maps, names) # put layers into a single stack for convenience landscape <- rast(maps) # can change color palette setColors(landscape, n = 50) <- list(DEM = topo.colors(50), forestCover = RColorBrewer::brewer.pal(9, "Set1"), forestAge = RColorBrewer::brewer.pal("Blues", n = 8), habitatQuality = RColorBrewer::brewer.pal(9, "Spectral"), percentPine = RColorBrewer::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 <- terra::vect(cbind(x = stats::runif(1e2, -50, 50), y = stats::runif(1e2, -50, 50))) # use factor raster to give legends as character strings ras <- rast(ext(0, 3, 0, 4), vals = sample(1:4, size = 12, replace = TRUE), res = 1) # needs to have a data.frame with ID as first column - see ?raster::ratify levels(ras) <- data.frame(ID = 1:4, Name = paste0("Level", 1:4)) Plot(ras, new = TRUE) # Arbitrary values for factors, including zero and not all levels represented in raster levs <- c(0:5, 7:12) ras <- rast(ext(0, 3, 0, 2), vals = c(1, 1, 3, 5, 8, 9), res = 1) levels(ras) <- data.frame(ID = levs, Name = LETTERS[c(1:3, 8:16)]) Plot(ras, new = TRUE) # Arbitrary values for factors, including zero and not all levels represented in raster levs <- c(0:5, 7:23) ras <- rast(ext(0, 3, 0, 2), vals = c(1, 1, 3, 5, 8, 9), res = 1) levels(ras) <- data.frame(ID = levs, Name = LETTERS[1:23]) Plot(ras, new = TRUE) # SpatialPolygons sr1 <- cbind(object = 1, cbind(c(2, 4, 4, 1, 2), c(2, 3, 5, 4, 2)) * 20 - 50) sr2 <- cbind(object = 2, cbind(c(5, 4, 2, 5), c(2, 3, 2, 2)) * 20 - 50) spP <- vect(rbind(sr1, sr2)) clearPlot() Plot(ras) clearPlot() Plot(landscape) # 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, maps$DEM) # can mix SpatRaster, SpatVector, RasterStack, RasterLayer, Spatial* Plot(landscape, habitatQuality2, caribou) # can mix stacks, rasters, SpatialPoint*, and SpatialPolygons* Plot(landscape, caribou) Plot(habitatQuality2, new = FALSE) Plot(spP) Plot(spP, addTo = "landscape$forestCover", gp = gpar(lwd = 2)) # provide manual arrangement, NumRow, NumCol Plot(landscape, spP, arr = c(2, 5), new = TRUE) # example base plot clearPlot() Plot(1:10, 1:10, addTo = "test", new = TRUE) # if there is no "test" then it will make it Plot(4, 5, pch = 22, col = "blue", addTo = "test") obj1 <- rnorm(1e2) Plot(obj1, axes = "L") # Can plot named lists of objects (but not base objects yet) ras1 <- ras2 <- ras a <- list() for (i in 1:2) { a[[paste0("ras", i)]] <- get(paste0("ras", i)) } a$spP <- spP clearPlot() Plot(a) # Now all together Plot(obj1, title = "scatterplot") Plot(landscape) # do with sf --> these will add to previous plots if (requireNamespace("sf", quietly = TRUE)) { caribouSF <- sf::st_as_sf(caribou) Plot(caribouSF, axes = "L") Plot(caribouSF, addTo = "landscape$percentPine") # overlay on a specific plot } # clean up clearPlot() }
if (requireNamespace("RColorBrewer") && interactive()) { library(terra) files <- dir(system.file("maps", package = "quickPlot"), full.names = TRUE, pattern = "tif") maps <- lapply(files, rast) names(maps) <- lapply(maps, names) # put layers into a single stack for convenience landscape <- rast(maps) # can change color palette setColors(landscape, n = 50) <- list(DEM = topo.colors(50), forestCover = RColorBrewer::brewer.pal(9, "Set1"), forestAge = RColorBrewer::brewer.pal("Blues", n = 8), habitatQuality = RColorBrewer::brewer.pal(9, "Spectral"), percentPine = RColorBrewer::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 <- terra::vect(cbind(x = stats::runif(1e2, -50, 50), y = stats::runif(1e2, -50, 50))) # use factor raster to give legends as character strings ras <- rast(ext(0, 3, 0, 4), vals = sample(1:4, size = 12, replace = TRUE), res = 1) # needs to have a data.frame with ID as first column - see ?raster::ratify levels(ras) <- data.frame(ID = 1:4, Name = paste0("Level", 1:4)) Plot(ras, new = TRUE) # Arbitrary values for factors, including zero and not all levels represented in raster levs <- c(0:5, 7:12) ras <- rast(ext(0, 3, 0, 2), vals = c(1, 1, 3, 5, 8, 9), res = 1) levels(ras) <- data.frame(ID = levs, Name = LETTERS[c(1:3, 8:16)]) Plot(ras, new = TRUE) # Arbitrary values for factors, including zero and not all levels represented in raster levs <- c(0:5, 7:23) ras <- rast(ext(0, 3, 0, 2), vals = c(1, 1, 3, 5, 8, 9), res = 1) levels(ras) <- data.frame(ID = levs, Name = LETTERS[1:23]) Plot(ras, new = TRUE) # SpatialPolygons sr1 <- cbind(object = 1, cbind(c(2, 4, 4, 1, 2), c(2, 3, 5, 4, 2)) * 20 - 50) sr2 <- cbind(object = 2, cbind(c(5, 4, 2, 5), c(2, 3, 2, 2)) * 20 - 50) spP <- vect(rbind(sr1, sr2)) clearPlot() Plot(ras) clearPlot() Plot(landscape) # 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, maps$DEM) # can mix SpatRaster, SpatVector, RasterStack, RasterLayer, Spatial* Plot(landscape, habitatQuality2, caribou) # can mix stacks, rasters, SpatialPoint*, and SpatialPolygons* Plot(landscape, caribou) Plot(habitatQuality2, new = FALSE) Plot(spP) Plot(spP, addTo = "landscape$forestCover", gp = gpar(lwd = 2)) # provide manual arrangement, NumRow, NumCol Plot(landscape, spP, arr = c(2, 5), new = TRUE) # example base plot clearPlot() Plot(1:10, 1:10, addTo = "test", new = TRUE) # if there is no "test" then it will make it Plot(4, 5, pch = 22, col = "blue", addTo = "test") obj1 <- rnorm(1e2) Plot(obj1, axes = "L") # Can plot named lists of objects (but not base objects yet) ras1 <- ras2 <- ras a <- list() for (i in 1:2) { a[[paste0("ras", i)]] <- get(paste0("ras", i)) } a$spP <- spP clearPlot() Plot(a) # Now all together Plot(obj1, title = "scatterplot") Plot(landscape) # do with sf --> these will add to previous plots if (requireNamespace("sf", quietly = TRUE)) { caribouSF <- sf::st_as_sf(caribou) Plot(caribouSF, axes = "L") Plot(caribouSF, addTo = "landscape$percentPine") # overlay on a specific plot } # clean up clearPlot() }
quickPlot
classesquickPlot
uses S4 classes.
"Dot" classes are not exported and are therefore intended for internal use only.
Plot
New classes | |
.arrangement() |
The layout or "arrangement" of plot objects |
.quickPlot() |
Main class for Plot - contains .quickGrob
and .arrangement objects |
.quickPlotGrob() |
GRaphical OBject used by quickPlot - smallest unit |
Unions of existing classes: | |
.quickPlottables |
The union of all object classes Plot can accept |
.quickPlotObjects |
The union of spatialObjects and several others |
Eliot McIntire and Alex Chubaty
quickPlot
All maps included here are randomly generated maps created using
SpaDES.tools::gaussMap()
.
These are located within the maps
folder of the package, and are used
in the vignettes.
Use system.file("maps", package = "quickPlot")
to locate the ‘maps/’
directory on your system.
raster
DEM.tif
: converted to a a small number of discrete levels
(in 100m hypothetical units).
habitatQuality.tif
: made to look like a continuous habitat surface,
rescaled to 0 to 1.
forestAge.tif
: rescaled to possible forest ages in a boreal forest setting.
forestCover.tif
: rescaled to possible forest cover in a boreal forest setting.
percentPine.tif
: rescaled to percentages.
SpatialLines
This will convert 2 objects whose coordinates can be extracted with coordinates
(e.g., sp::SpatialPoints*
) to a single SpatialLines
object.
The first object is treated as the "to" (destination), and the second object the "from" (source).
This can be used to represent directional SpatialLines
, especially with with arrow heads,
as in Plot(sl, length = 0.1)
.
sp2sl(sp1, from)
sp2sl(sp1, from)
sp1 |
a |
from |
a |
caribou <- terra::vect(x = cbind(x = stats::runif(1e1, -50, 50), y = stats::runif(1e1, -50, 50))) caribouFrom <- terra::vect(x = cbind(x = stats::runif(1e1, -50, 50), y = stats::runif(1e1, -50, 50))) caribouLines <- sp2sl(caribou, caribouFrom) if (interactive()) { clearPlot() Plot(caribouLines, length = 0.1) }
caribou <- terra::vect(x = cbind(x = stats::runif(1e1, -50, 50), y = stats::runif(1e1, -50, 50))) caribouFrom <- terra::vect(x = cbind(x = stats::runif(1e1, -50, 50), y = stats::runif(1e1, -50, 50))) caribouLines <- sp2sl(caribou, caribouFrom) if (interactive()) { clearPlot() Plot(caribouLines, length = 0.1) }
fastshp::thin
For visualizing, it is sometimes useful to remove points in Spatial*
objects.
This will change the geometry, so it is not recommended for computation.
This is similar to sf::st_simplify
,
but faster (see examples) for large shapefiles, particularly if
returnDataFrame
is TRUE
.
thin
will not attempt to preserve topology.
It is strictly for making smaller polygons for the (likely) purpose of visualizing more quickly.
thin( x, tolerance, returnDataFrame, minCoordsToThin, ..., verbose = getOption("quickPlot.verbose") ) thnSpatialPolygons( x, tolerance = NULL, returnDataFrame = FALSE, minCoordsToThin = 1e+05, maxNumPolygons = getOption("quickPlot.maxNumPolygons", 3000), ..., verbose = getOption("quickPlot.verbose") ) ## Default S3 method: thin( x, tolerance, returnDataFrame, minCoordsToThin, maxNumPolygons, ..., verbose = getOption("quickPlot.verbose") )
thin( x, tolerance, returnDataFrame, minCoordsToThin, ..., verbose = getOption("quickPlot.verbose") ) thnSpatialPolygons( x, tolerance = NULL, returnDataFrame = FALSE, minCoordsToThin = 1e+05, maxNumPolygons = getOption("quickPlot.maxNumPolygons", 3000), ..., verbose = getOption("quickPlot.verbose") ) ## Default S3 method: thin( x, tolerance, returnDataFrame, minCoordsToThin, maxNumPolygons, ..., verbose = getOption("quickPlot.verbose") )
x |
A |
tolerance |
Maximum allowable distance for a point to be removed. |
returnDataFrame |
If |
minCoordsToThin |
If the number of coordinates is smaller than this number,
then thin will just pass through, though it will take the time required to
calculate how many points there are (which is not |
... |
Passed to methods (e.g., |
verbose |
Numeric or logical. If |
maxNumPolygons |
For speed, |
This is similar to pryr::where
, except instead of working up the search() path
of packages, it searches up the call stack for an object. Ostensibly similar
to base::dynGet
, but it will only return the environment, not the object
itself and it will try to extract just the object name from name
,
even if supplied with a more complicated name
(e.g., if obj$firstElement@slot1$size
is
supplied, the function will only search for obj). The function is fairly fast.
This function is an important component to the Plot
function.
whereInStack(name, whFrame = -1)
whereInStack(name, whFrame = -1)
name |
An object name to find in the call stack |
whFrame |
A numeric indicating which |
The difference between this and what get
and exists
do, is that these other
functions
search up the enclosing environments, i.e., it matters where the functions were defined.
whereInStack
looks up the call stack environments. See the example for the difference.
The environment that is in the call stack where the object exists, that is closest to the frame in which this function is called.
b <- 1 inner <- function(y) { objEnv <- whereInStack("b") get("b", envir = objEnv) } findB <- function(x) { b <- 2 inner() } findB() # Finds 2 because it is looking up the call stack, i.e., the user's perspective # defined outside of findB2, so its enclosing environment is the same as findB2 innerGet <- function(y) { get("b") } findB2 <- function(x) { b <- 2 innerGet() } findB2() # Finds 1 because b has a value of 1 in the enclosing environment of innerGet b <- 3 findB2() # Finds 3 because b has a value of 3 in the enclosing environment of innerGet, # i.e., the environment in which innerGet was defined findB() # Still finds 2 because the call stack hasn't changed # compare base::dynGet findB3 <- function(x) { b <- 2 dynGet("b") } findB3() # same as findB(), but marginally faster, because it omits the stripping on # sub elements that may be part of the name argument b <- list() findB3 <- function(x) { b$a <- 2 dynGet("b$a") } testthat::expect_error(findB3()) # fails because not an object name findB <- function(x) { b$a <- 2 env <- whereInStack("b$a") env } findB() # finds it
b <- 1 inner <- function(y) { objEnv <- whereInStack("b") get("b", envir = objEnv) } findB <- function(x) { b <- 2 inner() } findB() # Finds 2 because it is looking up the call stack, i.e., the user's perspective # defined outside of findB2, so its enclosing environment is the same as findB2 innerGet <- function(y) { get("b") } findB2 <- function(x) { b <- 2 innerGet() } findB2() # Finds 1 because b has a value of 1 in the enclosing environment of innerGet b <- 3 findB2() # Finds 3 because b has a value of 3 in the enclosing environment of innerGet, # i.e., the environment in which innerGet was defined findB() # Still finds 2 because the call stack hasn't changed # compare base::dynGet findB3 <- function(x) { b <- 2 dynGet("b") } findB3() # same as findB(), but marginally faster, because it omits the stripping on # sub elements that may be part of the name argument b <- list() findB3 <- function(x) { b$a <- 2 dynGet("b$a") } testthat::expect_error(findB3()) # fails because not an object name findB <- function(x) { b$a <- 2 env <- whereInStack("b$a") env } findB() # finds it