Save a map to disk intended to be part of a as a still image sequence of one of four types: networks, tiles, lines, or polygons.
save_map(data, z.name = NULL, z.range = NULL, id, dir = ".", lon = 0,
lat = 0, n.period = 360, n.frames = n.period, ortho = TRUE,
col = NULL, type, contour = "none", density.geom = "tile",
xlim = c(-180, 180), ylim = c(-90, 90), pt.size = c(1, 0.5, 1, 0.5),
rotation.axis = 23.4, file = "Rplot", png.args = list(width = 1920,
height = 1080, res = 300, bg = "transparent"), save.plot = TRUE,
return.plot = FALSE, overwrite = FALSE, num.format = 4)a data frame containing networks, tiles, lines or polygons information.
character, the column name of the data (z) variable in data. Only needed for type="maptiles" and type="polygons"
numeric vector, the full known range for the data values across all data objects, not just the current one, e.g. c(0, 5).
character, column name referring to column of data representing frame sequence integer IDs.
png output directory. Defaults to working directory.
starting longitude for rotation sequence or vector of arbitrary longitude sequence.
fixed latitude or vector of arbitrary latitude sequence.
intended length of the period.
intended number of frames in animation.
use an orthographic projection for globe plots. Defaults to TRUE.
sensible default colors provided for each type
the type of plot, one of points, maplines, polygons, maptiles, density, or "network".
character, one of none, overlay, or only. Defaults to none. See details.
character, one of tile or polygon. Defaults to tile. See details.
numeric vector, defaults to (-180, 180). Will crop to range of longitudes in data if NULL.
numeric vector, defaults to (-90, 90). Will crop to range of latitudes in data if NULL.
numeric vector, applies only to type="network". Point sizes follow same order as colors for networks. See details.
the rotation axis used when ortho=TRUE for globe plots. Defaults to 23.4 degrees.
character, output filename pattern preceeding the image sequence numbering and file extension. Defaults to "Rplot".
a list of arguments passed to png. bg will still be used to color the plot bakground if return.plot=TRUE
so continue to pass png.args a background color when bg is not the default transparent even if save.plot=FALSE.
save the plot to disk. Defaults to TRUE. Typically only set to FALSE for demonstrations and testing.
return the ggplot object. Defaults to FALSE. Only intended for single-plot demonstrations and testing, not for still image sequence automation.
logical, overwrite existing files. Defaults to FALSE. If file exists and return.plot=TRUE the plot is still returned. Otherwise returns NULL.
This is a frame by frame check on each file. File writing is simply skipped for existing files when overwrite=FALSE. No error or warning is thrown.
number of digits including any leading zeros for image sequence frame numbering. Defaults to 4, i.e. 0001, 0002, ....
usually returns NULL after writing file to disk. May return a ggplot object with or without the file writing side effect.
save_map takes a specific type of data frame catering to networks, tiles, lines, or polygons.
It plots a 3D globe map with ortho=TRUE (default) or a flat map (ortho=FALSE).
For flat maps, lon, lat, n.period, n.frames, and rotation.axis are ignored.
For plotting on a globe, lon and lat are used to describe the field of view or the visible hemisphere.
n.period relates is eithe the period of rotation of the globe or the length of the non-repeating, arbitrary coordinates sequence.
n.frames is always the explicit number of frames that will make up an animation
regardless of the length of the series of data frames data to be plotted or the length of the rotational period or coordinates sequence.
If you are familiar with ggplot2, it may help to think of points as making use of geom_point;
maplines uses geom_path; polygons uses geom_polygon and geom_path;
maptiles uses geom_tile; density uses stat_density2d or stat_contour; and "network" combines geom_path and geom_point.
maptiles is also a specific case of density.
Maps are based on either two variables (location only) or on three variables (longitude, latitude, plus a data variable).
The former are generated by the map type options points, maplines, and network.
The latter are generated by polygons and maptiles. density may apply to either case.
z.name is relevant only for fill color when drawing tiles, polygons, or densities.
z.range is important for these plot types that use a data variable in addition to longitude and latitude
because it is used to ensure colors are mapped to data values consistently across all plots.
This is not only for the case of changing data values across a series of plots of different data frames data.
There are also changes in the range of values for a fixed data frame when it is plotted repeatedly as the globe is rotated and different hemispheres of the map
(different data subsets) are in view across the image sequence. z.range will default to the range of the given data if not provided.
The color argument is used differently depending on type.
For points and maplines it is a single color. Additional colors in a vector are ignored. For other plot types it must be a vector.
maptiles and polygons require a vector of at least two colors to produce a palette for their color gradient.
density may also require this but only for contour fill color gradient, which is relevant only when a data variable is specified by z.name.
network is a special case which assumes four colors in the following order: background line, foreground line, background point, foreground point.
The four colors are layered in the plot in this order. Semi-transparent colors can work well in this context. Additional colors are ignored.
If col=NULL (default) sensible default colors are provided for each plot type.
For contour lines, overlays on density maps are black by default but when layered with points col applies to both points and contour lines.
In the current package version defaul black for density is only overridden by the col argument when contour="only".
The first color is used and any additional colors in col are ignored, unless contour="only" and type="density" when z.name is also provided.
In this case, the density map represents a contour map based on all three variables
and since the contour is not filled (only contour lines; no overlay on a filled contour) the color palette defined by a col vector is allowed to apply to the contour lines themselves.
type="density" is a special map type setting in that density maps can be based on either position only (longitude and latitude) or on position plus data at position.
The name "density" is more appropriate for the former, for example a desnity plot of x and y data. For the latter, using three variables x, y and z,
it would be more accurate to refer to the default plot as a filled contour plot.
The visual effect is the same so it is not split into two distinct type selections.
Instead, the map is drawn using either ggplot2::stat_density2d or ggplot2::stat_contour depending on whether the user provides z.name or leaves it as NULL.
A separate contour argument is reserved for the option to overlay explicit contour lines (no color fill).
The contour argument is for optionally displaying contour lines on a map. By default, no contour lines are drawn.
contour="overlay" will overlay contour lines on another plotting layer and contour="only" will plot only the contour lines in place of the default layer.
Contour lines are only available for specific plot types: type="points" and type="density".
Since points are based on lon and lat data only, contour lines are similarly drawn based on lon and lat using ggplot2::stat_density2d.
On the other hand, density maps can be based on either two or three variables.
2D densities are drawn as with type="points".
When three variables are provided (lon, lat, and z.name), contour lines are drawn using ggplot2::stat_contour.
contour is ignored for any other type.
Density maps can be generated using polygons or tiles (rasterized data).
density.geom="tile" is the default because although it may require more processing power and time to generate map outputs,
tiles generally provides higher quality output with sufficient spatial resolution of the input data.
density.geom="polygon" may be quicker to render but may provide visually disappointing maps with severe clipping, especially in the orthographic projection, depending on the input data.
This is analogous to the trade off between using type="polygons" at all vs. electing to rasterize the input data up front and use it with type="maptiles" instead.
In fact, type="maptiles" is a special case of type="density"; the one which will generally work best, and without the superimposed contour lines.
See the introductory vignette for examples: browseVignettes(package=="mapmate")
For these reasons, the polygons map type and the density.geom="polygon" option for the density map type
are potentially useful only if the intent is to eventually zoom in on an area of the globe where no artifacts are visible.
Otherwise these settings serve largely to illustrate their limitations
and it is still best to use type="maptiles" or the density.geom="tile" option with type="density"
if the goal is to achieve artifact-free 3D global plots viewed from any arbitrary persepctive.
Depending on the input data, this may be necessary even for flat maps.
The costs to avoiding these problems are (1) much greater processing time with increasing resolution of the input data in order to make map pixels satisfactorily small and (2) the computing resources necessary to run it as well as have it run satisfactorily quickly.
Finally, drawing polygons and contour lines may yield superior visual results when working with three variables because this means there potentially can be data values associated uniformly with every spot on the surface of the globe, whereas density or intensity maps made from only the spatial locations of points themselves may be more likely to reveal clipping issues when projected.
The png output directory will be created if it does not exist, recursively if necessary. The default is the working directory.
This is ignored if save.plot=FALSE.
type="polygons" is only recommended for use with flat maps, not the orthographic projection. See the vignette for an example and description of the issue.
For globe plots it is best to rasterize polygons and use type="maptiles" for better results in exchange for increased processing time.
# NOT RUN {
# not run
# }
# NOT RUN {
library(dplyr)
library(purrr)
library(RColorBrewer)
data(annualtemps)
pal <- rev(brewer.pal(11,"RdYlBu"))
temps <- mutate(annualtemps, frameID = Year - min(Year) + 1)
temps <- split(temps, temps$frameID)
rng <- range(annualtemps$z, na.rm=TRUE)
n <- length(unique(annualtemps$Year))
filename <- "annual_3D_rotating"
# should specify a dir or set working dir for file output
# consider running over a smaller subset of frame IDs
walk(temps, ~save_map(.x, z.name="z", id="frameID", lon=-70, lat=50,
n.period=30, n.frames=n, col=pal, type="maptiles", file=filename, z.range=rng))
# }
Run the code above in your browser using DataLab