PlotMapOutput {HYPEtools}

Plot function for HYPE map results.

Description

Draw HYPE map results, with pretty scale discretizations and color ramp defaults for select HYPE variables.

Usage

PlotMapOutput(
  x,
  map = NULL,
  map.subid.column = 1,
  var.name = "",
  map.type = "default",
  shiny.data = FALSE,
  plot.legend = TRUE,
  legend.pos = "right",
  legend.title = NULL,
  legend.signif = 2,
  col = "auto",
  col.ramp.fun,
  col.breaks = NULL,
  col.labels = NULL,
  col.rev = FALSE,
  plot.scale = TRUE,
  scale.pos = "br",
  plot.arrow = TRUE,
  arrow.pos = "tr",
  weight = 0.15,
  opacity = 0.75,
  fillOpacity = 0.5,
  outline.color = "black",
  na.color = "#808080",
  plot.searchbar = FALSE,
  plot.label = FALSE,
  plot.label.size = 2.5,
  plot.label.geometry = c("centroid", "surface"),
  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),
  par.cex = 1,
  par.mar = rep(0, 4) + 0.1,
  add = FALSE,
  sites = NULL,
  sites.subid.column = NULL
)

Arguments

x

HYPE model results, typically 'map output' results. Data frame object with two columns, first column containing SUBIDs and second column containing model results to plot. See details.

map, sites

A SpatialPolygonsDataFrame or sf object. Typically an imported sub-basin vector polygon file. Import of vector polygons requires additional packages, e.g. sf::st_read. For interactive Leaflet maps a small/simplified polygon file should be used as larger files can take an excessive amount of time to render.

map.subid.column, sites.subid.column

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

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. See details.

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, var.name is used as legend title string. For select HYPE variables, pretty legend titles are in-built.

legend.signif

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

col

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

• "auto" to allow for automatic selection from tailored color ramp palettes and break points based on argument var.name, see details

• A color ramp palette function, e.g. as returned from a call to colorRampPalette. A number of tailored functions are available in HYPEtools, see CustomColors

• 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.ramp.fun

DEPRECATED, for backwards compatibility only.

col.breaks

A numeric vector, specifying break points for discretization of model result values into classes. Used if a color palette is specified with col argument. 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. Not mandatory, can optionally be combined with one of the pre-defined palettes, including "auto" selection. Per default, a generic classification will be applied (see details).

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.

weight

Numeric, weight of subbasin boundary lines. See geom_sf for static maps and leaflet::addPolygons() for Leaflet maps.

opacity

Numeric, opacity of subbasin boundary lines in Leaflet maps. See leaflet::addPolygons().

fillOpacity

Numeric, opacity of subbasin polygons in Leaflet maps. See leaflet::addPolygons().

outline.color

Character string of color to use to for subbasin polygon outlines. Use NA to hide the outlines.

na.color

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

plot.searchbar

Logical, if TRUE, then a search bar will be included within Leaflet maps. See leaflet.extras::addSearchFeatures().

plot.label

Logical, if TRUE, then labels will be displayed on default static maps and in Leaflet maps when the cursor hovers over subbasins. See geom_sf_text for default maps and leaflet::addPolygons() 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.

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 mapview::mapshot().

vheight

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

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 default maps.

legend.outer

Logical. If TRUE, outer break point values will be plotted in legend.

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.

par.cex

Numeric, character expansion factor. See description of cex in par. Only used for default 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 default maps.

add

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

Details

PlotMapOutput plots HYPE results from 'map[variable name].txt' files, typically imported using ReadMapOutput. x arguments must contain the variable of interest in the second column. For map results with multiple columns, i.e. several time periods, pass index selections to x, e.g. mymapresult[, c(1, 3)].

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. In order to move map and legend closer to each other, change the plot device width. For details on inset specification for the default maps, see inset in legend.

Mapped variables are visualized using color-coded data intervals. HYPEtools provides a number of color ramps functions for HYPE variables, see CustomColors. These are either single-color ramps with less saturated colors for smaller values and more saturated values for higher values, suitable for e.g. concentration or volume ranges, or multi-color ramps suitable for calculated differences, e.g. between two model runs.

Break points between color classes of in-built or user-provided color ramp palettes can optionally be provided in argument col.breaks. This is particularly useful when specific pretty class boundaries are needed, e.g. for publication figures. Per default, break points for internal single color ramps and user-provided ramps are calculated based on 10\ x. Default break points for internal color ramp ColDiffGeneric are based on an equal distance classification of log-scaled x ranges, centered around zero. For internal color ramp ColDiffTemp, they are breaks in an interval from -7.5 to 7.5 K.

For select common HYPE variables, given in argument var.name, an automatic color ramp selection including pretty breaks and legend titles is built into PlotMapOutput. These are 'CCTN', 'CCTP', 'COUT', and 'TEMP'. Automatic selection is activated by choosing keyword "auto" in col. All other HYPE variables will be plotted using a generic color ramp palette and generic break points with "auto" color selection.

Value

For default static maps, PlotMapOutput 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 SpatialPolygonsDataFrame as provided in argument map, with plotted values and color codes added as columns in the data slot.

See Also

ReadMapOutput for HYPE result import; PlotMapPoints for plotting HYPE results at points, e.g. sub-basin outlets.

Examples

# Import plot data and subbasin polygons
require(sf)
te1 <- ReadMapOutput(filename = system.file("demo_model",
"results", "mapCRUN.txt", package = "HYPEtools"), dt.format = NULL)
te2 <- st_read(dsn = system.file("demo_model",
"gis", "Nytorp_map.gpkg", package = "HYPEtools"))
# plot runoff map
PlotMapOutput(x = te1, map = te2, map.subid.column = 25,
var.name = "CRUN", col = ColQ)