Package 'HYPEtools'

Description

Function to find all SUBIDs of downstream sub-catchments along the main stem for a single sub-catchment.

Usage

AllDownstreamSubids(subid, gd, bd = NULL, write.arcgis = FALSE)

Arguments

Details

AllDownstreamSubids finds all downstream SUBIDs of a given SUBID along the main stem (including itself but not including potential irrigation links or groundwater flows) using GeoData columns 'SUBID' and 'MAINDOWN'. If a BranchData file is provided, the function will also include information on downstream bifurcations.

Value

AllDownstreamSubids returns a vector of downstream SUBIDs to the outlet if no BranchData is provided, otherwise a data frame with two columns downstream with downstream SUBIDs and is.branch with logical values indicating if a downstream SUBID contains a bifurcation ('branch' in HYPE terms). Downstream SUBIDs are ordered from source to final outlet SUBID.

See Also

AllUpstreamSubids, OutletSubids, OutletIds

Examples

te <- ReadGeoData(filename = system.file("demo_model", "GeoData.txt", package = "HYPEtools"))
AllDownstreamSubids(subid = 3344, gd = te)

Description

Function to find all SUBIDs of upstream sub-catchments for a single sub-catchment.

Usage

AllUpstreamSubids(
  subid,
  gd,
  bd = NULL,
  sort = FALSE,
  get.weights = FALSE,
  write.arcgis = FALSE
)

Arguments

Details

AllUpstreamSubids finds all upstream SUBIDs of a given SUBID (including itself but not including potential irrigation links or groundwater flows) using GeoData columns 'SUBID' and 'MAINDOWN', i.e the full upstream catchment. If a BranchData file is provided, the function will also include upstream areas which are connected through an upstream bifurcation. The results can be directly used as 'partial model setup file' ('pmsf.txt') using the export function WritePmsf.

If argument get.weights is set to TRUE, weighting fractions are returned along with upstream SUBIDs. The fractions are based on column 'MAINPART' in argument bd. The function considers fractions from bifurcation branches which flow into the basin, and fractions where bifurcation branches remove discharge from the basin. Fractions are incrementally updated, i.e. nested bifurcation fractions are multiplied.

For details on bifurcation handling in HYPE, see the HYPE online documentation for BranchData.txt.

Value

If get.weights is FALSE, AllUpstreamSubids returns a vector of SUBIDs, otherwise a two-column data frame with SUBIDs in the first, and flow weight fractions in the second column.

See Also

UpstreamGeoData, AllDownstreamSubids

Examples

te <- ReadGeoData(filename = system.file("demo_model", "GeoData.txt", package = "HYPEtools"))
AllUpstreamSubids(subid = 63794, gd = te)

Description

Calculate annual regimes based on long-term time series, typically imported HYPE basin output and time output result files.

Usage

AnnualRegime(
  x,
  stat = c("mean", "sum"),
  ts.in = NULL,
  ts.out = NULL,
  start.mon = 1,
  incl.leap = FALSE,
  na.rm = TRUE,
  format = c("list", "long")
)

Arguments

Details

AnnualRegime uses aggregate to calculate long-term average regimes for all data columns provided in x, including long-term arithmetic means, medians, minima and maxima, and 5%, 25%, 75%, and 95% percentiles. With HYPE result files, AnnualRegime is particularly applicable to basin and time output files imported using ReadBasinOutput and ReadTimeOutput. The function does not check if equally spaced time steps are provided in x or if the overall time period in x covers full years so that the calculated averages are based on the same number of values.

Values within each output time period can be aggregated either by arithmetic means or by sums within each period, e.g. typically means for temperatures and sums for precipitation. Long-term aggregated values are always computed as arithmetic means.

Value

If argument format is list, AnnualRegime returns a list with 8 elements and two additional attributes(). Each list element contains a named data frame with aggregated annual regime data: arithmetic means, medians, minima, maxima, and 5%, 25%, 75%, and 95% percentiles.

Each data frames contains, in column-wise order: reference dates in POSIXct format, date information as string, and aggregated variables found in x.

Reference dates are given as dates in either 1911, 1912, or 1913 (just because a leap day and outer weeks '00'/'53' occur during these years) and can be used for plots starting at the beginning of the hydrological year (with axis annotations set to months only). Daily and hourly time steps are given as is, weekly time steps are given as mid-week dates (Wednesday), monthly time steps as mid month dates (15th).

If argument format is long, AnnualRegime returns a four-column data frame with one value per row, and all variable information aligned with the values. Columns in the data frame: id with SUBIDs or HYPE variable IDs, month/week/day with aggregation time steps, name with short names of regime data (means, medians, minima, maxima, percentiles), and value with the variable value.

Attribute period contains a two-element POSIXct vector containing start and end dates of the source data. Attribute timestep contains a timestep keyword corresponding to function argument ts.out.

Note

If weekly data are provided in x, AnnualRegime will inflate x to daily time steps before computing results. Values in x will be assigned to the preceeding week days, corresponding to HYPE file output, where weekly values are conventionally printed on the last day of the week. If NA values are present in the original weekly data, these will be filled with the next available value as a side effect of the inflation.

If weekly output time steps are computed in combination with a user-defined start month, the function will round up weeks to determine the first week of the hydrological year. Weeks are identified using Monday as first day of the week and the first Monday of the year as day 1 of week 1 (see conversion code %W in strptime). Boundary weeks '00' and '53' are merged to week '00' prior to average computations.

See Also

PlotAnnualRegime

Examples

# Source data, HYPE basin output with a number of result variables
te <- ReadBasinOutput(filename = system.file("demo_model", "results", "0003587.txt", 
package = "HYPEtools"))
# Daily discharge regime, computed and observed, hydrologigical year from October 
AnnualRegime(te[, c("DATE", "COUT", "ROUT")], ts.in = "day", start.mon = 10)
# Id., aggregated to weekly means
AnnualRegime(te[, c("DATE", "COUT", "ROUT")], ts.in = "day", ts.out = "week", start.mon = 10)
# Long format, e.g. for subsequent plotting with ggplot
AnnualRegime(te[, c("DATE", "COUT", "ROUT")], ts.in = "day", ts.out = "week", format = "long", 
start.mon = 10)
# Precipitation regime, monthly sums
AnnualRegime(te[, c("DATE", "UPCPRC")], ts.in = "day", ts.out = "month", stat = "sum")

Description

Function to plot upstream-averaged landscape property classes of one or several sub-basins as bar plots, e.g. land use or soils. Builds on barplot.

Usage

BarplotUpstreamClasses(
  x,
  type = c("custom", "landuse", "soil", "crop"),
  desc = NULL,
  class.names = NULL,
  xlab = NULL,
  ylab = "Area fraction (%)",
  ylim = c(-0.05, max(x[, -1] * 150)),
  names.arg = rep("", ncol(x) - 1),
  cex.axis = 1,
  cex.names = 0.9,
  col = NULL,
  border = NA,
  legend.text = NULL,
  legend.pos = "left",
  pars = list(mar = c(1.5, 3, 0.5, 0.5) + 0.1, mgp = c(1.5, 0.3, 0), tcl = NA, xaxs =
    "i")
)

Arguments

Details

BarplotUpstreamClasses is a wrapper for barplot, with vertical labels plotted over the class group bars. Most arguments have sensible defaults, but can be adapted for fine-tuning if necessary.

Column names of x are used to link class groups to class IDs in desc. HYPE has no formal requirements on how class IDs are numbered and when one of the standard groups land use, soil, or crop are provided in x, there might be missing class IDs. Class names in desc are matched against column name endings '_x' in x. If manual names are provided in class.names, the column name endings must be a consecutive sequence from 1 to number of elements in class.names.

Value

The function returns bar midpoints, see description in barplot.

See Also

UpstreamGroupSLCClasses barplot

Examples

# Import source data
te1 <- ReadGeoData(filename = system.file("demo_model", "GeoData.txt", package = "HYPEtools"))
te2 <- ReadGeoClass(filename = system.file("demo_model", "GeoClass.txt", package = "HYPEtools"))
te3 <- ReadDescription(filename = system.file("demo_model", "description.txt", 
                       package = "HYPEtools"))
# Calculate plot data, upstream soil fractions
te4 <- UpstreamGroupSLCClasses(subid = 63794, gd = te1, gcl = te2, type = "soil")
# Function call
BarplotUpstreamClasses(x = te4, type = "s", desc = te4, ylim = c(0,100))

Description

BoxplotSLCClasses plots SLC class distributions for all SUBIDs in a GeoData data frame as boxplots. Boxes can represent distributions of area fractions

