rvn_rvp_fill_template: Rewrite template rvp file with values

Description

Rewrites a Raven template rvp file with default parameter values.

Usage

rvn_rvp_fill_template(
  rvi_file = NULL,
  rvh_file = NULL,
  rvp_template_file = NULL,
  fileprefix = NULL,
  rvp_out = NULL,
  overwrite = FALSE,
  default_param_value = 0.12345,
  default_soil_thickness = 0.5,
  use_default_flag = FALSE,
  avg_annual_runoff = NULL,
  extra_commands = NULL,
  RavenParamsFile = system.file("extdata", "RavenParameters.dat", package = "RavenR")
)

Value

TRUE if the function executed successfully

Arguments

rvi_file: path to the model *.rvi file
rvh_file: path to the model *.rvh file
rvp_template_file: path to the model rvp template file (*.rvp_temp.rvp)
fileprefix: model name prefix for the main model files; if provided, the function will attempt to find all missing file paths in the current working directory
rvp_out: file path to rewritten rvp file
overwrite: logical for whether to rewrite the *.rvp file if it already exists (default FALSE)
default_param_value: default parameter value to write for any parameters not found in RavenParameters.dat
default_soil_thickness: default soil layer thickness (m) to provide in :SoilProfile block
use_default_flag: writes all soil/land use/vegetation classes with [DEFAULT] flag
avg_annual_runoff: adds a line for :AvgAnnualRunoff if value provided with this parameter and not already in file
extra_commands: additional commands to add to end of rvp file as character vector
RavenParamsFile: path to RavenParameters.dat file (default path points to file included with RavenR installation)

Details

The Raven rvp template file is generated by Raven when the :CreateRVPTemplate command is included in the rvi file (the default when rvn_rvi_write_template is used to produce an rvi file). This template file displays the layout of the rvp file with required parameters based on the hydrologic processes in the rvi file, but is not immediately usable. This function uses the soil model information in the rvi file and the HRU class information in the rvh file to rewrite the template file with default parameter values so that it can be used in a model run.

If rvp_out is not provided, Raven will attempt to write to the file prefix of the provided template file with a .rvp extension. If there is a conflict with an existing file and overwrite==FALSE, the function will automatically overwrite a file with the suffix "_ravenr_generated.rvp".

The default parameter values come from the RavenParameters.dat file included with RavenR in the extdata folder. The user may provide their own file with updated values if preferred. Note that the database files held in the RavenR package are unofficial copies of those in the official Raven SVN, and any discrepancies should defer to the Raven SVN versions.

Any parameters not found in this file will be written with the value provided by default_param_value. The default soil thickness for the :SoilProfiles block is provided by the default_soil_thickness function parameter, which is applied for all soil classes.

As an alternative to specifying the three input files (rvi, rvh, rvp_temp.rvp), the fileprefix of the model (e.g. 'Nith' for Nith.rvi) may be provided instead. If provided, the function will attempt to find all required input files based on the provided fileprefix in the current working directory.

Additional commands can be added to the end of the rvp file with extra_commands, which are not quality controlled but simply appended to the rvp file. This can be useful for non-standard commands such as :RedirectToFile for channel properties rvp files that are not added automatically to base templates rvp files.

If you find parameters not found by this function, please open an ticket on Github (https://github.com/rchlumsk/RavenR/issues).

Examples

Run this code


### this section is not run, but illustrates how an rvp template file would be created
# -----
if (FALSE) {
## create an rvi file and template file with Raven
rvn_rvi_write_template(modelname="HBV-EC",
   filename="nithmodel.rvi")

## download Raven.exe if not already downloaded
if (!rvn_download(check=TRUE)) {
  rvn_download()
}

## run Raven to create template file
rvn_run(fileprefix="nithmodel")
}
# -----

# load pre-generated template file and other model files
nithmodel_template_file <- system.file("extdata","nithmodel.rvp_temp.rvp", package="RavenR")
nith_rvi_file <- system.file("extdata","Nith.rvi", package="RavenR")
nith_rvh_file <- system.file("extdata","Nith.rvh", package="RavenR")
rvp_out_file <- file.path(tempdir(), 'nithmodel.rvp')

# rewrite template with parameter values
rvn_rvp_fill_template(rvi_file=nith_rvi_file,
                      rvh_file=nith_rvh_file,
                      rvp_template_file=nithmodel_template_file,
                      rvp_out=rvp_out_file)