Draw HYPE map results, with pretty scale discretizations and color ramp defaults for select HYPE variables.
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
)
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.
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.
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.
Integer, column index in the map
'data' slot
holding SUBIDs (sub-catchment IDs).
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 keyword string. Choose either "default"
for the default static plots or "leaflet"
for interactive Leaflet maps. Use "legacy"
for deprecated static plots.
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.
Logical, plot a legend along with the map.
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"
.
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.
Integer, number of significant digits to display in legend labels.
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.
DEPRECATED, for backwards compatibility only.
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).
A character vector, specifying custom labels to be used for each legend item. Works with map.type
set to default
or leaflet
.
Logical, If TRUE
, then color palette will be reversed.
Logical, plot a scale bar on map. NOTE: Scale bar may be inaccurate for geographic coordinate systems (Consider switching to projected coordinate system).
Keyword string for scalebar position for static maps. One of bl
, br
, tr
, or tl
.
Logical, plot a North arrow in static maps.
Keyword string for north arrow position for static maps. One of bl
, br
, tr
, or tl
.
Numeric, weight of subbasin boundary lines. See ggplot2::geom_sf for static maps and leaflet::addPolygons for Leaflet maps.
Numeric, opacity of subbasin boundary lines in Leaflet maps. See leaflet::addPolygons.
Numeric, opacity of subbasin polygons in Leaflet maps. See leaflet::addPolygons.
Character string of color to use to for subbasin polygon outlines. Use NA
to hide the outlines.
Character string of color to use to symbolize subbasin polygons in maps which correspond to NA
values.
Logical, if TRUE
, then a search bar will be included within Leaflet maps. See leaflet.extras::addSearchFeatures.
Logical, if TRUE
, then labels will be displayed on default static maps and in Leaflet maps when the cursor hovers over subbasins.
See ggplot2::geom_sf_text for default maps and leaflet::addPolygons for Leaflet maps.
Numeric, size of text for labels on default static plots. See ggplot2::geom_sf_text.
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.
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.
Numeric, width of output plot for static maps in units of units
. See ggplot2::ggsave.
Numeric, height of output plot for static maps in units of units
. See ggplot2::ggsave.
Keyword string for units to save static map. One of "in"
, "cm"
, "mm"
, "px"
. See ggplot2::ggsave.
Integer, resolution to save static map. See ggplot2::ggsave.
Numeric, width of the exported Leaflet map image in pixels. See mapview::mapshot.
Numeric, height of the exported Leaflet map image in pixels. See mapview::mapshot.
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.
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.
Logical. If TRUE
, outer break point values will be plotted in legend.
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.
Numeric, character expansion factor. See description of cex
in par
. Only used for default maps.
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.
Logical, default FALSE
. If TRUE
, add to existing plot. In that case map.adj
has no effect. Only used for default maps.
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.
ReadMapOutput
for HYPE result import; PlotMapPoints
for plotting HYPE results at points, e.g. sub-basin outlets.
# \donttest{
# 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)
# }
Run the code above in your browser using DataLab