Usage

BoxplotSLCClasses(
  gd,
  gcl,
  col.landuse = "rainbow",
  col.group = NULL,
  lab.legend = NULL,
  pos.legend = 1,
  abs.area = FALSE,
  log = "",
  ylim = NULL,
  range = 0,
  mar = c(3, 3, 1, 7) + 0.1,
  mgp = c(1.5, 0.2, 0),
  tcl = 0.1,
  xaxs = "i",
  xpd = TRUE
)

Arguments

Details

BoxplotSLCClasses allows to analyze the occurrence of individual SLCs in a given model set-up. both in terms of area fractions (SLC values) and absolute areas. The function uses boxplot to plot distributions of SLCs of all SUBIDs in a GeoData data frame. Land use classes are color-coded, and soil classes marked by a point symbol below each box. Box whiskers extend to the data extremes.

Value

BoxplotSLCClasses returns a plot to the currently active plot device, and invisibly a data frame of SLC class fractions with 0 values replaced by NAs. If absolute areas are plotted, these are returned in the data frame.

Note

There is a maximum of 26 symbols available for marking soil classes. BoxplotSLCClasses can be quite crowded, depending on the number of SLCs in a model set-up. Tested and recommended plot device dimensions are 14 x 7 inches (width x height), e.g.:

> x11(width = 14, height = 7)

> png("mySLCdistri.png", width = 14, height = 7, units = "in", res = 600)

Examples

# Import source data
te1 <- ReadGeoData(filename = system.file("demo_model", "GeoData.txt", package = "HYPEtools"))
te2 <- ReadGeoClass(filename = system.file("demo_model", "GeoClass.txt", package = "HYPEtools"))
BoxplotSLCClasses(gd = te1, gcl = te2)

Description

CleanSLCClasses attempts to clean small SLC fractions within each SUBID (sub-catchment) from an imported GeoData file using user-provided area thresholds. Cleaning can be performed along class similarity rules or along SLC area alone.

Usage

CleanSLCClasses(
  gd,
  gcl,
  m1.file = NULL,
  m1.class = "s",
  m1.clean = rep(TRUE, 2),
  m1.precedence = rep(TRUE, 2),
  m2.frac = NULL,
  m2.abs = NULL,
  signif.digits = 3,
  verbose = TRUE,
  progbar = TRUE
)

Arguments

Details

CleanSLCClasses performs a clean-up of small SLC fractions in an imported GeoData file. Small SLCs are eliminated either by moving their area to similar classes according to rules which are passed to the function in a text file (Method 1), or by simply moving their area to the largest SLC in the SUBID (Method 2). Moving rules for the first method can be based on either soil classes or land use classes but these cannot be combined in one function call. Run the function two times to combine soil and land use based clean-up. Method 1 and 2, however, can be combined in one function call, in which case the rule-based classification will be executed first. Clean-up precedence in method 1: if clean-ups based on area fractions and absolute areas are combined (m1.clean = rep(TRUE, 2)), then area fractions will be cleaned first. In order to reverse precedence, call CleanSLCClasses two times with absolute area cleaning activated in first call and area fraction cleaning in second. In both methods, SLCs in each SUBID are cleaned iteratively in numerical order, starting with SLC_1. This implies a greater likelihood of eliminating SLCs with smaller indices.

Method 1

For method one, small SLC fractions are moved to either similar land use classes within the same soil class, or vice versa. Similarities are defined by the user in a tab-separated text file, which is read by CleanSLCClasses during runtime. Soil and land use classes correspond to the classes given in column two and three in the GeoClass file. The file must have the following format:

Column 1 contains the source land use or soil classes subjected to clean-up, columns 2 and 3 contain threshold values for area fractions and absolute areas. The remaining columns contain classes to which areas below threshold will be transferred, in order of precedence. Each class can have one or several transfer classes. CleanSLCClasses will derive SLC classes to clean from the given soil or land use class using the GeoClass table given in argument gcl. No header is allowed. At least one transfer class must exist, but classes can be omitted and will then be ignored by CleanSLCClasses. The order of transfer classes in the transfer file indicates transfer preference. CleanSLCClasses constructs a transfer list for each SLC class in the model set-up and per default uses the order to choose a preferred SLC to transfer to. However, if several SLCs exist for a given soil or land use class, one of them will be chosen without further sorting. If argument m1.precedence is set to FALSE for either area fractions or absolute areas, precedence will be ignored and the largest area available will be chosen to transfer small areas to. Area fraction thresholds are given as fractions of 1, absolute area thresholds as values in $m^{2}$. If an area below threshold is identified but there are no fitting SLCs available to transfer to, the area will remain unchanged.

Method 2

This method is more rigid than method one and can also be applied as a post-processor after clean-up using method 1 to force a removal of all SLCs below a given threshold from a GeoData file (method 1 cleaning can be be very selective, depending on how many transfer classes are provided in the transfer table). Cleaning thresholds for method 2 area fractions and absolute areas are given in arguments m2.frac and m2.abs. SLC areas below the given thresholds will be moved to the largest SLC in the given SUBID without considering any similarity between classes.

Value

CleanSLCClasses returns the GeoData data frame passed to the function in argument gd with cleaned SLC class columns.

See Also

RescaleSLCClasses for re-scaling of SLC area fraction sums.

Examples

# Import source data
te1 <- ReadGeoData(filename = system.file("demo_model", "GeoData.txt", package = "HYPEtools"))
te2 <- ReadGeoClass(filename = system.file("demo_model", "GeoClass.txt", package = "HYPEtools"))
# Clean-up using method 2, 0.5 % area fraction threshold and 100 m^2 absolute area threshold
te3 <- CleanSLCClasses(gd = te1, gcl = te2, m2.frac = 0.005, m2.abs = 100)
# Detailed comparison with function CompareFiles
te4 <- CompareFiles(te1, te3, type = "GeoData")
te4

Description

Compare HYPE model files to identify any differences, typically used to check that no undesired changes were made when writing a new file.

Usage

CompareFiles(
  x,
  y,
  type = c("AquiferData", "BasinOutput", "BranchData", "CropData", "DamData", "ForcKey",
    "FloodData", "GeoClass", "GeoData", "Info", "LakeData", "MapOutput", "MgmtData",
    "Optpar", "Par", "PointSourceData", "Obs", "Simass", "Subass", "TimeOutput", "Xobs"),
  by = NULL,
  compare.order = TRUE,
  threshold = 1e-10,
  ...
)

Arguments

Details

CompareFiles compares two HYPE model files and identifies any differences in values. The function reads two model files, compares the values in columns with corresponding names, and returns a data frame consisting of rows/columns with any differences. Values that are the same in both files are set to NA. If numeric values in two columns aren't exactly the same, then the difference between the values will be taken and compare to theshold. If the difference is <= theshold, then the values will be considered the equal and set to NA. The function is primarily intended as a check to ensure that no unintended changes were made when writing model files using the various HYPEtools write functions. However, it can also be used to e.g. compare files between different model versions.

Value

Returns invisibly a data frame containing rows and columns in which differences exist between x and y. Values that are the same in both files are set to NA. If the returned data frame has 0 row, then there were no differences between the files.

Examples

# Import demo model GeoData file, edit a SUBID
te1 <- ReadGeoData(filename = system.file("demo_model", "GeoData.txt", package = "HYPEtools"))
te1$SUBID[1] <- 1
# Compare with original file
te2 <- CompareFiles(system.file("demo_model", "GeoData.txt", package = "HYPEtools"), te1, 
                    type = "GeoData")
te2

Description

ConvertDischarge converts volumetric discharge to specific discharge (unit area discharge) and vice versa.

Usage

ConvertDischarge(q, area, from = "m3s", to = "mmd")

Arguments

Details

ConvertDischarge is a simple conversion function, most likely to be used in combination with apply or related functions.

Value

ConvertDischarge returns a numeric object of the same type as provided in argument q.

Examples

ConvertDischarge(6, 400000000)
ConvertDischarge(c(1.1, 1.2, 1.9, 2.8, 2, 1.5, 1.3, 1.2, 1.15, 1.1), 
                 from = "mmd", to = "ls", area = 1.2e6)

Description

CreateOptpar creates a list representing a HYPE optpar.txt file from an imported par.txt file and a selection of parameters.

Usage

CreateOptpar(
  x,
  pars,
  tasks = data.frame(character(), character()),
  comment = "",
  fun.ival = NULL
)

Arguments

Details

CreateOptpar makes it a bit more convenient to compose a HYPE optimization file. The function creates a template with all parameters to be included in an optimization run.

