OutletNearObs {HYPEtools}

Find outlet-near observations in HYPE observation data files.

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

gd

Data frame with two columns subid and maindown (not case-sensitive). Typically a 'GeoData.txt' file imported using ReadGeoData.

file.qobs, file.xobs

Character string, file location of HYPE observation data file. Only one of these needs to be supplied, with file.qobs taking precedence if both are provided. Either an Xobs.txt or a Qobs.txt file.

variable

Character string, HYPE variable to use. Needed only with argument file.xobs. If NULL (default), a vector of available variables in file.xobs is returned.

outlets

Integer vector, HYPE SUBIDs of subbasins to be considered outlets. If NULL (default), all outlet subbasins in gd are used.

frac.drain

Numeric, minimum fraction of drainage area at corresponding outlet to be covered by observation site.

nearest.only

Logical, if TRUE (default), only the nearest observation site SUBID is returned. If FALSE, all observation site SUBIDs available within frac.drain are returned.

verbose

Logical, print status messages and progress bars during runtime.

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)