anlzMWRmap {MassWateR}

Analyze results with maps

Description

Analyze results with maps

Usage

anlzMWRmap(
  res = NULL,
  param,
  acc = NULL,
  sit = NULL,
  fset = NULL,
  site = NULL,
  resultatt = NULL,
  locgroup = NULL,
  dtrng = NULL,
  ptsize = 4,
  repel = TRUE,
  labsize = 3,
  palcol = "Greens",
  palcolrev = FALSE,
  sumfun = "auto",
  crs = 4326,
  zoom = 11,
  addwater = "medium",
  watercol = "lightblue",
  maptype = NULL,
  buffdist = 2,
  scaledist = "km",
  northloc = "tl",
  scaleloc = "br",
  latlon = TRUE,
  ttlsize = 1.2,
  runchk = TRUE,
  warn = TRUE
)

Arguments

res

character string of path to the results file or data.frame for results returned by readMWRresults

param

character string of the parameter to plot, must conform to entries in the "Simple Parameter" column of paramsMWR

acc

character string of path to the data quality objectives file for accuracy or data.frame returned by readMWRacc

sit

character string of path to the site metadata file or data.frame of site metadata returned by readMWRsites

fset

optional list of inputs with elements named res, acc, frecom, sit, or wqx overrides the other arguments

site

character string of sites to include, default all

resultatt

character string of result attributes to plot, default all

locgroup

character string of location groups to plot from the "Location Group" column in the site metadata file, default all

dtrng

character string of length two for the date ranges as YYYY-MM-DD, default all

ptsize

numeric for size of the points, use a negative value to omit the points

repel

logical indicating if overlapping site labels are offset

labsize

numeric for size of the site labels

palcol

character string indicating the color palette to be used from RColorBrewer, see details

palcolrev

logical indicating if color palette in palcol is reversed

sumfun

character indicating one of "auto" (default), "mean", "geomean", "median", "min", or "max", see details

crs

numeric as a four-digit EPSG number for the coordinate reference system, see details

zoom

numeric indicating resolution of the base map, see details

addwater

character string as "low", "medium" (default), "high", or NULL (to suppress) to include water features with varying detail from the National Hydrography dataset, see details

watercol

character string of color for water objects if addwater is not NULL

maptype

character string as "cartolight", "cartodark", "osm", "hotstyle", or NULL (to suppress, default) indicating the basemap type, see details

buffdist

numeric for buffer around the bounding box for the selected sites in kilometers, see details

scaledist

character string indicating distance unit for the scale bar, "km" or "mi"

northloc

character string indicating location of the north arrow, see details

scaleloc

character string indicating location of the scale bar, see details

latlon

logical to include latitude and longitude labels on the plot, default TRUE

ttlsize

numeric value indicating font size of the title relative to other text in the plot

runchk

logical to run data checks with checkMWRresults, checkMWRacc, or checkMWRsites, applies only if res, acc, or sit are file paths

warn

logical to return warnings to the console (default)

Details

This function creates a map of summarized results for a selected parameter at each monitoring site. By default, all dates for the parameter are averaged. Options to filter by site, date range, and result attribute are provided. Only sites with spatial information in the site metadata file are plotted and a warning is returned for those that do not have this information. The site labels are also plotted next to each point. The labels can be suppressed by setting labsize = NULL.

Any acceptable color palette from RColorBrewer can be used for palcol, which is passed to the palette argument in scale_fill_distiller. These could include any of the sequential color palettes, e.g., "Greens", "Blues", etc. The diverging and qualitative palettes will also work, but may return uninterpretable color scales. The palette can be reversed by setting palcolrev = TRUE.

The default value for crs is EPSG 4326 for the WGS 84 projection in decimal degrees. The crs argument is passed to st_as_sf and any acceptable CRS appropriate for the data can be used.

The results shown on the map represent the parameter summary for each site within the date range provided by dtrng. If sumfun = "auto" (default), the mean is used where the distribution is determined automatically from the data quality objective file for accuracy, i.e., parameters with "log" in any of the columns are summarized with the geometric mean, otherwise arithmetic. Any other valid summary function will be applied if passed to sumfun ("mean", "geomean", "median", "min", "max"), regardless of the information in the data quality objective file for accuracy.

Using addwater = "medium" (default) will include lines and polygons of natural water bodies defined using the National Hydrography Dataset (NHD). The level of detail can be changed to low or high using addwater = "low" or addwater = "high", respectively. Use addwater = NULL to not show any water features.

A base map can be plotted using the maptype argument and is obtained from the annotation_map_tile function of ggspatial. The zoom value specifies the resolution of the map. Use higher values to download map tiles with greater resolution, although this increases the download time. The maptype argument describes the type of base map to download. Acceptable options include "cartolight", "cartodark", "osm", or "hotstyle". Use maptype = NULL to suppress the base map.

The area around the summarized points can be increased or decreased using the buffdist argument. This creates a buffered area around the bounding box for the points, where the units are kilometers.

A north arrow and scale bar are also placed on the map as defined by the northloc and scaleloc arguments. The placement for both can be chosen as "tl", "tr", "bl", or "br" for top-left, top-right, bottom-left, or bottom-right respectively. Setting either of the arguments to NULL will suppress the placement on the map.

Value

A ggplot object that can be further modified.

Examples

# results data path
respth <- system.file('extdata/ExampleResults.xlsx', package = 'MassWateR')

# results data
resdat <- readMWRresults(respth)

# accuracy path
accpth <- system.file('extdata/ExampleDQOAccuracy.xlsx', package = 'MassWateR')

# accuracy data
accdat <- readMWRacc(accpth)

# site data path
sitpth <- system.file('extdata/ExampleSites.xlsx', package = 'MassWateR')

# site data
sitdat <- readMWRsites(sitpth)


# map with NHD water bodies
anlzMWRmap(res = resdat, param = 'DO', acc = accdat, sit = sitdat, addwater = 'medium')