PlotMapPoints: Plot function for mapped point information

In HYPEtools: Tools for Processing and Analyzing Files from the Hydrological Catchment Model HYPE

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 ggplot2::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 ggplot2::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 ggplot2::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 ggplot2::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 ggplot2::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 ggplot2::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 ggplot2::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 ggplot2::ggsave.
height	Numeric, height of output plot for static maps in units of units. See ggplot2::ggsave.
units	Keyword string for units to save static map. One of "in", "cm", "mm", "px". See ggplot2::ggsave.
dpi	Integer, resolution to save static map. See ggplot2::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)

HYPEtools documentation built on Sept. 11, 2024, 8:34 p.m.