Parameter boundaries for individual classes have to be adapted after creation of the template, the function takes the existing parameter value(s) in x as upper and lower boundaries.

Parameter step width intervals (third parameter rows in optpar.txt files) are calculated with an internal function which per default returns the nearest single 1/1000th of the parameter value, with conditional replacement of '0' intervals:

function(x) {
  res <- 10^floor(log10(x/1000))
  ifelse(res == 0, .1, res)
}

Alternative functions can be passed to CreateOptpar using argument fun.ival. Such functions must have a single argument x, which represents the parameter value taken from argument x. The function is applied to all parameters in the resulting optpar list.

Value

The function returns a list with elements as described in ReadOptpar.

See Also

ReadOptpar WriteOptpar OptimisedClasses

Examples

# Import a HYPE parameter file
te1 <- ReadPar(filename = system.file("demo_model", "par.txt", package = "HYPEtools"))
# Create optimization parameters for a Monte Carlo run with 1000 iterations
te2 <- data.frame(key = c("task", "num_mc", "task"), value = c("MC", 1000, "WS"))
# Create an optpar file structure for HYPE recession coefficients
te3 <- CreateOptpar(x = te1, pars = c("rrcs1", "rrcs2"), tasks = te2)
te3

Description

Pre-defined color ramp palettes which are used in other HYPEtools functions.

Usage

ColNitr(n)

ColPhos(n)

ColPrec(n)

ColTemp(n)

ColQ(n)

ColDiffTemp(n)

ColDiffGeneric(n)

ColBlues(n)

ColReds(n)

ColGreens(n)

ColYOB(n)

ColPurples(n)

Arguments

Details

These functions build on calls to colorRampPalette.

Value

All functions return vectors of length n with interpolated RGB color values in hexadecimal notation (see rgb).

Examples

ColNitr(10)
ColGreens(6)
barplot(rep(1, 11), col = ColTemp(11))

Description

Function to find direct upstream SUBIDs including flow fractions for MAINDOWN/BRANCHDOWN splits for a single sub-catchment or all sub-catchments in a GeoData-like data frame.

Usage

DirectUpstreamSubids(subid = NULL, gd, bd = NULL)

Arguments

Details

DirectUpstreamSubids identifies direct upstream SUBIDs for a user-provided target SUBID or for all SUBIDs given in a data frame gd, typically an imported GeoData file.

A sub-catchment in HYPE can have several upstream sub-catchments. If there are more than one upstream sub-catchments, the downstream sub-catchment is a confluence. HYPE stores these connections in the GeoData file, in downstream direction, given as downstream SUBID in column 'MAINDOWN'. Bifurcations, i.e. splits in downstream direction, are also possible to model in HYPE. These additional downstream connections are provided in the BranchData file, together with flow fractions to each downstream SUBID.

Formally, gd can be any data frame which contains columns 'SUBID' and 'MAINDOWN' (not case-sensitive), and bd any data frame which contains three columns: 'BRANCHID', 'SOURCEID', and 'MAINPART', and optionally columns 'MAXQMAIN', 'MINQMAIN', 'MAXQBRANCH'. Typically, these are HYPE data files imported through ReadGeoData and ReadBranchData. See HYPE documentation for further details on connections Between SUBIDs in the model.

Value

DirectUpstreamSubids always returns a list. If argument subid is non-NULL, a list with two elements is returned: subid contains an integer giving the target SUBID and upstr.df contains a data frame with columns upstream (upstream SUBID), is.main (logical, TRUE if it is a MAINDOWN connection), fraction (fraction of flow going into the target SUBID), and llim and ulim giving upper and lower flow boundaries which optionally limit flow into the target SUBID.

If no specific SUBID was provided, DirectUpstreamSubids returns a list with upstream information for all SUBIDs in argument gd, each list element containing the list described above, i.e. with an integer element (SUBID) and a data frame element (upstream connections).

See Also

AllUpstreamSubids, which returns all upstream SUBIDs, i.e. the full upstream network up to the headwaters, for a given SUBID.

Examples

te <- ReadGeoData(filename = system.file("demo_model", "GeoData.txt", package = "HYPEtools"))
DirectUpstreamSubids(subid = 3594, gd = te)

Description

distinctColorPalette generates an attractive palette of random colors.

Usage

distinctColorPalette(count = 1, seed = NULL, darken = 0)

Arguments

Details

Adapted from the randomcoloR package https://cran.r-project.org/package=randomcoloR.

Value

distinctColorPalette returns a character vector of count optimally distinct colors in hexadecimal codes.

Examples

distinctColorPalette()

Description

EquallySpacedObs creates equally spaced time series with missing observations from a data frame with irregular observations.

Usage

EquallySpacedObs(x, sort.data = TRUE, timestep, ts.col = 1)

Arguments

Details

EquallySpacedObs will preserve additional attributes present in x. If datetime column is of class Date, there may occur problems with daylight saving time shifts. To avoid problems, use class POSIXct and set time zone to "UTC".

Value

EquallySpacedObs returns a dataframe.

Examples

te <- data.frame(date = as.POSIXct(c("2000-01-01", "2000-02-01"), tz = "gmt"), obs = c(1, 2))
EquallySpacedObs(x = te, timestep = "day")

Description

This function calculates quantiles suitable for duration curves of environmental time series data.

Usage

ExtractFreq(
  data,
  probs = c(0, 1e-05, 1e-04, 0.001, seq(0.01, 0.99, by = 0.01), 0.999, 0.9999, 0.99999,
    1)
)

Arguments

Details

ExtractFreq is a convenience wrapper function, it uses quantile to calculate the quantiles of one or more time series with a density appropriate for duration curves. NAs are allowed in the input data. For the results to be meaningful, input should represent equally-spaced time series, e.g. HYPE basin output files.

Value

ExtractFreq returns a dataframe with probabilities in the first column, and quantiles of data in the following columns. Number of observations per variable in data are given in an attribute n.obs (see attributes).

See Also

PlotDurationCurve

Examples

ExtractFreq(rnorm(1000))

Description

Calculate aggregated statistics from long-term time series, typically imported HYPE time output files.

Usage

ExtractStats(
  x,
  start.mon = 1,
  aggperiod = c("year", "season1", "season2", "month"),
  timestep = attr(x, "timestep"),
  subid = attr(x, "subid"),
  FUN,
  ...
)

Arguments

Details

ExtractStats uses aggregate to calculate statistics for all data columns provided in x. Argument start.mon allows to define the start of the hydrological year. Hydrological seasons begin with winter (season1) or autumn (season2).

Value

ExtractStats returns a dataframe with starting dates for each aggregation period in the first column, and a descriptive aggregation period name in the second. Remaining columns contain aggregated results as ordered in x. Additional attributes subid with subbasin IDs, timestep with time step of the source data, and period with a two-element POSIXct vector containing start and end dates of the source data.

Note

If FUN returns several values per aggregation period, these are returned in nested columns in the resulting dataframe. See Value section for aggregate and example code below.

Examples

# Import example data
te1 <- ReadTimeOutput(filename = system.file("demo_model", "results",
"timeCOUT.txt", package = "HYPEtools"), dt.format = "%Y-%m")
# Extract maxima
ExtractStats(x = te1, start.mon = 1, FUN = max)
# Multiple result stats: Extract min, mean, and max in one go:
te2 <- ExtractStats(x = te1, start.mon = 1,
FUN = function(x) {c(min(x), mean(x), max(x))})
# extract mean from resulting nested dataframe:
data.frame(te2[, 1:2], sapply(te2[, -c(1:2)], function(x){x[, 2]}))

Description

Numerical goodness-of-fit measures between sim and obs, with treatment of missing values.

Usage

gof(sim, obs, ...)

## Default S3 method:
gof(
  sim,
  obs,
  na.rm = TRUE,
  do.spearman = FALSE,
  s = c(1, 1, 1),
  method = c("2009", "2012"),
  start.month = 1,
  digits = 2,
  fun = NULL,
  ...,
  epsilon.type = c("none", "Pushpalatha2012", "otherFactor", "otherValue"),
  epsilon.value = NA
)

valindex(sim, obs, ...)

## Default S3 method:
valindex(sim, obs, ...)

rPearson(sim, obs, ...)

## Default S3 method:
rPearson(
  sim,
  obs,
  fun = NULL,
  ...,
  epsilon.type = c("none", "Pushpalatha2012", "otherFactor", "otherValue"),
  epsilon.value = NA
)

sKGE(sim, obs, ...)

