PlotEvaluationMaps: Function for plotting up to two HYPE simulation results in...

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

Function for plotting up to two HYPE simulation results in maps.

Description

Draws maps for selected HYPE variables and performance metrics with pretty scale discretizations and colors.

Usage

PlotEvaluationMaps(
  figsDirectory = NULL,
  tempDirectory = tempdir(),
  refSubass,
  simSubass = NULL,
  subBasins,
  geoData,
  simInfo,
  streamShapeFile = NULL,
  criterion = c("NSE", "KGE", "CC", "MAE", "RE(%)", "RMSE", "KGESD", "KGEM"),
  visualization = c("best.simulation", "relative.difference", "comparison"),
  data.presentation = c("outlets", "polygons", "centroids"),
  evaluation.variable,
  simulation.names = NULL,
  marker.size = NULL,
  show.borders = FALSE,
  show.streams = FALSE,
  histogram.fill = NULL,
  map.colors = NULL,
  domain.name,
  gauge.list = NULL,
  num.digits = 3,
  file.format = "pdf"
)

Arguments

figsDirectory	The figures output directory, an optional character string. If not set, figures are saved to the temporary directory together with the intermediate objects.
tempDirectory	Temporary directory for intermediate data e.g., geo-spatial objects. It is a mandatory character string that is also used for figures if the figures directory is not specified. The default is temporary space tempdir(), which is deleted when R is closed down. The directory is meant to save time by writing intermediate data the first time functions are called. The data is loaded from disk during subsequent calls (e.g., to visualize the same variable with different performance metrics).
refSubass	The mandatory reference (default) HYPE simulation subass file from which a subass object can be imported with the ReadSubass() function.
simSubass	An optional simulation subass file from which a subass object can be imported with the ReadSubass() function. It is used for comparison to the reference simulation or for computing the relative difference in performance of two simulations.
subBasins	A mandatory file containing the sub-basin polygons.
geoData	A mandatory file from which an appropriate object can be imported with the ReadGeoData() function. The outlets of the gauged sub-basins in the subass files are read from this file and converted into geo-spatial objects for visualization.
simInfo	A mandatory file for reading with the ReadInfo() function. It provides simulation settings e.g., start/end dates, aggregation periods, etc.
streamShapeFile	An optional file containing the stream network of the model domain, which should be projected to the WGS84 system for consistency. If the stream network is desired without specifying this file, the 50m-resolution map from the Natural Earth portal is used (requires network connection). The layer may not provide the desired level of detail however.
criterion	An optional valid name of a HYPE subass evaluation criterion. 'NSE', 'KGE', 'CC', etc. Some are not currently implemented but NSE is plotted by default.
visualization	The mandatory type of visualization, one from "relative.difference", "best.simulation" and "comparison". The first two produce a single map while the third produces two side-by-side maps. "Comparison" and "relative difference" require two subass files.
data.presentation	The mandatory data presentation mode. One of "polygons", "outlets" or "centroids". "Polygons" are useful for spatially distributed data e.g., evaporation but take very long to plot and render for large domains. "Outlets" and "centroids" are useful for point observations, e.g., discharge; plotted at the sub-basin outlets and centroids, respectively. Distributed data for the global model is visualized with centroids.
evaluation.variable	A mandatory descriptive character string for the variable name being analyzed, e.g., "Discharge", "Snow Water Equivalent", etc.
simulation.names	A vector of two (at least one) character strings with descriptive "names" of the simulations e.g., model versions. They are used as titles on the maps and the first item is mandatory.
marker.size	Optional numerical value for the marker size.
show.borders	Logical choice to show political borders (default is FALSE). If requested, the 110m-resolution map will be downloaded from the Natural Earth portal, which requires an internet connection.
show.streams	Logical choice to show the river network on the map (default is FALSE).
histogram.fill	An optional character string of length two for the histogram fill colors. In case of a single map, the first color is used.
map.colors	An optional vector of colors for displaying data on the maps.
domain.name	A mandatory character string for the name of the domain. The global model is called "wwhype".
gauge.list	A subset of gauges to be plotted (must exist in the subass file), if some gauges in the subass file are to be excluded.
num.digits	An optional numeric value specifying the number of significant digits displayed in summary statistics. The default is 3.
file.format	An optional string specifying the figure output format. Options are "pdf" (default) and "png".

Details

PlotEvaluationMaps visualises model performances from one or two subass files. The user should provide the files as well as the subbasin polygons, the geodata and info.txt files. Relative difference in performance is computed as the (new - ref)/ref simulation *100%. The best simulation is the new in case two are provided or the reference if only one is provided.

Value

PlotEvaluationMaps does not return any objects.

Examples

## Not run: 
if (interactive()) {
  PlotEvaluationMaps(
    tempDirectory       = tempdir(),
    refSubass           = system.file("demo_model", "results", "subass1.txt", 
    package = "HYPEtools"),
    subBasins           = system.file("demo_model", "gis", "Nytorp_map.gpkg", 
    package = "HYPEtools"),
    geoData             = system.file("demo_model", "GeoData.txt",            
    package = "HYPEtools"),
    simInfo             = system.file("demo_model", "info.txt",               
    package = "HYPEtools"),
    criterion           = c('KGE'),
    visualization       = c("best.simulation"), 
    data.presentation   = c("outlets"), 
    evaluation.variable = c("discharge"),
    simulation.names    = c("Nytorp"),
    show.borders        = FALSE,
    show.streams        = FALSE,
    domain.name         = "Nytorp",
    num.digits       = 3,
    file.format         = "pdf"
  )
}

## End(Not run)

HYPEtools documentation built on April 9, 2026, 1:07 a.m.