% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/function_PlotEvaluationMaps.R
\name{PlotEvaluationMaps}
\alias{PlotEvaluationMaps}
\title{Function for plotting up to two HYPE simulation results in maps.}
\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{
\item{figsDirectory}{The figures output directory, an optional character string. If not set, figures are saved to the temporary directory together with the intermediate objects.}

\item{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 \code{tempdir()}, which is deleted when \code{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).}

\item{refSubass}{The mandatory reference (default) HYPE simulation subass file from which a subass object can be imported with the \code{ReadSubass()} function.}

\item{simSubass}{An optional simulation subass file from which a subass object can be imported with the \code{ReadSubass()} function. It is used for comparison to the reference simulation or for computing the relative difference in performance of two simulations.}

\item{subBasins}{A mandatory file containing the sub-basin polygons.}

\item{geoData}{A mandatory file from which an appropriate object can be imported with the \code{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.}

\item{simInfo}{A mandatory file for reading with the \code{ReadInfo()} function. It provides simulation settings e.g., start/end dates, aggregation periods, etc.}

\item{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.}

\item{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.}

\item{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.}

\item{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.}

\item{evaluation.variable}{A mandatory descriptive character string for the variable name being analyzed, e.g., "Discharge", "Snow Water Equivalent", etc.}

\item{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.}

\item{marker.size}{Optional numerical value for the marker size.}

\item{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.}

\item{show.streams}{Logical choice to show the river network on the map (default is FALSE).}

\item{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.}

\item{map.colors}{An optional vector of colors for displaying data on the maps.}

\item{domain.name}{A mandatory character string for the name of the domain. The global model is called "wwhype".}

\item{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.}

\item{num.digits}{An optional numeric value specifying the number of significant digits displayed in summary statistics. The default is 3.}

\item{file.format}{An optional string specifying the figure output format. Options are "pdf" (default) and "png".}
}
\value{
\code{PlotEvaluationMaps} does not return any objects.
}
\description{
Draws maps for selected HYPE variables and performance metrics with pretty scale discretizations and colors.
}
\details{
\code{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.
}
\examples{
\dontrun{
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"
  )
}
}

}
