PlotMapPoints {HYPEtools}

Plot function for mapped point information

Description

Plot mapped point information, e.g. model performances at observation sites.

Usage

PlotMapPoints(
  x,
  sites = NULL,
  sites.subid.column = 1,
  sites.groups = NULL,
  bg = NULL,
  bg.label.column = 1,
  var.name = "",
  map.type = "default",
  shiny.data = FALSE,
  plot.legend = TRUE,
  legend.pos = "right",
  legend.title = NULL,
  legend.signif = 2,
  col = NULL,
  col.breaks = NULL,
  col.labels = NULL,
  col.rev = FALSE,
  plot.scale = TRUE,
  scale.pos = "br",
  plot.arrow = TRUE,
  arrow.pos = "tr",
  radius = 5,
  weight = 0.15,
  opacity = 0.75,
  fillOpacity = 0.5,
  na.color = "#808080",
  jitter = 0.01,
  bg.weight = 0.15,
  bg.opacity = 0.75,
  bg.fillColor = "#e5e5e5",
  bg.fillOpacity = 0.75,
  plot.label = FALSE,
  plot.label.size = 2.5,
  plot.label.geometry = c("centroid", "surface"),
  noHide = FALSE,
  textOnly = FALSE,
  font.size = 10,
  plot.bg.label = NULL,
  file = "",
  width = NA,
  height = NA,
  units = c("in", "cm", "mm", "px"),
  dpi = 300,
  vwidth = 1424,
  vheight = 1000,
  html.name = "",
  map.adj = 0,
  legend.outer = FALSE,
  legend.inset = c(0, 0),
  pt.cex = 1,
  par.cex = 1,
  par.mar = rep(0, 4) + 0.1,
  pch = 21,
  lwd = 0.8,
  add = FALSE,
  map = NULL,
  map.subid.column = NULL
)

Arguments

x

Information to plot, typically model performances from imported HYPE 'subassX.txt' files. Data frame object with two columns, first column containing SUBIDs and second column containing model results to plot. See details.

sites, map

A SpatialPointsDataFrame or sf object. Typically an imported outlet point vector point file. Import of vector points requires additional packages, e.g. sf::st_read().

sites.subid.column, map.subid.column

Integer, column index in the sites 'data' slot holding SUBIDs (sub-catchment IDs).

sites.groups

Named list providing groups of SUBIDs to allow toggling of point groups in Leaflet maps. Default NULL will produce maps without point groups. List names represent the names of the groups to plot, and list values represent the SUBIDs within the group. Example: sites.groups = list("GROUP 1" = c(1, 2, 3), "GROUP 2" = c(4, 5, 6)).

bg

A SpatialPolygonsDataFrame or sf object to plot in the background. Typically an imported sub-basin vector polygon file. For default maps with several background layers, use add = TRUE and plot background layer(s) first.

bg.label.column

Integer, column index in the bg 'data' slot holding labels (e.g. SUBIDs) to use for plotting.

var.name

Character string. HYPE variable name to be plotted. Mandatory for automatic color ramp selection of pre-defined HYPE variables (col = "auto"). Not case-sensitive.

map.type

Map type keyword string. Choose either "default" for the default static plots or "leaflet" for interactive Leaflet maps. Use "legacy" for deprecated static plots.

shiny.data

Logical, if map.type is "leaflet", then should the output be a list containing the basemap, formatted data, legend colors, and legend labels? Typically set to FALSE unless using PlotMapOutput to create Shiny apps or custom Leaflet maps.

plot.legend

Logical, plot a legend along with the map.

legend.pos

Keyword string for legend position. For static plots, one of: "none", "left", "right", "bottom", "top", or a two-element numeric vector. For interactive Leaflet maps, one of: "topleft", "topright", "bottomright", "bottomleft". For legacy static plots, one of: "left", "topleft", "topright", "right", "bottomright", "bottomleft".

legend.title

Character string or mathematical expression. An optional title for the legend. If none is provided here, the name of the second column in x is used as legend title string.

legend.signif

Integer, number of significant digits to display in legend labels.

col

Colors to use on the map. One of the following:

• NULL, to use a default purple-red-yellow-blue color ramp, best used with col.breaks = NULL.

• A color ramp palette function, e.g. as returned from a call to colorRampPalette

• A vector of colors. This can be a character vector of R's built-in color names or hexadecimal strings as returned by rgb, or an integer vector of current palette indices.

col.breaks

A numeric vector, specifying break points for discretization of model result values into classes. Class boundaries will be interpreted as right-closed, i.e upper boundaries included in class. Lowest class boundary included in lowest class as well. Meaningful results require the lowest and uppermost breaks to bracket all model result values, otherwise there will be unclassified white spots on the map plot. If NULL (the default), col.breaks covers a range from 0 to 1 with 9 intervals, and an additional interval for negative values. This is suitable for e.g. NSE performances.

col.labels

A character vector, specifying custom labels to be used for each legend item. Works with map.type set to default or leaflet.

col.rev

Logical, If TRUE, then color palette will be reversed.

plot.scale

Logical, plot a scale bar on map. NOTE: Scale bar may be inaccurate for geographic coordinate systems (Consider switching to projected coordinate system).

scale.pos

Keyword string for scalebar position for static maps. One of bl, br, tr, or tl.

plot.arrow

Logical, plot a North arrow in static maps.

arrow.pos

Keyword string for north arrow position for static maps. One of bl, br, tr, or tl.

radius

Numeric, radius of markers maps. See geom_sf for static maps and leaflet::addCircleMarkers() for Leaflet maps.

weight

Numeric, weight of marker outlines in Leaflet maps. See leaflet::addCircleMarkers().

opacity

