ggplot_dt: plotting function for spatial data

Description

Plots spatial data from a data.table. The data table needs to contain columns named 'lon' and 'lat'. The grid needs to be regular. If spatial data is contained for several levels (e.g. mutliple times or multiple ensemble members), only the data for the first level is plotted. By default, the first column that is not recognized as a dimension variable is plotted, see data_col. For the most common data-columns, reasonable color scales are selected automatically.

Usage

ggplot_dt(
  dt,
  data_col = NULL,
  mn = NULL,
  discrete_cs = FALSE,
  rr = NULL,
  low = NULL,
  mid = NULL,
  high = NULL,
  name = data_col,
  midpoint = NULL,
  breaks = NULL,
  na.value = "gray75",
  oob = NULL,
  guide = guide_colorbar(barwidth = 0.5, barheight = 10),
  ...,
  binwidth = NULL,
  bin_midpoint = midpoint,
  add_map = TRUE,
  extent = NULL,
  expand.x = c(0, 0),
  expand.y = c(0, 0)
)

Value

a ggplot object.

Arguments

dt: Data table containing the data for plotting.
data_col: The name of the column in dt containing the data for plotting. If nothing is provided (the default), the first column that is not a dimension variable or 'member' is selected.
mn: optional plot title
discrete_cs: Logical. Should the color scale be discretized?
rr, low, mid, high, name, breaks, na.value, oob, guide, ...: Arguments for the color scale, passed to scale_fill_gradient2 or scale_fill_steps2 (depending on whether discrete_cs == TRUE). rr replaces limits (specifying the range of the color scale) for consistency with the older plotting functions from the PostProcessing package. na.value specifies the color of missing values. oob specifies the treatment of out-of-boundary values, i.e. values beyond the limits. The ... argument can in particular be used to customize the legend/colorbar using the function guide_colorbar, see https://ggplot2.tidyverse.org/reference/guide_colourbar.html. Moreover, when discrete_cs == TRUE you can pass the arguments n.breaks,breaks to customize the scale. If you use n.breaks you might also want to set nice.breaks = FALSE, see ?scale_fill_steps2.
midpoint: midpoint of the color scale, passed to scale_fill_gradient2 or scale_fill_steps2 (depending on whether discrete_cs == TRUE). If you set it to NULL (the default), the midpoint is set to the center of the data range (or the center of rr, if provided), such that the entire color scale is used. Note that this default differs from the default behavior of scale_fill_gradient2 or scale_fill_steps2. Specifying the midpoint can often be a convenient way to force a color scale with only two colors (for example, by setting it to the minimum or maximum of your data).
binwidth, bin_midpoint: only used when discrete_cs == TRUE. Normally, the breaks for the discrete colorscale are specified by n.breaks (which is not reliable, since they're adjusted to be 'nice'), or by specifying the breaks explicitly (which is often tedious). This gives you a third option, namely specifying how far the breaks should be apart, and specifying the centerpoint for one of the bins (default is midpoint, or the center of rr if midpoint is not provided). For example, if your color scale shows percentages and you'd like 4 categories, ranging from white to red, this is easiest achieved by binwidth = 25, midpoint = 12.5.
add_map: logical. Set to FALSE to remove borders (e.g. if you want to add them yourself from a shapefile).
extent: An optional four-element vector in the order xmin,xmax,ymin,ymax for specifying the spatial extent of the plot. Default is to fit the extent to the data.
expand.x, expand.y: vectors with two entries to be added to xlims/ylims of the plot. E.g. expand.x = c(-0.5,0.5) expands the plot by half a longitude both on the right and left hand side

Author

Claudio Heinrich

Examples

Run this code

ex_dt = chirps_monthly[lat <0 & month == 12 & year == 2020]
pp = ggplot_dt(ex_dt)
if(interactive()) plot(pp)

Run the code above in your browser using DataLab