Package 'RPhosFate' reference manual

Title:	Soil and Chemical Substance Emission and Transport Model
Description:	An enhanced version of the semi-empirical, spatially distributed emission and transport model PhosFate implemented in 'R' and 'C++'. It currently supports suspended solids (SS) and particulate phosphorus (PP). A major feature is the allocation of substance loads entering surface waters to their sources of origin, which is a basic requirement for the identification of critical source areas and in consequence a cost-effective implementation of mitigation measures. References: Hepp et al. (2022) <doi:10.1016/j.jenvman.2022.114514>; Hepp and Zessner (2019) <doi:10.3390/w11102161>; Kovacs (2013) <http://hdl.handle.net/20.500.12708/9468>.
Authors:	Gerold Hepp [aut, cre]
Maintainer:	Gerold Hepp <[email protected]>
License:	AGPL (>= 3)
Version:	1.0.4
Built:	2024-10-31 06:50:29 UTC
Source:	CRAN

One dimensional automatic model calibration

Description

Automatically calibrates the model with the help of a combination of golden section search and successive parabolic interpolation.

Usage

## S4 method for signature 'RPhosFate'
autoCalibrate(
  x,
  substance,
  col,
  interval,
  metric,
  tol = min(interval) * 0.1,
  parameter = NULL
)
## S4 method for signature 'RPhosFate'
autoCalibrate(
  x,
  substance,
  col,
  interval,
  metric,
  tol = min(interval) * 0.1,
  parameter = NULL
)

Arguments

`x`	An S4 `RPhosFate` river catchment object.
`substance`	A character string specifying the substance to calculate.
`col`	A character string specifying the calibration data column with the respective substance river loads.
`interval`	A numeric vector specifying the end-points of the interval to be searched.
`metric`	A character string specifying the metric to optimise. See `calibrationQuality` for available metrics.
`tol`	A numeric scalar specifying the desired accuracy of the parameter used for optimisation (not the metric).
`parameter`	By default, SS are calibrated utilising the overland deposition rate and all other substances are calibrated utilising their respective enrichment ratio. This argument can be used to specify a dedicated parameter utilised for calibration via a character string: `"ns_dep_ovl"` for overland or `"ns_dep_cha"` for channel deposition rate.

Value

An S4 RPhosFate river catchment object and side effects in the form of raster files.

Examples


# temporary demonstration project copy
cv_dir <- demoProject()
# load temporary demonstration project
x <- RPhosFate(
  cv_dir = cv_dir,
  ls_ini = TRUE
)
# presupposed method calls
x <- firstRun(x, "SS")
x <- snapGauges(x)

x <- autoCalibrate(
  x,
  "SS",
  col = "SS_load",
  interval = c(10e-4, 20e-4),
  metric = "NSE"
)

# temporary demonstration project copy
cv_dir <- demoProject()
# load temporary demonstration project
x <- RPhosFate(
  cv_dir = cv_dir,
  ls_ini = TRUE
)
# presupposed method calls
x <- firstRun(x, "SS")
x <- snapGauges(x)

x <- autoCalibrate(
  x,
  "SS",
  col = "SS_load",
  interval = c(10e-4, 20e-4),
  metric = "NSE"
)

Two dimensional automatic model calibration

Description

Automatically calibrates the model with the help of a general-purpose optimisation function. In contrast to autoCalibrate, this method always utilises the overland and channel deposition rate at the same time and never the respective enrichment ratio for calibration. Beware of local optima and parameters approximately within the convergence tolerance of interval end-points.

Usage

## S4 method for signature 'RPhosFate'
autoCalibrate2(
  x,
  substance,
  col,
  metric,
  method = "Nelder-Mead",
  lower = 0,
  upper = 0.1,
  control = list(fnscale = if (metric %in% c("NSE", "mNSE", "KGE")) -1 else 1)
)
## S4 method for signature 'RPhosFate'
autoCalibrate2(
  x,
  substance,
  col,
  metric,
  method = "Nelder-Mead",
  lower = 0,
  upper = 0.1,
  control = list(fnscale = if (metric %in% c("NSE", "mNSE", "KGE")) -1 else 1)
)

Arguments

`x`	An S4 `RPhosFate` river catchment object.
`substance`	A character string specifying the substance to calculate.
`col`	A character string specifying the calibration data column with the respective substance river loads.
`metric`	A character string specifying the metric to optimise. See `calibrationQuality` for available metrics.
`method`	A character string specifying the utilised optimisation method. See `optim` for further information (use `autoCalibrate` instead of method `"Brent"`).
`lower`	A numeric scalar or vector specifying the lower end-point(s) of the interval(s) to be searched.
`upper`	A numeric scalar or vector specifying the upper end-point(s) of the interval(s) to be searched.
`control`	A `list` of control parameters passed on to `optim`. See `optim` for further information.

Value

An S4 RPhosFate river catchment object and side effects in the form of raster files.

Examples


# temporary demonstration project copy
cv_dir <- demoProject()
# load temporary demonstration project
x <- RPhosFate(
  cv_dir = cv_dir,
  ls_ini = TRUE
)
# presupposed method calls
x <- firstRun(x, "SS")
x <- snapGauges(x)

x <- autoCalibrate2(
  x,
  "SS",
  col = "SS_load",
  metric = "NSE",
  method = "L-BFGS-B",
  lower = c(10e-4, 0),
  upper = c(20e-4, 20e-4),
  control = list(fnscale = -1, parscale = c(1e-3, 1e-3), factr = 1e12)
)

# temporary demonstration project copy
cv_dir <- demoProject()
# load temporary demonstration project
x <- RPhosFate(
  cv_dir = cv_dir,
  ls_ini = TRUE
)
# presupposed method calls
x <- firstRun(x, "SS")
x <- snapGauges(x)

x <- autoCalibrate2(
  x,
  "SS",
  col = "SS_load",
  metric = "NSE",
  method = "L-BFGS-B",
  lower = c(10e-4, 0),
  upper = c(20e-4, 20e-4),
  control = list(fnscale = -1, parscale = c(1e-3, 1e-3), factr = 1e12)
)

