Basic modelling workflow

This vignette provides an overview of the basic modelling workflow with the RPhosFate package.

Preparations

Load the package and obtain a copy of the demonstration project:

library(RPhosFate)

cv_dir <- demoProject()

Project initialisation

Use RPhosFate() or catchment() to initialise the project:

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
  )
)

First model run for suspended solids (SS)

firstRun() calls all low-level interface methods for the specified substance in the required order:

x <- firstRun(x, substance = "SS")

Calibration quality of SS

Snap coordinates of provided calibration gauges to the respective midpoint of the nearest channel cell if necessary and check calibration quality:

x <- snapGauges(x)

metrics <- calibrationQuality(x, substance = "SS", col = "SS_load")

Calibrate SS

SS is calibrated by iteratively specifying better parameter values for ns_dep_ovl (overland deposition rate) and/or ns_dep_cha (channel deposition rate) as well as calling subsequentRun() for SS afterwards until pleased with the metrics. By default, subsequentRun() only calls the transport() low-level interface method for the specified substance:

x <- setParameter(x, ns_dep_ovl = 15e-4)

x <- subsequentRun(x, substance = "SS")

metrics <- calibrationQuality(x, substance = "SS", col = "SS_load")

The autoCalibrate() and autoCalibrate2() methods may provide more comfortable alternatives to this process.

Calibration quality of particulate phosphorus (PP)

First, a further call to subsequentRun() for PP is necessary:

x <- subsequentRun(x, substance = "PP")

metrics <- calibrationQuality(x, substance = "PP", col = "PP_load")

Calibrate PP

Same procedure as with SS apart from iteratively specifying better parameter values for the enrichment ratio:

x <- setParameter(x, nv_enr_rto = c(PP = 1.4))

x <- subsequentRun(x, substance = "PP")

metrics <- calibrationQuality(x, substance = "PP", col = "PP_load")

In case the only substance of interest is PP, it is possible to set its enrichment ratio to one and directly calibrate it via ns_dep_ovl and/or ns_dep_cha.

Save state

Write parameters and transport calculation order to disk:

saveState(x)

Return to the calibrated project at a later time

Simply load the previously saved state of the project via the ls_ini argument of RPhosFate() or catchment():

x <- RPhosFate(
  cv_dir = cv_dir,
  ls_ini = TRUE
)

Gerold Hepp

2023-10-08