## Default S3 method:
sKGE(
  sim,
  obs,
  s = c(1, 1, 1),
  na.rm = TRUE,
  method = c("2009", "2012"),
  start.month = 1,
  out.PerYear = FALSE,
  fun = NULL,
  ...,
  epsilon.type = c("none", "Pushpalatha2012", "otherFactor", "otherValue"),
  epsilon.value = NA
)

KGE(sim, obs, ...)

## Default S3 method:
KGE(
  sim,
  obs,
  s = c(1, 1, 1),
  na.rm = TRUE,
  method = c("2009", "2012", "2021"),
  out.type = c("single", "full"),
  fun = NULL,
  ...,
  epsilon.type = c("none", "Pushpalatha2012", "otherFactor", "otherValue"),
  epsilon.value = NA
)

NSE(sim, obs, ...)

## Default S3 method:
NSE(
  sim,
  obs,
  na.rm = TRUE,
  fun = NULL,
  ...,
  epsilon.type = c("none", "Pushpalatha2012", "otherFactor", "otherValue"),
  epsilon.value = NA
)

pbias(sim, obs, ...)

## Default S3 method:
pbias(
  sim,
  obs,
  na.rm = TRUE,
  dec = 1,
  fun = NULL,
  ...,
  epsilon.type = c("none", "Pushpalatha2012", "otherFactor", "otherValue"),
  epsilon.value = NA
)

mae(sim, obs, ...)

## Default S3 method:
mae(
  sim,
  obs,
  na.rm = TRUE,
  fun = NULL,
  ...,
  epsilon.type = c("none", "Pushpalatha2012", "otherFactor", "otherValue"),
  epsilon.value = NA
)

VE(sim, obs, ...)

## Default S3 method:
VE(
  sim,
  obs,
  na.rm = TRUE,
  fun = NULL,
  ...,
  epsilon.type = c("none", "Pushpalatha2012", "otherFactor", "otherValue"),
  epsilon.value = NA
)

Arguments

Details

The gof, mae, pbias, NSE, rPearson, sKGE, and KGE functions are provided to calculate goodness of fit statistics. The functions were adapted from the hydroGOF package https://github.com/hzambran/hydroGOF.

Value

gof Returns a matrix of goodness of fit statistics. mae, pbias, NSE, rPearson, sKGE, and KGE return a numeric of the goodness of fit statistic.

Examples

gof(sim = sample(1:100), obs = sample(1:100))

Description

GroupSLCClasses calculates grouped sums for SLC classes (area fractions or absolute areas) based on land use, soil, or crop groups in a GeoClass table, or any other user-provided grouping index.

Usage

GroupSLCClasses(
  gd,
  gcl = NULL,
  type = c("landuse", "soil", "crop"),
  group = NULL,
  abs.area = FALSE,
  verbose = TRUE
)

Arguments

Details

If absolute areas are calculated, area units will correspond to areas provided in gd.

Value

GroupSLClasses returns the data frame with SUBIDs, SUBID areas, and grouped SLC class columns.

Examples

# Import source data
te1 <- ReadGeoData(filename = system.file("demo_model", "GeoData.txt", package = "HYPEtools"))
te2 <- ReadGeoClass(filename = system.file("demo_model", "GeoClass.txt", package = "HYPEtools"))
# Calculate soil groups
GroupSLCClasses(gd = te1, gcl = te2, type = "s")

Description

Function to calculate nutrient load retention fractions in groundwater parts of HYPE, i.e. after root zone retention. See Details for exact definition.

Usage

GwRetention(nfrz, nfs3, gts3, gd, par, unit.area = TRUE, nutrient = "tn")

Arguments

Details

GwRetention calculates a groundwater nutrient retention as fractions of outgoing and incoming loads using HYPE soil load variables. Incoming loads include drainage into layer 3 from the root zone (defined as soil layer 1 and 2), rural load fractions into soil (dependent on parameter locsoil), tile drainage, surface flow, and flow from layer 1 and 2. Outgoing loads include runoff from all soil layers, tile drain, and surface flow.

The retention fraction R is calculated as (see also the variable description in the HYPE online documentation):

$R = 1 - \frac{OUT}{IN} = 1 - \frac{nfrz - gts3 + nfs3 + locsoil * lr}{nfrz + locsoil * lr}$ -

$li = nfrz + locsoil * lr$ [kg/y]

$lr = LOC_VOL * LOC_TN * 0.365$ [kg/y]

, where li is incoming load to groundwater (leaching rates), lr is rural load (total from GeoData converted to kg/yr; locsoil in the formula converts it to rural load into soil layer 3), and nfrz, gts3, nfs3 are soil loads as in function arguments described above. See Examples for HYPE variable names for TN loads.

Columns SUBID, LOC_VOL, and LOC_TN must be present in gd, for a description of column contents see the GeoData file description in the HYPE online documentation. Column names are not case-sensitive.

Value