Calibration quality

Description

Assesses the model's calibration quality with the help of the pairwise complete modelled as well as observed loads and the following metrics:

NSE: Nash-Sutcliffe Efficiency
mNSE: Modified Nash-Sutcliffe Efficiency (j = 1)
KGE: Modified Kling-Gupta Efficiency
RMSE: Root Mean Square Error
PBIAS: Percent Bias
RSR: Ratio of the RMSE to the standard deviation of the observations
RCV: Ratio of the coefficients of variation
GMRAE: Geometric Mean Relative Absolute Error
MdRAE: Median Relative Absolute Error

In addition, a scatter plot with the observed river loads on the x- and the modelled river loads on the y-axis is displayed and provides a visual impression of the model performance. Other elements of this plot are an identity line (solid) and plus/minus 30% deviation lines (dashed).

Usage

## S4 method for signature 'RPhosFate'
calibrationQuality(x, substance, col)
## S4 method for signature 'RPhosFate'
calibrationQuality(x, substance, col)

Arguments

`x`	An S4 `RPhosFate` river catchment object.
`substance`	A character string specifying the substance to calculate.
`col`	A character string specifying the calibration data column with the respective substance river loads.

Value

A named numeric vector containing the assessed metrics along with the in-channel retention ratio (one minus sum of xxt at catchment outlet(s) divided by sum of xxt_inp).

References

Nash, J.E., Sutcliffe, J.V., 1970. River flow forecasting through conceptual models part I – a discussion of principles. Journal of Hydrology 10, 282–290. https://doi.org/10.1016/0022-1694(70)90255-6

Legates, D.R., McCabe Jr., G.J., 1999. Evaluating the use of “goodness-of-fit” measures in hydrologic and hydroclimatic model validation. Water Resources Research 35, 233–241. https://doi.org/10.1029/1998WR900018

Kling, H., Fuchs, M., Paulin, M., 2012. Runoff conditions in the upper Danube basin under an ensemble of climate change scenarios. Journal of Hydrology 424–425, 264–277. https://doi.org/10.1016/j.jhydrol.2012.01.011

Moriasi, D.N., Arnold, J.G., Van Liew, M.W., Bingner, R.L., Harmel, R.D., Veith, T.L., 2007. Model evaluation guidelines for systematic quantification of accuracy in watershed simulations. Transactions of the ASABE 50, 885–900.

Examples


# temporary demonstration project copy
cv_dir <- demoProject()
# load temporary demonstration project
x <- RPhosFate(
  cv_dir = cv_dir,
  ls_ini = TRUE
)
# presupposed method calls
x <- firstRun(x, "SS")
x <- snapGauges(x)

calibrationQuality(x, "SS", "SS_load")

# temporary demonstration project copy
cv_dir <- demoProject()
# load temporary demonstration project
x <- RPhosFate(
  cv_dir = cv_dir,
  ls_ini = TRUE
)
# presupposed method calls
x <- firstRun(x, "SS")
x <- snapGauges(x)

calibrationQuality(x, "SS", "SS_load")

Demonstration project

Description

Copies a demonstration project to an existing or a temporary directory.

The demonstration project data are a derivative of the

Geoland.at (digital elevation model),
AMA (field data),
BMLRT (channel data) and
GIP.at (road data)

data sets, used and licensed under (CC BY 4.0) by Gerold Hepp.

While the data represent a real catchment (HOAL), some of them are fictitious, but plausible. These are, among others, R- and C-factors, soil and related data, existence of subsurface drainage at road embankments as well as substance river loads.

Usage

demoProject(cs_dir = tempdir(TRUE))
demoProject(cs_dir = tempdir(TRUE))

Arguments

cs_dir

An optional character string specifying an existing directory.

Value

A character string containing the demonstration project root directory.

Examples


demoProject()

demoProject()

DEM related input

Description

Clips, pre-processes and calculates or determines all input data related to the digital elevation model (DEM) in the broader sense: acc, acc_wtd, cha, dem, dir, rds, slp, and wsh.

Requires TauDEM 5.3.7 and the WhiteboxTools binary (whitebox::install_whitebox) to be installed on your computer.

Usage

DEMrelatedInput(
  cv_dir,
  cs_dem,
  cs_cha,
  sp_msk,
  sp_olp,
  sp_sds,
  cs_rds = NULL,
  cs_wgs = NULL,
  cs_dir = NULL,
  ns_brn = 50,
  is_adj = 1L,
  is_ths = 1L,
  ls_tmp = FALSE,
  cs_fex = c("tif", "img")
)
DEMrelatedInput(
  cv_dir,
  cs_dem,
  cs_cha,
  sp_msk,
  sp_olp,
  sp_sds,
  cs_rds = NULL,
  cs_wgs = NULL,
  cs_dir = NULL,
  ns_brn = 50,
  is_adj = 1L,
  is_ths = 1L,
  ls_tmp = FALSE,
  cs_fex = c("tif", "img")
)

Arguments

`cv_dir`	A character vector specifying the desired project root directory (first position).
`cs_dem`	A character string specifying a path to a potentially large raster digital elevation model.
`cs_cha`	A character string specifying a path to a potentially large raster providing channels.
`sp_msk`	An `sp::SpatialPolygonsDataFrame` providing a somewhat oversized catchment mask used to clip the potentially large input rasters for further processing.
`sp_olp`	An `sp::SpatialPointsDataFrame` providing the desired catchment outlet(s).
`sp_sds`	An `sp::SpatialPointsDataFrame` providing channel sources.
`cs_rds`	An optional character string specifying a path to a potentially large raster providing roads.
`cs_wgs`	An optional character string specifying a path to a potentially large raster providing flow accumulation weights.
`cs_dir`	An optional character string specifying a path to a potentially large raster providing D8 flow directions using ArcGIS codes.
`ns_brn`	A numeric scalar specifying the stream burning step size in m.
`is_adj`	A numeric scalar specifying how many cells adjacent to channels shall be burnt.
`is_ths`	An integer scalar specifying the number of threads to use during computation (no effect in case OpenMP is not supported by the toolchain and/or platform).
`ls_tmp`	A logical scalar specifying if the temporary files created during computation shall be kept.
`cs_fex`	A character string specifying the file extension of the created raster files (either the default `"tif"` or `"img"` for backward compatibility).

