plotSpatial: Plot maps from a 'Field' or a lists of 'Field'

In MagicForrest/DGVMTools: DGVM Processing, Analysis and Plotting Tools

Plot maps from a Field or a lists of Field

Description

This is a heavy lifting function for plotting maps from Fields with flexibility, but also with a high degree of automation. As a consequence, it has a really large amount of parameters for a huge amount of flexibility. However they are all set to sensible defaults. In principle you can supply only the Fields and it will plot something sensible. It extracts the relevant data from the Fields, bashes it into a data.table then calls ggplot2 function geom_raster() and it returns a ggplot object, which will need to be displayed using a print() command. Note that this object can be firther modified using further ggplot2 commands.

Usage

plotSpatial(
  fields,
  layers = NULL,
  title = character(0),
  subtitle = character(0),
  legend.title = character(0),
  facet.order = NULL,
  plot.bg.col = "white",
  panel.bg.col = "white",
  useLongNames = FALSE,
  text.multiplier = NULL,
  xlim = NULL,
  ylim = NULL,
  years = NULL,
  days = NULL,
  months = NULL,
  seasons = NULL,
  limits = NULL,
  cols = NULL,
  cuts = NULL,
  drop.cuts = TRUE,
  map.overlay = NULL,
  plot = TRUE,
  tile = FALSE,
  pixel.size = NULL,
  ...
)

Arguments

fields	The data to plot. Can be a Field or a list of Fields.
layers	A list of strings specifying which layers to plot. Defaults to all layers.
title	A character string to override the default title. Set to NULL for no title.
subtitle	A character string to override the default subtitle. Set to NULL for no subtitle.
legend.title	A character string or expression to override the default legend title. Set to NULL for no legend title. The default legend title is the units of the Quantity of the first Field provided in the field argument. This argument allows general flexibility, but it is particularly handy to facilitate expressions for nicely marked up subscript and superscript.
facet.order	A vector of the characters that, if supplied, control the order of the facets. To see what these values are you can call this funtion with "plot=FALSE" and check the values of the Facet column. But generally they will be the values of the @names slots of the Data/Fields and/or the layers (as layers plotted as defined by the layers arguments in this function).
plot.bg.col	Colour string for the plot background, default "white".
panel.bg.col	Colour string for the panel background, default "white".
useLongNames	Boolean, if TRUE replace Layer IDs with the Layer's full names on the plots.
text.multiplier	A number specifying an overall multiplier for the text on the plot. Make it bigger if the text is too small on large plots and vice-versa.
xlim	An optional vector of two numerics to specify the x/longitude range of the plot.
ylim	An optional vector of two numerics to specify the y/latitude range of the plot.
years	An optional numeric vector specifying which years to plot (take care, this defaults to all the years in the input Fields which can be a lot!)
days	An optional numeric vector specifying which days to plot (take care, this defaults to all the days in the input Fields which can be a lot!)
months	An optional numeric vector specifying which months to plot(defaults to all the days in the input Fields)
seasons	An optional character vector specifying which seasons to plot (any or all of "DJF", "MAM, "JJA", "SON", defaults to all the seasons in the input Fields)
limits	A numeric vector with two members (lower and upper limit) to limit the plotted values.
cols	A colour palette function to override the defaults.
cuts	Cut ranges (a numeric vector) to override the default colour delimitation, discretise the data into discrete colour bands
drop.cuts	Logical, if TRUE then drop cut at each end which do not have any data in them in order more to fully use the colour scale. Default is TRUE. Ignored if 'cuts' argument is not used.
map.overlay	An optional character string specifying either "coastlines" (alternatively "ne_coastlines") or "countries" (alternatively "ne_countries" or, for backwards compatibility with previous versions "world") to plot either the coastlines or coastlines and country borders from the ranturalearth(data) packages. Other things can be overlain on the resulting plot with further ggplot2 commands, and check the rnaturalearth package family for higher res versions, lakes, etc.
plot	Boolean, if FALSE return a data.table with the final data instead of the ggplot object. This can be useful for inspecting the structure of the facetting columns, amongst other things.
tile	Logical, if TRUE use geom_tile instead of geom_raster. The advantage is that plots made with geom_tile are more malleable and can, for example, be plotted on polar coordinates. However geom_tile is much slower than geom_raster.
pixel.size	Numeric, allows you to alter the plotted pixel size (height and width simultaneously using the same value). This is useful if you are plotting a collection of individual sites which do not have regular spacing. Note the "tile = TRUE" (see above) will automatically set if you haven't done it manually.
...	Arguments passed to ggplot2::facet_wrap(). See the ggplot2 documentation for full details but the following are particularly useful. "nrow"The number of rows of facets "ncol"The number of columns of facets "scales"Whether the scales (ie. x and y ranges) should be fixed for all facets. Options are "fixed" (same scales on all facets, default) "free" (all facets can their x and y ranges), "free_x" and "free_y" (only x and y ranges can vary, respectively). "labeller"A function to define the labels for the facets. This is a little tricky, please look to the ggplot2 documentation. But basically what you want is to define a named character vector, the names are the previous facet names and the values are the new names. Then make this into a function by passing it to the ggplot function "as.labeller", and then that becomes your 'labeller' argument.

Details

This function is the main spatial plotting functions and can be very useful to the user for making quick plots in standard benchmarking and post-processing. It is also highly customisable for final results plots for papers and so on.

Value

Returns a ggplot object

Author(s)

Matthew Forrest [e-mail]

See Also

plotTemporal, plotSpatialComparison

MagicForrest/DGVMTools documentation built on Aug. 23, 2024, 8:05 a.m.