GwRetention returns a three-column data frame, containing SUBIDs, retention in groundwater as a fraction of incoming loads (if multiplied by 100, it becomes \ .

Examples

# Create dummy data
te1 <- ReadGeoData(filename = system.file("demo_model",
"GeoData.txt", package = "HYPEtools"))
te1$loc_tn <- runif(n = nrow(te1), min = 0, max = 100)
te1$loc_vol <- runif(n = nrow(te1), min = 0, max = 2)
te2 <- ReadPar(filename = system.file("demo_model",
"par.txt", package = "HYPEtools"))
te2$locsoil <- .3
# HYPE soil load (sl) variables for TN, dummy loads
GwRetention(nfrz = data.frame(SUBID = te1$SUBID, SL06 = runif(n = nrow(te1), 10, 50)), 
            gts3 = data.frame(SUBID = te1$SUBID, SL17 = runif(n = nrow(te1), 10, 50)), 
            nfs3 = data.frame(SUBID = te1$SUBID, SL18 = runif(n = nrow(te1), 10, 50)), 
            gd = te1, par = te2)

Description

Function to find all headwater SUBIDs of a HYPE model domain.

Usage

HeadwaterSubids(gd)

Arguments

Details

HeadwaterSubids finds all headwater SUBIDs of a model domain as provided in a 'GeoData.txt' file, i.e. all subcatchments which do not have any upstream subcatchments.

Value

HeadwaterSubids returns a vector of outlet SUBIDs.

See Also

AllUpstreamSubids

Examples

te <- ReadGeoData(filename = system.file("demo_model", "GeoData.txt", package = "HYPEtools"))
HeadwaterSubids(gd = te)

Description

These are simple convenience wrapper functions to quickly query and assign values of attributes which are added to HYPE data on import.

Usage

datetime(x)

datetime(x) <- value

hypeunit(x)

hypeunit(x) <- value

obsid(x)

obsid(x) <- value

outregid(x)

outregid(x) <- value

subid(x)

subid(x) <- value

timestep(x)

timestep(x) <- value

variable(x)

variable(x) <- value

Arguments

Details

These functions are just shortcuts for attr.

Value

The extractor functions return the value of the respective attribute or NULL if no matching attribute is found.

Examples

te <- ReadBasinOutput(filename = system.file("demo_model", "results",
"0003587.txt", package = "HYPEtools"))
hypeunit(te)
timestep(te)
subid(te)

Description

These are simple convenience wrapper functions to export various HYPE data files from R.

Usage

WriteAquiferData(x, filename, verbose = TRUE)

WriteOutregions(x, filename, verbose = TRUE)

WriteBranchData(x, filename, verbose = TRUE)

WriteCropData(x, filename, verbose = TRUE)

WriteDamData(x, filename, verbose = TRUE)

WriteFloodData(x, filename, verbose = TRUE)

WriteLakeData(x, filename, verbose = TRUE)

WriteMgmtData(x, filename, verbose = TRUE)

WritePointSourceData(x, filename, verbose = TRUE)

WriteForcKey(x, filename)

WriteGlacierData(x, filename, verbose = TRUE)

Arguments

Details

Hype data file exports, simple fwrite wrappers with formatting options adjusted to match HYPE file specifications:

• LakeData.txt

• DamData.txt

• MgmtData.txt

• AquiferData.txt

• PointSourceData.txt

• GlacierData.txt

• CropData.txt

• BranchData.txt

• forckey.txt

• Outregions.txt

In most files, HYPE requires NA-free input in required columns, but empty values are allowed in additional comment columns which are not read by HYPE. Informative warnings will be thrown if NAs are found during export. Character string lengths in comment columns of HYPE data files are restricted to 100 characters, the functions will return with a warning if longer strings were exported.

Value

No return value, called for export to text files.

Examples

te <- ReadForcKey(filename = system.file("demo_model", "ForcKey.txt", package = "HYPEtools"))
WriteForcKey(x = te, filename = tempfile())

Description

These are simple convenience wrapper functions to import various HYPE data files as data frame into R.

Usage

ReadAquiferData(
  filename = "AquiferData.txt",
  verbose = TRUE,
  header = TRUE,
  na.strings = "-9999",
  sep = "\t",
  stringsAsFactors = FALSE,
  encoding = c("unknown", "latin1", "UTF-8"),
  ...
)

ReadOutregions(
  filename = "Outregions.txt",
  verbose = TRUE,
  header = TRUE,
  na.strings = "-9999",
  sep = "\t",
  stringsAsFactors = FALSE,
  encoding = c("unknown", "latin1", "UTF-8"),
  ...
)

ReadBranchData(
  filename = "BranchData.txt",
  verbose = TRUE,
  header = TRUE,
  na.strings = "-9999",
  sep = "\t",
  stringsAsFactors = FALSE,
  encoding = c("unknown", "latin1", "UTF-8"),
  ...
)

ReadCropData(
  filename = "CropData.txt",
  verbose = TRUE,
  header = TRUE,
  na.strings = "-9999",
  sep = "\t",
  stringsAsFactors = FALSE,
  encoding = c("unknown", "latin1", "UTF-8"),
  ...
)

ReadDamData(
  filename = "DamData.txt",
  verbose = TRUE,
  header = TRUE,
  na.strings = "-9999",
  sep = "\t",
  quote = "",
  stringsAsFactors = FALSE,
  encoding = c("unknown", "latin1", "UTF-8"),
  ...
)

ReadFloodData(
  filename = "FloodData.txt",
  verbose = TRUE,
  header = TRUE,
  na.strings = "-9999",
  sep = "\t",
  quote = "",
  stringsAsFactors = FALSE,
  encoding = c("unknown", "latin1", "UTF-8"),
  ...
)

ReadGlacierData(
  filename = "GlacierData.txt",
  verbose = TRUE,
  header = TRUE,
  na.strings = "-9999",
  sep = "\t",
  stringsAsFactors = FALSE,
  encoding = c("unknown", "latin1", "UTF-8"),
  ...
)

ReadLakeData(
  filename = "LakeData.txt",
  verbose = TRUE,
  header = TRUE,
  na.strings = "-9999",
  sep = "\t",
  quote = "",
  stringsAsFactors = FALSE,
  encoding = c("unknown", "latin1", "UTF-8"),
  ...
)

ReadMgmtData(
  filename = "MgmtData.txt",
  verbose = TRUE,
  header = TRUE,
  na.strings = "-9999",
  sep = "\t",
  stringsAsFactors = FALSE,
  encoding = c("unknown", "latin1", "UTF-8"),
  ...
)

ReadPointSourceData(
  filename = "PointSourceData.txt",
  verbose = TRUE,
  header = TRUE,
  na.strings = "-9999",
  sep = "\t",
  stringsAsFactors = FALSE,
  encoding = c("unknown", "latin1", "UTF-8"),
  data.table = FALSE,
  ...
)

ReadAllsim(filename = "allsim.txt", na.strings = "-9999")

ReadForcKey(
  filename = "ForcKey.txt",
  sep = "\t",
  encoding = c("unknown", "latin1", "UTF-8")
)

ReadUpdate(
  filename = "update.txt",
  header = TRUE,
  sep = "\t",
  stringsAsFactors = FALSE,
  encoding = c("unknown", "latin1", "UTF-8"),
  data.table = FALSE,
  ...
)

Arguments

Details

Hype data file imports, simple read.table or fread wrappers with formatting arguments set to match HYPE file specifications:

• LakeData.txt

• DamData.txt

• MgmtData.txt

• AquiferData.txt

• PointSourceData.txt

• GlacierData.txt

• CropData.txt

• BranchData.txt

• Outregions.txt

• allsim.txt

• update.txt

In most files, HYPE requires NA-free input in required columns, but empty values are allowed in additional comment columns. Informative warnings will be thrown if NAs are found during import.

Value

Imported files are returned as data frames.

Examples

te <- ReadForcKey(filename = system.file("demo_model", "ForcKey.txt", package = "HYPEtools"))

Description

Constructor function for data frames which hold HYPE GeoData tables with information on sub-basins.

Usage

HypeGeoData(x)

Arguments

Details

S3 constructor function for data frames which hold HYPE GeoData tables. These are normal data frames with at least five mandatory columns, all numeric: AREA, SUBID, MAINDOWN, RIVLEN, and SLC_n, where n are consecutive SLC class numbers (up to 999).See also the HYPE file description for GeoData.txt files for reference.

Usually, this class will be assigned to GeoData tables on import with ReadGeoData. A summary method exists for HypeGeoData data frames.

Value

Returns a data frame with added class attribute HypeGeoData.

See Also

ReadGeoData

Examples

te <- data.table::fread(file = system.file("demo_model",
"GeoData.txt", package = "HYPEtools"), data.table = FALSE)
HypeGeoData(x = te)
summary(te)

Description

Constructor function for arrays which hold equidistant time series of multiple HYPE variables for a single sub-basin and multiple model runs, typically imported HYPE basin output results.

Usage

HypeMultiVar(
  x,
  datetime,
  hype.var,
  hype.unit,
  subid = NULL,
  outregid = NULL,
  hype.comment = ""
)

Arguments

Details

S3 class constructor function for array objects which can hold (multiple) HYPE basin output results.

Value

Returns a 3-dimensional array with [time, variable, iteration] dimensions and additional attributes:

datetime

A vector of date-times. Corresponds to 1st array dimension.

variable

A character vector of HYPE output variable IDs.

hypeunit

A character vector of HYPE output variable units.

subid

A single SUBID.

outregid

A single OUTREGID.

timestep

A character keyword for the time step.

comment

A comment string, currently used for class group outputs.

Examples

# import a basin output file
te1 <- ReadBasinOutput(filename = system.file("demo_model",
"results", "0003587.txt", package = "HYPEtools"))
# create a dummy array with two iterations from imported basin file
te2 <- array(data = c(unlist(te1[, -1]),  unlist(te1[, -1])), 
             dim = c(nrow(te1), ncol(te1) - 1, 2), 
             dimnames = list(rownames(te1), colnames(te1)[-1]))
# Construct HypeMultiVar array
HypeMultiVar(te2, datetime = te1$DATE, hype.var = variable(te1),
hype.unit = hypeunit(te1), subid = 3587)

Description

Constructor function for arrays which hold equidistant time series of a single HYPE variable for multiple sub-basins and multiple model runs, typically imported time and map output results.

Usage

HypeSingleVar(x, datetime, subid = NULL, outregid = NULL, hype.var)

Arguments

Details

S3 class constructor function for array objects which can hold (multiple) HYPE time or map output results.

Value

Returns a 3-dimensional array with [time, subid, iteration] dimensions and additional attributes:

datetime

A vector of date-times. Corresponds to 1st array dimension.

subid

A vector of SUBIDs. Corresponds to 2nd array dimension (NA, if it does not apply to data contents).

outregid

A vector of OUTREGIDs. Corresponds to 2nd array dimension (NA, if it does not apply to data contents).

variable

HYPE output variable ID.

timestep

A character keyword for the time step.

Examples

# Import a time output file
te1 <- ReadTimeOutput(filename = system.file("demo_model", "results",
"timeCOUT.txt", package = "HYPEtools"), dt.format = "%Y-%m")
# Create a dummy array with two iterations from imported time file
te2 <- array(data = c(unlist(te1[, -1]),  unlist(te1[, -1])), 
             dim = c(nrow(te1), ncol(te1) - 1, 2), 
             dimnames = list(rownames(te1), colnames(te1)[-1]))
# Construct HypeSingleVar array
HypeSingleVar(x = te2, datetime = te1$DATE,
subid = subid(te1), hype.var = variable(te1))

Description

Quickly query vectors of HYPE sub-basin IDs (SUBID) for various properties.

Usage

IsHeadwater(subid, gd)

IsOutlet(subid, gd)

IsRegulated(subid, gd, dd = NULL, ld = NULL)

Arguments

Details

These are convenience functions to query subbasin properties. Some functions can be inefficient if applied to many or all subbasins of a HYPE model setup and more efficient functions may exist in HYPEtools, see links in See also section below or browse the package index.

Value

The functions return a logical vector of the same length as subid, with NA values for all SUBIDs which do not exist in gd.

See Also

AllUpstreamSubids(); AllDownstreamSubids(); OutletSubids(); OutletIds()

Examples

te <- ReadGeoData(filename = system.file("demo_model", "GeoData.txt", package = "HYPEtools"))
IsHeadwater(subid = 40556, gd = te)
IsHeadwater(subid = te$SUBID, gd = te)

Description

Constructor function for data frames which hold HYPE Xobs.txt file contents, i.e. time series of a multiple observation variables for multiple sub-basins and equidistant time steps in POSIXct format in the first column.

Usage

HypeXobs(x, comment, variable, subid, verbose = TRUE)

Arguments

Details

S3 class constructor function for HypeXobs data frame objects which hold HYPE Xobs.txt file contents. Xobs.txt files contain three header rows, see the Xobs.txt description in the HYPE documentation. These headers are stored as additional attributes in objects.

Value

Returns a data frame of class HypeXobs with additional attributes:

comment

A character vector.

variable

A character vector of HYPE variable IDs.

subid

A vector of SUBIDs.

timestep

Time step keyword, "day", or "n hour" (n = number of hours). NULL, if x contains just one row.

Examples

# Use the Xobs file import function instead of the class constructor for standard work flows
te <- ReadXobs(file = system.file("demo_model", "Xobs.txt", package = "HYPEtools"))
summary(te)
# Class constructor
HypeXobs(x = as.data.frame(te), comment = comment(te), variable = variable(te), subid = subid(te))

Description

Add/Remove lines to HYPE info.txt files

Usage

AddInfoLine(info, name, value, after = NULL)

RemoveInfoLine(info, name)

Arguments

Details

The AddInfoLine and RemoveInfoLine functions provide features to add/remove lines to an imported info.txt file. Info.txt codes can be found on the HYPE Wiki.

Value

AddInfoLine and RemoveInfoLine return a named list in the info.txt file structure.

Examples

info <- ReadInfo(filename = system.file("demo_model",
"info.txt", package = "HYPEtools"))
info <- AddInfoLine(info, name = "testline", value = "testvalue")
info <- RemoveInfoLine(info, name = "testline")

Description

By default, this function creates an sf object which contains regional irrigation connections between source and target HYPE sub-catchments. However, this function can also be used to create interactive Leaflet maps.

Usage

MapRegionalSources(
  data,
  map,
  map.subid.column = 1,
  group.column = NULL,
  group.colors = NULL,
  digits = 3,
  progbar = FALSE,
  map.type = "default",
  plot.scale = TRUE,
  plot.searchbar = FALSE,
  weight = 0.5,
  opacity = 1,
  fillColor = "#4d4d4d",
  fillOpacity = 0.25,
  line.weight = 5,
  line.opacity = 1,
  seed = NULL,
  darken = 0,
  font.size = 10,
  file = "",
  vwidth = 1424,
  vheight = 1000,
  html.name = ""
)

Arguments

Details

MapRegionalSources can return static plots or interactive Leaflet maps depending on value provided for the argument map.type. By default, MapRegionalSources creates an sf object from HYPE SUBID centerpoints using a table of SUBID pairs. Regional irrigation sources in HYPE are transfers from outlet lakes or rivers in a source sub-catchment to the soil storage of irrigated SLC classes (Soil, Land use, Crop) in a target sub-catchment. If map.type is set to "leaflet", then MapRegionalSources returns an object of class leaflet.

Value

For default static maps, MapRegionalSources returns an sf object containing columns SUBID (irrigation target sub-catchment), REGSRCID (irrigation source sub-catchment), and Length_[unit] (distance between sub-catchments) where 'unit' is the actual length unit of the distances. The projection of the returned object is always identical to the projection of argument map. For interactive Leaflet maps, PlotMapOutput returns an object of class leaflet. If map contains polygon data, then the interactive map will include the polygons as a background layer.

Examples

# Import subbasin centroids and subbasin polygons (to use as background)
require(sf)
te1 <- st_read(dsn = system.file("demo_model", "gis",
"Nytorp_centroids.gpkg", package = "HYPEtools"))
te2 <- st_read(dsn = system.file("demo_model", "gis",
"Nytorp_map.gpkg", package = "HYPEtools"))
# Create dummy MgmtData file with irrigation links
te3 <- data.frame(SUBID = c(3594, 63794), REGSRCID = c(40556, 3486))

# Plot regional irrigation links between subbasins with subbasin outlines as background
MapRegionalSources(data = te3, map = te1, map.subid.column = 25)
plot(st_geometry(te2), add = TRUE, border = 2)

Description

Merge an imported HYPE GeoData table of class link{HypeGeoData} with another data frame.

Usage

## S3 method for class 'HypeGeoData'
merge(x, y, all.x = TRUE, sort = NA, ...)

Arguments

Details

merge.HypeGeoData allows to merge new columns to an existing HYPE GeoData table, while preserving the HypeGeoData class attribute. Duplicate columns are marked with a ".y"-suffix for the merged y data frame.

The following arguments of the default method are hard-coded:

• by, by.x, by.y, set to "SUBID"

• suffixes, set to c("", ".y")

The method warns if any of these arguments is supplied by the user. To override, use the GeoData table as argument y or call the data frame method explicitly (merge.data.frame()).

Value

A HypeGeoData data frame.

See Also

merge, the S3 generic function.

Examples

# import and create dummy data
te1 <- ReadGeoData(filename = system.file("demo_model",
"GeoData.txt", package = "HYPEtools"))
te2 <- data.frame(SUBID = sample(x = te1$SUBID, size = 10),
loc_vol = runif(n = 10, 10, 50))
merge(x = te1, y = te2)

Description

Function to merge two HYPE observation data frames, with handling of overlapping time periods and time periods gaps as well as merging of common columns.

Usage

MergeObs(x, y)

Arguments

Details

MergeObs handles time steps of different lengths (e.g. daily, hourly), but requires identical time step lengths from both inputs data frames.

In case of common columns (identical date and SUBID combinations in x and y), values from columns in x will take precedence, and values from y will only be added if x values are missing.

Value

MergeObs returns a data frame with merged Obs data.

Examples

# Import dummy data, add new observations to second Obs table, and merge
te1 <- ReadObs(filename = system.file("demo_model", "Tobs.txt", package = "HYPEtools"))
te2 <- ReadObs(filename = system.file("demo_model", "Tobs.txt", package = "HYPEtools"))
te2$X0000[1:365] <- runif(n = 365, -20, 25)
MergeObs(x = te1, y = te2)

Description

Function to merge two Xobs data frames, with handling of overlapping time periods and time periods gaps as well as merging of common columns.

Usage

MergeXobs(x, y, comment = "")

Arguments

Details

MergeXobs handles time steps of different lengths (e.g. daily, hourly), but requires identical time step lengths from both inputs data frames. The functions expects data frames of class HypeXobs or data frames with comparable structure and will throw a warning if the class attribute is missing.

In case of common columns (identical observation variable and SUBID combinations in x and y), values from columns in x will take precedence, and values from y will only be added if x values are missing

Value

MergeXobs returns a data frame with attributes for Xobs data.

Examples

# Import dummy data, add new observations to second Xobs table
te1 <- ReadXobs(filename = system.file("demo_model", "Xobs.txt", package = "HYPEtools"))
te2 <- ReadXobs(filename = system.file("demo_model", "Xobs.txt", package = "HYPEtools"))
te2$WSTR_40541[1:10] <- runif(n = 10, 50, 100)
MergeXobs(x = te1, y = te2)

Description

Nash-Sutcliffe Efficiency calculation for imported HYPE outputs with single variables for several catchments, i.e. time and map files, optionally multiple model run iterations combined.

Usage

## S3 method for class 'HypeSingleVar'
NSE(sim, obs, na.rm = TRUE, progbar = TRUE, ...)

Arguments

Value

NSE.HypeSingleVar returns a 2-dimensional array of NSE performances for all SUBIDs and model iterations provided in argument sim, with values in the same order as the second and third dimension in sim, i.e. [subid, iteration].

Examples

# Create dummy data, discharge observations with added white noise as model simulations
te1 <- ReadObs(filename = system.file("demo_model", "Qobs.txt", package = "HYPEtools"))
te1 <- HypeSingleVar(x = array(data = unlist(te1[, -1]) + 
                                      runif(n = nrow(te1), min = -.5, max = .5), 
                               dim = c(nrow(te1), ncol(te1) - 1, 1), 
                               dimnames = list(rownames(te1), colnames(te1)[-1])), 
                     datetime = te1$DATE, subid = obsid(te1), hype.var = "cout")
te2 <- ReadObs(filename = system.file("demo_model", "Qobs.txt", package = "HYPEtools"))
te2 <- HypeSingleVar(x = array(data = unlist(te2[, -1]), 
                               dim = c(nrow(te2), ncol(te2) - 1, 1), 
                               dimnames = list(rownames(te2), colnames(te2)[-1])), 
                     datetime = te2$DATE, subid = obsid(te2), hype.var = "rout")
# Nash-Sutcliffe Efficiency
NSE(sim = te1, obs = te2, progbar = FALSE)

Description

OptimisedClasses checks which classes (land use or soil) of parameters in an imported optpar list are actually optimized, i.e. have a min/max range larger than zero.

Usage

OptimisedClasses(x)

Arguments

Details

OptimisedClasses allows to quickly check which classes of parameters in an optpar.txt file are actually optimized during a HYPE optimization run. The function compares min and max values in the pars element of an imported HYPE optpar.txt file to identify those.

Value

OptimisedClasses returns a named list with one vector element for each parameter found in x. List element names are HYPE parameter names. Each vector contains the optimized class numbers for the respective parameter.

Examples

te <- ReadOptpar(filename = system.file("demo_model", "optpar.txt", package = "HYPEtools"))
OptimisedClasses(te)

Description

Function to find the identifier(s) used to signify model domain outlets, i.e. the "downstream" ID of outlet catchments, in a GeoData file. This is typically just one number, often e.g. '0' or '-9999', but can be one or several IDs if the GeoData file originates from a HYPE sub-model set-up, e.g. created with the 'SelectAro' program. Use OutletSubids to find the actual SUBID values of the outlet catchments.

Usage

OutletIds(gd)

Arguments

Details

OutletIds finds the unique outlet IDs of a GeoData file. The outlet ID of a typical model is a single placeholder number, often e.g. '0' or '-9999', but there can be several outlet IDs, e.g. one or several SUBIDs if the GeoData file originates from a HYPE sub-model set-up, created with the 'SelectAro' tool.

Value

OutletIds returns a vector of outlet IDs.

See Also

AllDownstreamSubids, OutletSubids

Examples

te <- ReadGeoData(filename = system.file("demo_model", "GeoData.txt", package = "HYPEtools"))
OutletIds(gd = te)

Description

Find observation stations close to specified outlet subbasins of a HYPE model set-up. Proximity threshold as upstream area fraction of target outlet subbasin(s). Currently, only upstream observations are identified.

Usage

OutletNearObs(
  gd,
  file.qobs = NULL,
  file.xobs = NULL,
  variable = NULL,
  outlets = NULL,
  frac.drain = 0.8,
  nearest.only = TRUE,
  verbose = TRUE
)

Arguments

Details

OutletNearObs finds observation sites for observation variables in HYPE 'Qobs.txt' and HYPE 'Xobs.txt' files located upstream an outlet sub-basin. For file.xobs files, which can hold several observation variables, a single variable has to be selected (the function conveniently prints available variables in file.xobs, if no variable is provided). Any number of SUBIDs present in gd can be defined as outlet subbasins with argument outlets. The function handles nested outlets, i.e. cases where user-provided subbasins in outlets are upstream basins of one another. Outlet proximity is defined by drainage area size compared to the respective outlet. The function returns either the nearest or all sites matching or exceeding fraction frac.drain, depending on argument nearest.only.

Value

OutletNearObs returns a data frame with 4 columns, containing row-wise all observation sites which match the search criteria:

subid.outlet

SUBID of outlet subbasin

subid.obs

SUBID of observation site

area.fraction

Relative drainage area fraction of observation site, compared to corresponding outlet subbasin

area.outlet

Drainage area of outlet subbasin, in km^2

area.obs

Drainage area of observation site, in km^2

If file.xobs is provided without variable, the function prints available HYPE observation variables in file.xobs and silently returns the same information as character vector.

Examples

# Import source data
te <- ReadGeoData(filename = system.file("demo_model", "GeoData.txt", package = "HYPEtools"))
# Find observation near domain outlet
OutletNearObs(file.qobs = system.file("demo_model", "Qobs.txt", package = "HYPEtools"), gd = te,
verbose = FALSE)
# get vector of variables in an Xobs file
OutletNearObs(file.xobs = system.file("demo_model", "Xobs.txt", package = "HYPEtools"), gd = te,
verbose = FALSE)

Description

Function to find all outlet SUBIDs of a HYPE model domain.

Usage

OutletSubids(gd)

Arguments

Details

OutletSubids finds all outlet SUBIDs of a model domain as provided in a 'GeoData.txt' file, i.e. all SUBIDs from which stream water leaves the model domain.

Value

OutletSubids returns a vector of outlet SUBIDs.

See Also

AllDownstreamSubids, OutletIds

Examples

te <- ReadGeoData(filename = system.file("demo_model", "GeoData.txt", package = "HYPEtools"))
OutletSubids(gd = te)

Description

Creates a Party Parrot.

Usage

PartyParrot(sound = 8)

Arguments

Details

PartyParrot generates a Party Parrot. Uses for Party Parrots include, for example, celebrating the successful execution of a script.

Value

Returns a Party Parrot to the Console.

Examples

PartyParrot()

Description

Percent bias (PBIAS) calculation for imported HYPE outputs with single variables for several catchments, i.e. time and map files, optionally multiple model runs combined.

Usage

## S3 method for class 'HypeSingleVar'
pbias(sim, obs, na.rm = TRUE, progbar = TRUE, ...)

Arguments

Value

pbias.HypeSingleVar returns a 2-dimensional array of NSE performances for all SUBIDs and model iterations provided in argument sim, with values in the same order as the second and third dimension in sim, i.e. [subid, iteration].

Examples

# Create dummy data, discharge observations with added white noise as model simulations
te1 <- ReadObs(filename = system.file("demo_model", "Qobs.txt", package = "HYPEtools"))
te1 <- HypeSingleVar(x = array(data = unlist(te1[, -1]) + 
                               runif(n = nrow(te1), min = -.5, max = .5), 
                               dim = c(nrow(te1), ncol(te1) - 1, 1), 
                               dimnames = list(rownames(te1), colnames(te1)[-1])), 
                     datetime = te1$DATE, subid = obsid(te1), hype.var = "cout")
te2 <- ReadObs(filename = system.file("demo_model", "Qobs.txt", package = "HYPEtools"))
te2 <- HypeSingleVar(x = array(data = unlist(te2[, -1]), 
                               dim = c(nrow(te2), ncol(te2) - 1, 1), 
                               dimnames = list(rownames(te2), colnames(te2)[-1])), 
                     datetime = te2$DATE, subid = obsid(te2), hype.var = "rout")
# Percentage bias
pbias(sim = te1, obs = te2, progbar = FALSE)

Description

Convenience wrapper function for a combined line plot with polygon variation ranges.

Usage

PlotAnnualRegime(
  x,
  line = c("mean", "median"),
  band = c("none", "p05p95", "p25p75", "minmax"),
  add.legend = FALSE,
  l.legend = NULL,
  l.position = c("topright", "bottomright", "right", "topleft", "left", "bottomleft"),
  log = FALSE,
  ylim = NULL,
  ylab = expression(paste("Q (m"^3, " s"^{
     -1
 }, ")")),
  xlab = paste(format(attr(x, "period"), format = "%Y"), collapse = " to "),
  col = "blue",
  alpha = 30,
  lty = 1,
  lwd = 1,
  mar = c(3, 3, 1, 1) + 0.1,
  verbose = TRUE
)

Arguments

Details

PlotAnnualRegime plots contents from lists as returned by AnnualRegime (for format details, see there). If NA values are present in the plot data, the function will throw a warning if verbose = TRUE and proceed with plotting all available data.

Argument band allows to plot variation bands to be plotted in addition to average lines. These can be (combinations of) ranges between minima and maxima, 5th and 95th percentiles, and 25th and 75th percentiles, i.e. all moments available in AnnualRegime results.

Grid lines plotted in the background are mid-month lines.

Value

PlotAnnualRegime returns a plot to the currently active plot device.

See Also

AnnualRegime, PlotSimObsRegime

Examples

## Not run: 
# Source data, HYPE basin output with a number of result variables
te1 <- ReadBasinOutput(filename = system.file("demo_model",
                                              "results", "0003587.txt",
                                              package = "HYPEtools"))
# Daily discharge regime, computed and observed,
# hydrological year from October, aggregated to weekly means
te2 <- AnnualRegime(te1[, c("DATE", "COUT", "ROUT")],
                    ts.in = "day",
                    ts.out = "week", start.mon = 10)
                    
# Screen devices should not be used in examples
PlotAnnualRegime(x = te2)
PlotAnnualRegime(x = te2, line = "median", band = "p05p95",
  add.legend = TRUE, col = c("red", "blue"))

## End(Not run)

Description

Plot a standard suite of time series plots from a basin output file, typically used for model performance inspection and/or during manual calibration

Usage

PlotBasinOutput(
  x,
  filename,
  driver = c("default", "pdf", "png", "screen"),
  timestep = attr(x, "timestep"),
  hype.vars = "all",
  vol.err = TRUE,
  log.q = FALSE,
  start.mon = 1,
  from = 1,
  to = nrow(x),
  date.format = "",
  name = "",
  area = NULL,
  subid = attr(x, "subid"),
  gd = NULL,
  bd = NULL,
  ylab.t1 = "Conc."
)

Arguments

Details

PlotBasinOutput plots a suite of time series along with a flow duration curve, a flow regime plot, and a selection of goodness-of-fit measures from an imported HYPE basin output file. The function selects from a range of "known" variables, and plots those which are available in the user-supplied basin output. It is mostly meant as a support tool during calibration, manual or automatic, providing a quick and comprehensive overview of model dynamics in a subbasin of interest.

HYPE outputs which are known to PlotBasinOutput include:

• precipitation

• air temperature

• discharge

• lake water level

• water temperature

• evapotranspiration

• snow water equivalent

• sub-surface storage components

• nitrogen concentrations

• phosphorus concentrations

• suspended sediment concentrations

• total sediment concentrations

• tracer concentration

Below a complete list of HYPE variables known to the function in HYPE info.txt format, ready to copy-paste into an info.txt file. For a detailed description of the variables, see the HYPE online documentation.

basinoutput variable upcprf upcpsf temp upepot upevap cout rout soim sm13 upsmfp snow upcprc cct2 ret2 ccin rein ccon reon cctn retn ccsp resp ccpp repp cctp retp wcom wstr ccss ress ccts rets cct1 ret1

Device dimensions are hard-coded to a width of 15 inches and height depending on the number of plotted time series. When plotting to a screen device, a maximum height of 10 inches is enforced in order to prevent automatic resizing with slow redrawing. PlotBasinOutput throws a warning if the plot height exceeds 10 inches, which can lead to overlapping plot elements. On screens with less than 10 inch screen, redrawing is inhibited, which can lead to an empty plot. The recommended solution for both effects is to plot to pdf or png file devices instead.

Value

Returns a multi-panel plot in a new graphics device.

See Also

PlotBasinSummary, PlotAnnualRegime, PlotDurationCurve, ReadBasinOutput

Examples

# Source data, HYPE basin output with a number of result variables
te1 <- ReadBasinOutput(filename = system.file("demo_model",
"results","0003587.txt", package = "HYPEtools"))
te2 <- ReadGeoData(filename = system.file("demo_model",
"GeoData.txt", package = "HYPEtools"))

## Not run:  
# Plot selected water variables on screen device
PlotBasinOutput(x = te1, gd = te2, driver = "screen",hype.vars = c("cout", "rout", 
"snow", "upcprf", "upcpsf"))

## End(Not run)

Description

Plot a standard suite of plots summarizing properties of a sub-basin including upstream area and model performance for discharge and concentrations of nutrients, sediment, and tracers.

Usage

PlotBasinSummary(
  x,
  filename,
  driver = c("default", "pdf", "png", "screen"),
  panels = 1,
  gd = NULL,
  bd = NULL,
  gcl = NULL,
  psd = NULL,
  subid = NULL,
  desc = NULL,
  timestep = attr(x, "timestep"),
  hype.vars = "all",
  from = 1,
  to = nrow(x),
  log = FALSE,
  xscale = "gauss",
  start.mon = 10,
  name = "",
  ylab.t1 = "Conc."
)

Arguments

Details

PlotBasinSummary plots a multi-panel plot with a number of plots to evaluate model properties and performances for a chosen sub-basin. Performance plots include discharge, HYPE-modeled nutrient species for nitrogen (total, inorganic, organic) and phosphorus (total, particulate, soluble), and HYPE modeled suspended and total sediment concentrations.

Plotted panels show:

• Summarized catchment characteristics as bar charts: Upstream-averaged land use, soil, and crop group fractions; modeled nutrient loads in sub-basin outlet, and summed upstream gross loads from point sources and rural households (if necessary variables available, omitted otherwise).

• Goodness-of-fit measures for discharge and concentrations: KGE (Kling-Gupta Efficiency), NSE (Nash-Sutcliffe Efficiency), PBIAS (Percentage Bias, aka relative error), MAE (Mean Absolute Error), r (Pearson product-moment correlation coefficient), VE (Volumetric Efficiency).

• Simulation-observation relationships for discharge and concentrations: Simulated and observed concentration-discharge relationships, relationship between observed and simulated nutrient, sediment, and tracer concentrations.

• Duration curves for flow and concentrations: Pairwise simulated and observed curves.

• Annual regimes for flow and concentrations: Pairwise simulated and observed regime plots at monthly aggregation, with number of observations for concentration regimes.

• Corresponding plots for IN/TN and SP/TP ratios.

Per default, the function plots from available model variables in an imported HYPE basin output file, and missing variables will be automatically omitted. Variable selection can be additionally fine-tuned using argument hype.vars.

Argument panels allows to choose if bar chart panels should be plotted. This can be time-consuming for sites with many upstream sub-basins and might not necessary e.g. during calibration. If 1 (default), all panels are plotted. If set to 2, bar charts will be excluded. If 3, only bar charts will be plotted. Arguments gd, bd, gcl, psd, subid, and desc are only needed for bar chart plotting.

Below a complete list of HYPE variables known to the function in HYPE info.txt format, ready to copy-paste into an info.txt file. For a detailed description of the variables, see the HYPE online documentation.

basinoutput variable cout rout ccin rein ccon reon cctn retn ccsp resp ccpp repp cctp retp ctnl ctpl ccss ress ccts rets cct1 ret1

#' Device dimensions are hard-coded to a width of 13 inches and height depending on the number of plotted time series. When plotting to a screen device, a maximum height of 10 inches is enforced in order to prevent automatic resizing with slow redrawing. PlotBasinOutput throws a warning if the plot height exceeds 10 inches, which can lead to overlapping plot elements. On screens with less than 10 inch screen height, redrawing is inhibited, which can lead to an empty plot. The recommended solution for both effects is to plot to pdf or png file devices instead.

Value

Returns a multi-panel plot in a new graphics device.

See Also

PlotBasinOutput, BarplotUpstreamClasses, PlotSimObsRegime, PlotAnnualRegime, PlotDurationCurve, ReadBasinOutput

Examples

# Source data, HYPE basin output with a number of result variables
te1 <- ReadBasinOutput(filename = system.file("demo_model", "results", "0003587.txt", 
                       package = "HYPEtools"))
te2 <- ReadGeoData(filename = system.file("demo_model", "GeoData.txt", package = "HYPEtools"))

## Not run: 
# Plot basin summary for discharge on screen device
PlotBasinSummary(x = te1, gd = te2, driver = "screen", panels = 2)

## End(Not run)

Description

Convenience wrapper function for a (multiple) line plot, with pretty defaults for axis annotation and a Gaussian scaling option for the x-axis.

Usage

PlotDurationCurve(
  freq,
  xscale = "lin",
  yscale = "log",
  add.legend = FALSE,
  l.legend = NULL,
  ylim = NULL,
  xlab = "Flow exceedance percentile",
  ylab = "m3s",
  col = "blue",
  lty = 1,
  lwd = 1,
  mar = c(3, 3, 1, 1) + 0.1
)

Arguments

Details

PlotDurationCurve plots a duration curve with pretty formatting defaults. The function sets par parameters tcl and mgp internally and will override previously set values for the returned plot. It typically uses results from ExtractFreq as input data and via that function it can be used to visualize and compare time series properties.

Value

PlotDurationCurve returns a plot to the currently active plot device.

See Also

ExtractFreq

Examples

# Import source data
te1 <- ReadBasinOutput(filename = system.file("demo_model", "results", "0003587.txt", 
                       package = "HYPEtools"))
te2 <- ExtractFreq(te1[, c("COUT", "ROUT")])
# Plot flow duration curves for simulated and observed discharge
PlotDurationCurve(freq = te2, add.legend = TRUE, col = c("red", "blue"))

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