Details

This function applies the following (pre-processing) steps to ensure hydrologic consistency of the generated input data:

Stream burning and orientation of cells adjacent to channel cells approximately into the direction of channel cells (no effect with ns_brn = 0).
Depression breaching.
Tracing of downslope flowpaths from the provided channel sources.

When roads are provided, they are considered as flow obstacles breaking the continuity of the calculated flow accumulations.

In case no flow accumulation weights are provided, acc and acc_wtd are identical.

Providing existing flow directions prevents calculating them, which, for example, may be useful in case the effect of tillage directions has been enforced on topographic flow directions in advance. Please note that doing so renders stream burning and depression breaching without effect.

dem represents the breached DEM with reversed stream burning if applicable. This processed DEM also serves as the basis for the calculation of the D8 slopes provided by slp.

Value

A two column numeric matrix specifying one or more catchment outlet coordinates and side effects in the form of raster files.

References

Lindsay, J.B., 2016. Efficient hybrid breaching-filling sink removal methods for flow path enforcement in digital elevation models. Hydrological Processes 30, 846–857.

Examples

## Not run: 
# obtain temporary project root directory
cv_dir <- normalizePath(
  tempfile("cmt"),
  winslash = .Platform$file.sep,
  mustWork = FALSE
)
# obtain directory holding "large" rasters and other required data sets
cs_dir_lrg <- system.file("tinytest", "largeData", package = "RPhosFate")

nm_olc <- DEMrelatedInput(
  cv_dir = cv_dir,
  cs_dem = file.path(cs_dir_lrg, "dem_lrg.tif"),
  cs_cha = file.path(cs_dir_lrg, "cha_lrg.tif"),
  sp_msk = raster::shapefile(file.path(cs_dir_lrg, "msk.shp")),
  sp_olp = raster::shapefile(file.path(cs_dir_lrg, "olp.shp")),
  sp_sds = raster::shapefile(file.path(cs_dir_lrg, "sds.shp")),
  cs_rds = file.path(cs_dir_lrg, "rds_lrg.tif"),
  cs_wgs = file.path(cs_dir_lrg, "wgs_lrg.tif"),
  ls_tmp = TRUE
)
## End(Not run)

## Not run: 
# obtain temporary project root directory
cv_dir <- normalizePath(
  tempfile("cmt"),
  winslash = .Platform$file.sep,
  mustWork = FALSE
)
# obtain directory holding "large" rasters and other required data sets
cs_dir_lrg <- system.file("tinytest", "largeData", package = "RPhosFate")

nm_olc <- DEMrelatedInput(
  cv_dir = cv_dir,
  cs_dem = file.path(cs_dir_lrg, "dem_lrg.tif"),
  cs_cha = file.path(cs_dir_lrg, "cha_lrg.tif"),
  sp_msk = raster::shapefile(file.path(cs_dir_lrg, "msk.shp")),
  sp_olp = raster::shapefile(file.path(cs_dir_lrg, "olp.shp")),
  sp_sds = raster::shapefile(file.path(cs_dir_lrg, "sds.shp")),
  cs_rds = file.path(cs_dir_lrg, "rds_lrg.tif"),
  cs_wgs = file.path(cs_dir_lrg, "wgs_lrg.tif"),
  ls_tmp = TRUE
)
## End(Not run)

Emission

Description

Calculates and writes substance emissions to disk.

Usage

## S4 method for signature 'RPhosFate'
emission(x, substance = "PP")
## S4 method for signature 'RPhosFate'
emission(x, substance = "PP")

Arguments

`x`	An S4 `RPhosFate` river catchment object.
`substance`	A character string specifying the substance to calculate.

Value

An S4 RPhosFate river catchment object and side effects in the form of raster files.

Examples


# temporary demonstration project copy
cv_dir <- demoProject()
# load temporary demonstration project
x <- RPhosFate(
  cv_dir = cv_dir,
  ls_ini = TRUE
)
# presupposed method calls
x <- erosionPrerequisites(x)
x <- erosion(x)

x <- emission(x, "PP")

# temporary demonstration project copy
cv_dir <- demoProject()
# load temporary demonstration project
x <- RPhosFate(
  cv_dir = cv_dir,
  ls_ini = TRUE
)
# presupposed method calls
x <- erosionPrerequisites(x)
x <- erosion(x)

x <- emission(x, "PP")

Erosion

Description

Calculates and writes (R)USLE erosion to disk.

Usage

## S4 method for signature 'RPhosFate'
erosion(x)
## S4 method for signature 'RPhosFate'
erosion(x)

Arguments

`x`	An S4 `RPhosFate` river catchment object.

Value

An S4 RPhosFate river catchment object and side effects in the form of raster files.

References

Renard, K.G., Foster, G.R., Weesies, G.A., McCool, D.K., Yoder, D.C., 1997. Predicting soil erosion by water: a guide to conservation planning with the Revised Universal Soil Loss Equation (RUSLE), Agriculture Handbook. U.S. Government Printing Office, Washington, DC.

Wischmeier, W.H., Smith, D.D., 1978. Predicting rainfall erosion losses. A guide to conservation planning, Agriculture Handbook. U.S. Government Printing Office, Washington, DC.

Examples


# temporary demonstration project copy
cv_dir <- demoProject()
# load temporary demonstration project
x <- RPhosFate(
  cv_dir = cv_dir,
  ls_ini = TRUE
)
# presupposed method call
x <- erosionPrerequisites(x)

x <- erosion(x)