Numeric, opacity of marker outlines in Leaflet maps. See leaflet::addCircleMarkers().

fillOpacity

Numeric, opacity of markers in Leaflet maps. See leaflet::addCircleMarkers().

na.color

Character string of color to use to symbolize markers in maps which correspond to NA values.

jitter

Numeric, amount to jitter points with duplicate geometries. See sf::st_jitter().

bg.weight

Numeric, weight of bg subbasin outlines in Leaflet maps. See leaflet::addPolygons().

bg.opacity

Numeric, opacity of bg subbasin outlines in Leaflet maps. See geom_sf for static maps and leaflet::addPolygons() for Leaflet maps.

bg.fillColor

Character string of color to use to symbolize bg subbasin polygons in maps. See geom_sf for static maps and leaflet::addPolygons() for Leaflet maps.

bg.fillOpacity

Numeric in range 0-1, opacity of bg subbasin polygons in maps. See geom_sf for static maps and leaflet::addPolygons() for Leaflet maps.

plot.label

Logical, if TRUE, then labels will be displayed on default static maps and in Leaflet maps when the cursor hovers over markers. See geom_sf_text for default maps and leaflet::addCircleMarkers() for Leaflet maps.

plot.label.size

Numeric, size of text for labels on default static plots. See geom_sf_text.

plot.label.geometry

Keyword string to select where plot labels should be displayed on the default static plots. Either centroid to use sf::st_centroid or surface to use sf::st_point_on_surface.

noHide

Logical, set to TRUE to always display marker labels in Leaflet maps. See leaflet::labelOptions().

textOnly

Logical, set to TRUE to hide marker label background in Leaflet maps. See leaflet::labelOptions().

font.size

Numeric, font size (px) for marker labels in Leaflet maps.

plot.bg.label

String, if hover, then labels will be displayed in Leaflet maps for bg when the cursor hovers over polygons. If static, then static labels for bg will be displayed in Leaflet maps. If any string is specified, then background labels will be added to default static maps.

file

Save map to an image file by specifying the path to the desired output file using this argument. File extension must be specified. See ggsave for static maps and mapview::mapshot() for Leaflet maps. You may need to run webshot::install_phantomjs() the first time you save a Leaflet map to an image file. See webshot::install_phantomjs().

width

Numeric, width of output plot for static maps in units of units. See ggsave.

height

Numeric, height of output plot for static maps in units of units. See ggsave.

units

Keyword string for units to save static map. One of "in", "cm", "mm", "px". See ggsave.

dpi

Integer, resolution to save static map. See ggsave.

vwidth

Numeric, width of the exported Leaflet map image in pixels. See webshot::webshot().

vheight

Numeric, height of the exported Leaflet map image in pixels. See webshot::webshot().

html.name

Save Leaflet map to an interactive HTML file by specifying the path to the desired output file using this argument. File extension must be specified. See htmlwidgets::saveWidget().

map.adj

Numeric, map adjustment in direction where it is smaller than the plot window. A value of 0 means left-justified or bottom-justified, 0.5 (the default) means centered, and 1 means right-justified or top-justified. Only used for legacy static maps.

legend.outer

Logical. If TRUE, outer break point values will be plotted in legend. Only used for legacy static maps.

legend.inset

Numeric, inset distance(s) from the margins as a fraction of the plot region for legend, scale and north arrow. See legend and details below. Only used for legacy static maps.

pt.cex

Numeric, plot point size expansion factor, works on top of par.cex.

par.cex

Numeric, character expansion factor. See description of cex in par. Only used for legacy maps.

par.mar

Plot margins as in par argument mar. Defaults to a nearly margin-less plot. In standard use cases of this function, plot margins do not need to be changed. Only used for legacy maps.

pch, lwd

Integer, plotting symbol and line width. See points. Only used for legacy maps.

add

Logical, default FALSE. If TRUE, add to existing plot. In that case map.adj has no effect. Only used for legacy maps.

Details

PlotMapPoints can be used to print point information on a mapped surface. The primary target are model performance measures as written to HYPE 'subassX.txt' files, but color scale and break point arguments are flexible enough to also be used with e.g. HYPE output variables or other data.

PlotMapOutput can return static plots or interactive Leaflet maps depending on value provided for the argument map.type. For backwards compatibility, legacy static plots can still be generated by setting map.type to legacy. For legacy plots, legend.pos and map.adj should be chosen so that legend and map do not overlap, and the legend position can be fine-tuned using argument legend.inset. This is particularly useful for legend titles with more than one line. For details on inset specification for the default maps, see inset in legend.

Value

For default static maps, PlotMapPoints returns an object of class ggplot. This plot can also be assigned to a variable in the environment. For interactive Leaflet maps, PlotMapOutput returns an object of class leaflet. For legacy static plots, PlotMapOutput returns a plot to the currently active plot device and invisibly an object of class SpatialPointsDataFrame as provided in argument sites, with plotted values and color codes added as columns in the data slot.

See Also

ReadSubass for HYPE result import; ReadMapOutput for a similar plot function

Examples

# Import plot data and subbasin points
require(sf)
te1 <- ReadSubass(filename = system.file("demo_model",
"results", "subass1.txt", package = "HYPEtools"))
te2 <- st_read(dsn = system.file("demo_model",
"gis", "Nytorp_station.gpkg", package = "HYPEtools"))
te2$SUBID <- 3587 # add station SUBID to point
te3 <- st_read(dsn = system.file("demo_model",
"gis", "Nytorp_map.gpkg", package = "HYPEtools"))
# plot NSE performance for discharge
PlotMapPoints(x = te1[, 1:2], sites = te2, sites.subid.column = 4, bg = te3)