# temporary demonstration project copy
cv_dir <- demoProject()
# load temporary demonstration project
x <- RPhosFate(
  cv_dir = cv_dir,
  ls_ini = TRUE
)
# presupposed method call
x <- erosionPrerequisites(x)

x <- erosion(x)

Erosion prerequisites

Description

Calculates and writes capped slopes, L- and RUSLE S-factors (equations for summer conditions and slopes $\geq$ 15 ft) to disk. Weighted flow accumulations less than one are set to one for the calculation of the L-factors.

Usage

## S4 method for signature 'RPhosFate'
erosionPrerequisites(x)
## S4 method for signature 'RPhosFate'
erosionPrerequisites(x)

Arguments

`x`	An S4 `RPhosFate` river catchment object.

Value

An S4 RPhosFate river catchment object and side effects in the form of raster files.

References

Examples


# temporary demonstration project copy
cv_dir <- demoProject()
# load temporary demonstration project
x <- RPhosFate(
  cv_dir = cv_dir,
  ls_ini = TRUE
)

x <- erosionPrerequisites(x)

# temporary demonstration project copy
cv_dir <- demoProject()
# load temporary demonstration project
x <- RPhosFate(
  cv_dir = cv_dir,
  ls_ini = TRUE
)

x <- erosionPrerequisites(x)

First run

Description

Calls erosionPrerequisites, erosion, emission, transportPrerequisites, transportCalcOrder and transport in the mentioned order. While transport is called for the specified substance only, emission is called for all substances whose top soil concentrations have been provided.

Usage

## S4 method for signature 'RPhosFate'
firstRun(x, substance = "PP")
## S4 method for signature 'RPhosFate'
firstRun(x, substance = "PP")

Arguments

`x`	An S4 `RPhosFate` river catchment object.
`substance`	A character string specifying the substance to calculate.

Value

An S4 RPhosFate river catchment object and side effects in the form of raster files.

Examples


# temporary demonstration project copy
cv_dir <- demoProject()
# load temporary demonstration project
x <- RPhosFate(
  cv_dir = cv_dir,
  ls_ini = TRUE
)

x <- firstRun(x, "SS")

# temporary demonstration project copy
cv_dir <- demoProject()
# load temporary demonstration project
x <- RPhosFate(
  cv_dir = cv_dir,
  ls_ini = TRUE
)

x <- firstRun(x, "SS")

Get layer

Description

Obtains a project raster layer for further analysis.

Usage

## S4 method for signature 'RPhosFate'
getLayer(x, i, j = NULL)

## S4 method for signature 'RPhosFate,ANY,ANY,ANY'
x[i, j]
## S4 method for signature 'RPhosFate'
getLayer(x, i, j = NULL)

## S4 method for signature 'RPhosFate,ANY,ANY,ANY'
x[i, j]

Arguments

`x`	An S4 `RPhosFate` river catchment object.
`i`	A character string specifying a layer name. Substance related layers whose names start with xx are treated differently. They have to be queried by their name (not filename), for example, `"xxc"` in combination with `"PP"` in argument `j` queries the particulate phosphorus concentrations in top soils. See subdirectory sections for further information.
`j`	A character string specifying a substance if applicable.

Value

A raster::RasterLayer object.

Input subdirectory

This directory holds all possible user input raster data (flow obstacles like roads must be considered during generation of the flow accumulation layers and also be cut out from them in order to be properly respected):

acc: Flow accumulations required for transportCalcOrder.
acc_wtd: Weighted flow accumulations required for everything (can be equal to acc).
CFa: (R)USLE C-factors required for erosion.
cha: Channel cells required for everything (1: channel cell, NA: no channel cell).
clc: Clay contents of top soils in % required for substance emissions.
dem: Digital elevation model in m a.s.l. (optional).
dir: D8 flow directions required for transportPrerequisites and substance transport.
fid: Field IDs (optional).
KFa: (R)USLE K-factors required for erosion.
lue: Land use classes (optional).
man: Manning's roughness coefficients required for substance transport.
xxc: Substance contents of top soils in mg/kg required for substance emissions, for example, ppc for PP top soil contents.
rds: Road cells required for transportPrerequisites (0: road cell without subsurface drainage, 1: road cell with subsurface drainage, NA: no road cell).
RFa: (R)USLE R-factors required for erosion.
slp: Slopes in % required for everything.
wsh: Watershed (optional).

Intermediate subdirectory

This directory holds intermediate calculations:

inl: Cells representing inlets at roads (storm drains).
LFa: L-factors.
rhy: Hydraulic radii in m.
rip: Cells representing the riparian zones within channel cells.
SFa: RUSLE S-factors.
slp_cap: Capped slopes in %.

Result subdirectory

This directory holds the model results:

ero: Erosion in t/cell/yr.
xxe: Substance emissions in kg/cell/yr, for example, ppe for PP emissions.
xxr: Substance retentions in t/cell/yr (SS) or kg/cell/yr, for example, ppr for PP retentions.
xxt: Substance transports in t/cell/yr (SS) or kg/cell/yr, for example, ppt for PP transports.
xxt_cld: Substance cell loads in t/cell/yr (SS) or kg/cell/yr, for example, ppt_cld for PP cell loads.
xxt_ctf: Substance cell transfers in t/cell/yr (SS) or kg/cell/yr, for example, ppt_ctf for PP transfers.
xxt_inp: Substance inputs into surface waters in t/cell/yr (SS) or kg/cell/yr, for example, ppt_inp for PP inputs into surface waters.
xxt_out: Substance outlet loads of subsurface drainages in t/cell/yr (SS) or kg/cell/yr, for example, ppt_out for PP outlet loads.

Examples


# temporary demonstration project copy
cv_dir <- demoProject()
# load temporary demonstration project
x <- RPhosFate(
  cv_dir = cv_dir,
  ls_ini = TRUE
)
# presupposed method call
x <- firstRun(x, "SS")

getLayer(x, "dir")
getLayer(x, "xxt", "SS")
getLayer(x, "xxe", "PP")

# temporary demonstration project copy
cv_dir <- demoProject()
# load temporary demonstration project
x <- RPhosFate(
  cv_dir = cv_dir,
  ls_ini = TRUE
)
# presupposed method call
x <- firstRun(x, "SS")

getLayer(x, "dir")
getLayer(x, "xxt", "SS")
getLayer(x, "xxe", "PP")

Get parameter(s)

Description

Obtains a single model parameter or all model parameters at once.

Usage

## S4 method for signature 'RPhosFate'
getParameter(x, parameter = NULL)
## S4 method for signature 'RPhosFate'
getParameter(x, parameter = NULL)

Arguments

`x`	An S4 `RPhosFate` river catchment object.
`parameter`	A character string specifying a parameter name or `NULL` for a `list` of all parameters. See model parameter arguments section for further information.

Value

Depends on the queried parameter or a list in case of all parameters. See model parameter arguments section for further information.

Model parameter arguments

ns_slp_min: A numeric scalar specifying the minimum bounding slope in % (defaults to 0.001).
ns_slp_max: A numeric scalar specifying the maximum bounding slope in % (defaults to 999.0).
ns_rhy_a: A numeric scalar specifying a network constant depending on the discharge frequency needed for the calculation of the hydraulic radius, which in turn is a prerequisite for substance transport (defaults to 0.09 representing a discharge frequency of approximately six years).
ns_rhy_b: A numeric scalar specifying a geometry scaling exponent depending on the discharge frequency needed for the calculation of the hydraulic radius, which in turn is a prerequisite for substance transport (defaults to 0.50 representing a discharge frequency of approximately six years).
ns_cha_rto: A numeric scalar specifying the ratio of the channel to the cell width determining the widths of the riparian zones required for substance transport (defaults to 0.5).
ns_man_rip: A numeric scalar specifying Manning's roughness coefficient of the riparian zones within channel cells required for substance transport (defaults to 0.32).
ns_man_cha: A numeric scalar specifying Manning's roughness coefficient of the channel within channel cells required for substance transport (defaults to 0.04).
ns_dep_ovl: A numeric scalar specifying the overland deposition rate per second required for substance transport (calibration parameter; no default).
ns_dep_cha: A numeric scalar specifying the channel deposition rate per second required for substance transport (calibration parameter; no default).
nv_tfc_inl: A named numeric vector specifying the inlet transfer coefficients required for substance transport, for example, c(SS = 0.6, PP = 0.6) (no default).
nv_enr_rto A named numeric vector specifying the substance enrichment ratios required for substance except SS transport, for example, c(PP = 2.0) (calibration parameter; no default).
iv_fDo: An integer vector specifying the outflow direction vector required for substance transport (defaults to ArcGIS codes).
nm_olc: A two column numeric matrix specifying one or more catchment outlet coordinates required for the in-channel retention ratio of calibrationQuality (no default).
df_cdt: A data.frame with calibration data, which must have at least the following three columns and one or more columns with substance river loads in t/yr (no default):
- ID: ID(s) of the gauge(s)
- x: x-coordinate(s) of the gauge(s)
- y: y-coordinate(s) of the gauge(s)

Examples


# temporary demonstration project copy
cv_dir <- demoProject()
# load temporary demonstration project
x <- RPhosFate(
  cv_dir = cv_dir,
  ls_ini = TRUE
)

getParameter(x)
getParameter(x, "ns_dep_ovl")

# temporary demonstration project copy
cv_dir <- demoProject()
# load temporary demonstration project
x <- RPhosFate(
  cv_dir = cv_dir,
  ls_ini = TRUE
)

getParameter(x)
getParameter(x, "ns_dep_ovl")

Initialise project

Description

Initialises a project from scratch or loads the state of an existing one utilising GeoTIFF (*.tif) raster files from, by convention, the following three project root subdirectories:

Input
Intermediate
Result

See subdirectory sections for further information.

catchment is an alias for RPhosFate.

Usage

RPhosFate(...)

catchment(...)
RPhosFate(...)

catchment(...)

Arguments

...

Arguments used to initialise the project. See argument sections for further information.

Value

An S4 RPhosFate river catchment object.

Input subdirectory

acc: Flow accumulations required for transportCalcOrder.
acc_wtd: Weighted flow accumulations required for everything (can be equal to acc).
CFa: (R)USLE C-factors required for erosion.
cha: Channel cells required for everything (1: channel cell, NA: no channel cell).
clc: Clay contents of top soils in % required for substance emissions.
dem: Digital elevation model in m a.s.l. (optional).
dir: D8 flow directions required for transportPrerequisites and substance transport.
fid: Field IDs (optional).
KFa: (R)USLE K-factors required for erosion.
lue: Land use classes (optional).
man: Manning's roughness coefficients required for substance transport.
xxc: Substance contents of top soils in mg/kg required for substance emissions, for example, ppc for PP top soil contents.
rds: Road cells required for transportPrerequisites (0: road cell without subsurface drainage, 1: road cell with subsurface drainage, NA: no road cell).
RFa: (R)USLE R-factors required for erosion.
slp: Slopes in % required for everything.
wsh: Watershed (optional).

Intermediate subdirectory

This directory holds intermediate calculations:

inl: Cells representing inlets at roads (storm drains).
LFa: L-factors.
rhy: Hydraulic radii in m.
rip: Cells representing the riparian zones within channel cells.
SFa: RUSLE S-factors.
slp_cap: Capped slopes in %.

Result subdirectory

This directory holds the model results:

ero: Erosion in t/cell/yr.
xxe: Substance emissions in kg/cell/yr, for example, ppe for PP emissions.
xxr: Substance retentions in t/cell/yr (SS) or kg/cell/yr, for example, ppr for PP retentions.
xxt: Substance transports in t/cell/yr (SS) or kg/cell/yr, for example, ppt for PP transports.
xxt_cld: Substance cell loads in t/cell/yr (SS) or kg/cell/yr, for example, ppt_cld for PP cell loads.
xxt_ctf: Substance cell transfers in t/cell/yr (SS) or kg/cell/yr, for example, ppt_ctf for PP transfers.
xxt_inp: Substance inputs into surface waters in t/cell/yr (SS) or kg/cell/yr, for example, ppt_inp for PP inputs into surface waters.
xxt_out: Substance outlet loads of subsurface drainages in t/cell/yr (SS) or kg/cell/yr, for example, ppt_out for PP outlet loads.

Data management arguments

cv_dir: A character vector specifying the project root (first position) and optionally the Monte Carlo input data directory (second position).
ls_ini: A logical scalar specifying if the state of an existing project shall be loaded from disk (defaults to FALSE). Parameters or substance parameter values specified via the ... argument take precedence over loaded ones.
is_MCi: An integer scalar specifying the current Monte Carlo iteration if applicable (defaults to integer(), which means Monte Carlo simulation mode is disabled).
cv_MCl: A character vector specifying the names of the layers, which shall be written to disk with the associated Monte Carlo iteration in their filenames upon calling the appropriate methods (defaults to "xxt"; no effect in case Monte Carlo simulation mode is disabled).

Model parameter arguments

ns_slp_min: A numeric scalar specifying the minimum bounding slope in % (defaults to 0.001).
ns_slp_max: A numeric scalar specifying the maximum bounding slope in % (defaults to 999.0).
ns_rhy_a: A numeric scalar specifying a network constant depending on the discharge frequency needed for the calculation of the hydraulic radius, which in turn is a prerequisite for substance transport (defaults to 0.09 representing a discharge frequency of approximately six years).
ns_rhy_b: A numeric scalar specifying a geometry scaling exponent depending on the discharge frequency needed for the calculation of the hydraulic radius, which in turn is a prerequisite for substance transport (defaults to 0.50 representing a discharge frequency of approximately six years).
ns_cha_rto: A numeric scalar specifying the ratio of the channel to the cell width determining the widths of the riparian zones required for substance transport (defaults to 0.5).
ns_man_rip: A numeric scalar specifying Manning's roughness coefficient of the riparian zones within channel cells required for substance transport (defaults to 0.32).
ns_man_cha: A numeric scalar specifying Manning's roughness coefficient of the channel within channel cells required for substance transport (defaults to 0.04).
ns_dep_ovl: A numeric scalar specifying the overland deposition rate per second required for substance transport (calibration parameter; no default).
ns_dep_cha: A numeric scalar specifying the channel deposition rate per second required for substance transport (calibration parameter; no default).
nv_tfc_inl: A named numeric vector specifying the inlet transfer coefficients required for substance transport, for example, c(SS = 0.6, PP = 0.6) (no default).
nv_enr_rto A named numeric vector specifying the substance enrichment ratios required for substance except SS transport, for example, c(PP = 2.0) (calibration parameter; no default).
iv_fDo: An integer vector specifying the outflow direction vector required for substance transport (defaults to ArcGIS codes).
nm_olc: A two column numeric matrix specifying one or more catchment outlet coordinates required for the in-channel retention ratio of calibrationQuality (no default).
df_cdt: A data.frame with calibration data, which must have at least the following three columns and one or more columns with substance river loads in t/yr (no default):
- ID: ID(s) of the gauge(s)
- x: x-coordinate(s) of the gauge(s)
- y: y-coordinate(s) of the gauge(s)

Monte Carlo simulation mode

This mode can make use of repeated random samples, i.e. raster data, of distributions of about all input data. The filenames of the Monte Carlo input raster data must contain the specified iteration, for example, CFa12.tif for the twelfth iteration of the C-factors input data, and can reside in a separate directory. In case no Monte Carlo raster file is found for a certain layer in the designated directory, the respective project root subdirectory is searched for one and finally the “normal” project input raster data is utilised.

Examples


# temporary demonstration project copy
cv_dir <- demoProject()

# initialise project from scratch
x <- RPhosFate(
  cv_dir = cv_dir,
  ns_dep_ovl = 25e-4,
  ns_dep_cha = 0.0,
  nv_tfc_inl = c(SS = 0.6, PP = 0.6),
  nv_enr_rto = c(PP = 2.0),
  nm_olc = matrix(c(4704255, 2795195), ncol = 2L),
  df_cdt = read.table(
    file.path(cv_dir, "cdt.txt"),
    header = TRUE,
    stringsAsFactors = FALSE
  )
)

# load state of existing project in Monte Carlo simulation mode
x <- RPhosFate(
  cv_dir = c(
    cv_dir,
    system.file("tinytest", "testProject", package = "RPhosFate")
  ),
  ls_ini = TRUE,
  is_MCi = 1L,
  cv_MCl = c("xxt", "xxt_cld")
)

# temporary demonstration project copy
cv_dir <- demoProject()

# initialise project from scratch
x <- RPhosFate(
  cv_dir = cv_dir,
  ns_dep_ovl = 25e-4,
  ns_dep_cha = 0.0,
  nv_tfc_inl = c(SS = 0.6, PP = 0.6),
  nv_enr_rto = c(PP = 2.0),
  nm_olc = matrix(c(4704255, 2795195), ncol = 2L),
  df_cdt = read.table(
    file.path(cv_dir, "cdt.txt"),
    header = TRUE,
    stringsAsFactors = FALSE
  )
)

# load state of existing project in Monte Carlo simulation mode
x <- RPhosFate(
  cv_dir = c(
    cv_dir,
    system.file("tinytest", "testProject", package = "RPhosFate")
  ),
  ls_ini = TRUE,
  is_MCi = 1L,
  cv_MCl = c("xxt", "xxt_cld")
)

RPhosFate class

Description

An S4 object representing a river catchment.

Slots

cv_dir: A character vector holding the project root (first position) and optionally the Monte Carlo input data directory (second position).
ls_ini: A logical scalar specifying if the state of an existing project was loaded from disk.
is_MCi: An integer scalar holding the current Monte Carlo iteration if applicable.
cv_MCl: A character vector holding the names of the layers, which shall be written to disk with the associated Monte Carlo iteration in their filenames upon calling the appropriate methods.
cs_fex: A character string holding the automatically determined file extension of the provided raster files (either ".tif" or ".img" for backward compatibility).
parameters: An S4 object holding the model parameters.
topo: An S4 object holding the raster layers related to topography in the broader sense.
erosion: An S4 object holding the raster layers related to erosion.
transport: An S4 object holding raster layers required for modelling transport.
substances: An S4 object holding the substance raster layer containers.
helpers: An S4 object holding helper data.

Save state

Description

Saves parameters (parameters.yaml) and transport calculation order (order.rds) to disk.

Usage

## S4 method for signature 'RPhosFate'
saveState(x)
## S4 method for signature 'RPhosFate'
saveState(x)

Arguments

`x`	An S4 `RPhosFate` river catchment object.

Value

NULL invisibly and side effects in the form of files.

Examples


# temporary demonstration project copy
cv_dir <- demoProject()
# load temporary demonstration project
x <- RPhosFate(
  cv_dir = cv_dir,
  ls_ini = TRUE
)

saveState(x)

# temporary demonstration project copy
cv_dir <- demoProject()
# load temporary demonstration project
x <- RPhosFate(
  cv_dir = cv_dir,
  ls_ini = TRUE
)

saveState(x)

Set parameter(s)

Description

Sets one or more model parameters or substance parameter values.

Usage

## S4 method for signature 'RPhosFate'
setParameter(x, ...)
## S4 method for signature 'RPhosFate'
setParameter(x, ...)

Arguments

`x`	An S4 `RPhosFate` river catchment object.
`...`	Names and values of the parameters to set. See model parameter arguments section for further information.

Value

An S4 RPhosFate river catchment object.

Model parameter arguments

ns_slp_min: A numeric scalar specifying the minimum bounding slope in % (defaults to 0.001).
ns_slp_max: A numeric scalar specifying the maximum bounding slope in % (defaults to 999.0).
ns_rhy_a: A numeric scalar specifying a network constant depending on the discharge frequency needed for the calculation of the hydraulic radius, which in turn is a prerequisite for substance transport (defaults to 0.09 representing a discharge frequency of approximately six years).
ns_rhy_b: A numeric scalar specifying a geometry scaling exponent depending on the discharge frequency needed for the calculation of the hydraulic radius, which in turn is a prerequisite for substance transport (defaults to 0.50 representing a discharge frequency of approximately six years).
ns_cha_rto: A numeric scalar specifying the ratio of the channel to the cell width determining the widths of the riparian zones required for substance transport (defaults to 0.5).
ns_man_rip: A numeric scalar specifying Manning's roughness coefficient of the riparian zones within channel cells required for substance transport (defaults to 0.32).
ns_man_cha: A numeric scalar specifying Manning's roughness coefficient of the channel within channel cells required for substance transport (defaults to 0.04).
ns_dep_ovl: A numeric scalar specifying the overland deposition rate per second required for substance transport (calibration parameter; no default).
ns_dep_cha: A numeric scalar specifying the channel deposition rate per second required for substance transport (calibration parameter; no default).
nv_tfc_inl: A named numeric vector specifying the inlet transfer coefficients required for substance transport, for example, c(SS = 0.6, PP = 0.6) (no default).
nv_enr_rto A named numeric vector specifying the substance enrichment ratios required for substance except SS transport, for example, c(PP = 2.0) (calibration parameter; no default).
iv_fDo: An integer vector specifying the outflow direction vector required for substance transport (defaults to ArcGIS codes).
nm_olc: A two column numeric matrix specifying one or more catchment outlet coordinates required for the in-channel retention ratio of calibrationQuality (no default).
df_cdt: A data.frame with calibration data, which must have at least the following three columns and one or more columns with substance river loads in t/yr (no default):
- ID: ID(s) of the gauge(s)
- x: x-coordinate(s) of the gauge(s)
- y: y-coordinate(s) of the gauge(s)

Examples


# temporary demonstration project copy
cv_dir <- demoProject()
# load temporary demonstration project
x <- RPhosFate(
  cv_dir = cv_dir,
  ls_ini = TRUE
)

x <- setParameter(x, ns_dep_ovl = 15e-4)
x <- setParameter(
  x,
  nv_tfc_inl = c(SS = 0.6, PP = 0.6),
  nv_enr_rto = c(PP = 1.4)
)

# temporary demonstration project copy
cv_dir <- demoProject()
# load temporary demonstration project
x <- RPhosFate(
  cv_dir = cv_dir,
  ls_ini = TRUE
)

x <- setParameter(x, ns_dep_ovl = 15e-4)
x <- setParameter(
  x,
  nv_tfc_inl = c(SS = 0.6, PP = 0.6),
  nv_enr_rto = c(PP = 1.4)
)

Snap gauge(s)

Description

Snaps the coordinates of the provided calibration gauges to the respective midpoint of the nearest channel cell.

Usage

## S4 method for signature 'RPhosFate'
snapGauges(x)
## S4 method for signature 'RPhosFate'
snapGauges(x)

Arguments

`x`	An S4 `RPhosFate` river catchment object.

Value

An S4 RPhosFate river catchment object.

Examples


# temporary demonstration project copy
cv_dir <- demoProject()
# load temporary demonstration project
x <- RPhosFate(
  cv_dir = cv_dir,
  ls_ini = TRUE
)

x <- snapGauges(x)

# temporary demonstration project copy
cv_dir <- demoProject()
# load temporary demonstration project
x <- RPhosFate(
  cv_dir = cv_dir,
  ls_ini = TRUE
)

x <- snapGauges(x)

Subsequent run

Description

Calls transport for the specified substance and optionally erosionPrerequisites, erosion, emission, transportPrerequisites and/or transportCalcOrder beforehand.

Usage

## S4 method for signature 'RPhosFate'
subsequentRun(
  x,
  substance = "PP",
  erosionPrerequisites = FALSE,
  erosion = FALSE,
  emission = FALSE,
  transportPrerequisites = FALSE,
  transportCalcOrder = FALSE
)
## S4 method for signature 'RPhosFate'
subsequentRun(
  x,
  substance = "PP",
  erosionPrerequisites = FALSE,
  erosion = FALSE,
  emission = FALSE,
  transportPrerequisites = FALSE,
  transportCalcOrder = FALSE
)

Arguments

`x`	An S4 `RPhosFate` river catchment object.
`substance`	A character string specifying the substance to calculate.
`erosionPrerequisites`	A logical scalar specifying if `erosionPrerequisites` is called.
`erosion`	A logical scalar specifying if `erosion` is called.
`emission`	A logical scalar specifying if `emission` is called. It is never called with `substance = "SS"` though.
`transportPrerequisites`	A logical scalar specifying if `transportPrerequisites` is called.
`transportCalcOrder`	A logical scalar specifying if `transportCalcOrder` is called.

Value

An S4 RPhosFate river catchment object and side effects in the form of raster files.

Examples


# temporary demonstration project copy
cv_dir <- demoProject()
# load temporary demonstration project
x <- RPhosFate(
  cv_dir = cv_dir,
  ls_ini = TRUE
)
# presupposed method call
x <- firstRun(x, "SS")

x <- subsequentRun(x, "PP")

# temporary demonstration project copy
cv_dir <- demoProject()
# load temporary demonstration project
x <- RPhosFate(
  cv_dir = cv_dir,
  ls_ini = TRUE
)
# presupposed method call
x <- firstRun(x, "SS")

x <- subsequentRun(x, "PP")

Transport

Description

Calculates and writes substance retentions, transports and cell loads as well as transfers to disk.

Usage

## S4 method for signature 'RPhosFate'
transport(x, substance = "PP")
## S4 method for signature 'RPhosFate'
transport(x, substance = "PP")

Arguments

`x`	An S4 `RPhosFate` river catchment object.
`substance`	A character string specifying the substance to calculate.

Value

An S4 RPhosFate river catchment object and side effects in the form of raster files.

References

Engman, E.T., 1986. Roughness coefficients for routing surface runoff. Journal of Irrigation and Drainage Engineering 112, 39–53.

Examples


# temporary demonstration project copy
cv_dir <- demoProject()
# load temporary demonstration project
x <- RPhosFate(
  cv_dir = cv_dir,
  ls_ini = TRUE
)
# presupposed method calls
x <- erosionPrerequisites(x)
x <- erosion(x)
x <- emission(x, "PP")
x <- transportPrerequisites(x)
x <- transportCalcOrder(x)

x <- transport(x, "PP")

# temporary demonstration project copy
cv_dir <- demoProject()
# load temporary demonstration project
x <- RPhosFate(
  cv_dir = cv_dir,
  ls_ini = TRUE
)
# presupposed method calls
x <- erosionPrerequisites(x)
x <- erosion(x)
x <- emission(x, "PP")
x <- transportPrerequisites(x)
x <- transportCalcOrder(x)

x <- transport(x, "PP")

Transport calculation order

Description

Determines the cell transport calculation order.

Usage

## S4 method for signature 'RPhosFate'
transportCalcOrder(x)
## S4 method for signature 'RPhosFate'
transportCalcOrder(x)

Arguments

`x`	An S4 `RPhosFate` river catchment object.

Value

An S4 RPhosFate river catchment object.

Examples


# temporary demonstration project copy
cv_dir <- demoProject()
# load temporary demonstration project
x <- RPhosFate(
  cv_dir = cv_dir,
  ls_ini = TRUE
)

x <- transportCalcOrder(x)

# temporary demonstration project copy
cv_dir <- demoProject()
# load temporary demonstration project
x <- RPhosFate(
  cv_dir = cv_dir,
  ls_ini = TRUE
)

x <- transportCalcOrder(x)

Transport prerequisites

Description

Calculates hydraulic radii and determines cells representing inlets as well as riparian zones before writing them to disk.

Usage

## S4 method for signature 'RPhosFate'
transportPrerequisites(x)
## S4 method for signature 'RPhosFate'
transportPrerequisites(x)

Arguments

`x`	An S4 `RPhosFate` river catchment object.

Value

An S4 RPhosFate river catchment object and side effects in the form of raster files.

References

Molnár, P., Ramírez, J.A., 1998. Energy dissipation theories and optimal channel characteristics of river networks. Water Resources Research 34, 1809–1818.

Examples


# temporary demonstration project copy
cv_dir <- demoProject()
# load temporary demonstration project
x <- RPhosFate(
  cv_dir = cv_dir,
  ls_ini = TRUE
)

x <- transportPrerequisites(x)

# temporary demonstration project copy
cv_dir <- demoProject()
# load temporary demonstration project
x <- RPhosFate(
  cv_dir = cv_dir,
  ls_ini = TRUE
)

x <- transportPrerequisites(x)

Package 'RPhosFate'

Help Index

One dimensional automatic model calibration

Description

Usage

Arguments

Value

See Also

Examples

Two dimensional automatic model calibration

Description

Usage

Arguments

Value

See Also

Examples

Calibration quality

Description

Usage

Arguments

Value

References

See Also

Examples

Demonstration project

Description

Usage

Arguments

Value

See Also

Examples

DEM related input

Description

Usage

Arguments

Details

Value

References

See Also

Examples

Emission

Description

Usage

Arguments

Value

See Also

Examples

Erosion

Description

Usage

Arguments

Value

References

See Also

Examples

Erosion prerequisites

Description

Usage

Arguments

Value

References

See Also

Examples

First run

Description

Usage

Arguments

Value

See Also

Examples

Get layer

Description

Usage

Arguments

Value

Input subdirectory

Intermediate subdirectory

Result subdirectory

Examples

Get parameter(s)