Package 'rechaRge'

Simulation using a recharge model

Description

Performs a simulation of water recharge using a specific model.

HydroBudget is a spatially distributed GWR model that computes a superficial water budget on grid cells of regional-scale watersheds. Runoff, actual evapotranspiration (AET), and potential GWR are simulated for each grid cell, with a monthly time step, and fluxes do not transfer from a cell to another (no water routing). The model inputs are distributed daily precipitation and temperature as well as distributed data of pedology, land cover, and slope.

Usage

compute_recharge(
  obj,
  rcn,
  climate,
  rcn_climate,
  period = NULL,
  workers = 1,
  ...
)

## Default S3 method:
compute_recharge(
  obj,
  rcn,
  climate,
  rcn_climate,
  period = NULL,
  workers = 1,
  ...
)

## S3 method for class 'hydrobudget'
compute_recharge(
  obj,
  rcn,
  climate,
  rcn_climate,
  period = NULL,
  workers = 1,
  ...
)

Arguments

obj	The recharge object.
rcn	The RCN values. Input can be a data.frame/data.table or a path to a data file.
climate	The daily total precipitation (mm/d) and average daily temperature (°C). Input can be a data.frame/data.table or a path to a data file.
rcn_climate	The relation between the RCN and climate cells. Input can be a data.frame/data.table or a path to a data file.
period	The start and end years. If not provided, the start/end years will be extracted from the climate data.
workers	The number of workers to use in the parallel computations. If NULL, an optimal number of cores will be used. This optimal number is also the maximum value. Default value is 1 (no parallelization).
...	Other arguments passed to methods

Details

The expected columns for the RCN data set input are:

• rcn_id, the RCN cell ID

• RCNII

• lon

• lat

The expected columns for the climate data set input are:

• climate_id the climate cell ID

• day

• month

• year

• t_mean

• p_tot

• lat

The expected columns for the RCN-climate data set input are:

• climate_id the climate cell ID

• rcn_id, the RCN cell ID

The columns of the water budget data set output are:

• year

• month

• vi

• t_mean

• runoff

• pet

• aet

• gwr

• runoff_2

• delta_reservoir

• rcn_id

Value

The water budget

Examples

## Not run: 
# Use input example files provided by the package
base_url <- "https://github.com/gwrecharge/rechaRge-book/raw/main/examples/input/"
input_rcn <- paste0(base_url, "rcn.csv.gz")
input_climate <- paste0(base_url, "climate.csv.gz")
input_rcn_climate <- paste0(base_url, "rcn_climate.csv.gz")

# Calibration parameters
HB <- rechaRge::new_hydrobudget(
  T_m = 2.1, # melting temperature (°C)
  C_m = 6.2, # melting coefficient (mm/°C/d)
  TT_F = -17.6, # Threshold temperature for soil frost (°C)
  F_T = 16.4, # Freezing time (d)
  t_API = 3.9, # Antecedent precipitation index time (d)
  f_runoff = 0.63, # Runoff factor (-)
  sw_m = 431, # Maximum soil water content (mm)
  f_inf = 0.07 # infiltration factor (-)
)

# Simulation period
simul_period <- c(2010, 2017)

# Parallel computing option
# workers <- 6

# Simulation with the HydroBudget model
water_budget <- rechaRge::compute_recharge(
  HB,
  rcn = input_rcn,
  climate = input_climate,
  rcn_climate = input_rcn_climate,
  period = simul_period
  # workers = workers
)
head(water_budget)

## End(Not run)

---

Evaluate the quality of the simulation result

Description

From a simulation result, evaluate the quality by comparing with observations. The quality measurement can be used for model calibration (e.g. caRamel package) or sensitivity evaluation (e.g. sensitivity package).

Evaluates the simulated water budget with the average KGE.

Usage

evaluate_simulation_quality(obj, water_budget, ...)

## Default S3 method:
evaluate_simulation_quality(obj, water_budget, ...)

## S3 method for class 'hydrobudget'
evaluate_simulation_quality(
  obj,
  water_budget,
  rcn_gauging,
  observed_flow,
  alpha_lyne_hollick,
  period = NULL,
  ...
)

Arguments

obj	The HydroBudget object with calibration parameters and column names mappings.
water_budget	The computed water budget. Input can be a data.frame/data.table or a path to a data file.
...	Other arguments passed to methods
rcn_gauging	The table with the list of RCN cells located in each gauging station watershed. Input can be a data.frame/data.table or a path to a data file.
observed_flow	The flow rates in mm/day. Input can be a data.frame/data.table or a path to a data file.
alpha_lyne_hollick	The Lyne and Hollick filter. Input can be a data.frame/data.table or a path to a data file.
period	The start and end years. If not provided, the start/end years will be extracted from the water budget data.

Details

The columns of the water budget data set input are:

• year

• month

• vi

• t_mean

• runoff

• pet

• aet

• gwr

• runoff_2

• delta_reservoir

• rcn_id

The columns of the observed flow data set input are:

• year

• month

• day

• one column per station (named by the station ID), the flow rates in mm/day

The columns of the RCN gauging stations data set input are:

• rcn_id, the cell ID

• station_id, the station ID

The columns of the Lyne and Hollick filter data set input are:

• station_id, the station ID

• alpha

Value

The model-specific quality assessment.

The HydroBudget quality assessment.

Examples

## Not run: 
# Use input example files provided by the package
base_url <- "https://github.com/gwrecharge/rechaRge-book/raw/main/examples/input/"
input_rcn_gauging <- paste0(base_url, "rcn_gauging.csv.gz")
input_observed_flow <- paste0(base_url, "observed_flow.csv.gz")
input_alpha_lyne_hollick <- paste0(base_url, "alpha_lyne_hollick.csv.gz")

# Calibration parameters
HB <- rechaRge::new_hydrobudget(
  T_m = 2.1, # melting temperature (°C)
  C_m = 6.2, # melting coefficient (mm/°C/d)
  TT_F = -17.6, # Threshold temperature for soil frost (°C)
  F_T = 16.4, # Freezing time (d)
  t_API = 3.9, # Antecedent precipitation index time (d)
  f_runoff = 0.63, # Runoff factor (-)
  sw_m = 431, # Maximum soil water content (mm)
  f_inf = 0.07 # infiltration factor (-)
)

# ... compute the water budget ...

result <- evaluate_simulation_quality(
  HB,
  water_budget = water_budget,
  rcn_gauging = input_rcn_gauging,
  observed_flow = input_observed_flow,
  alpha_lyne_hollick = input_alpha_lyne_hollick,
  period = simul_period
)

## End(Not run)

---

KGE computation

Description

Compute the Kling-Gupta Efficiency coefficient which summarizes the discrepancy between observed values and the values expected under the model in question.

Usage

KGE(sim, obs)

Arguments

sim	Simulated values
obs	Observed values

Value

Kling-Gupta Efficiency between 'sim' and 'obs'

Examples

sim <- c(0.5, 0.5, 10, 15, 0.5, 20, 25, 0.1, 15, 10)
obs <- c(1, 0.1, 0.1, 20, 0.6, 30, 20, 0.5, 30, 8)
rechaRge::KGE(sim, obs)

---

HydroBudget object

Description

Make a new HydroBudget object, by providing the calibration parameters for the model computation.

Usage

new_hydrobudget(T_m, C_m, TT_F, F_T, t_API, f_runoff, sw_m, f_inf)

Arguments

T_m	The melting temperature (°C)
C_m	The melting coefficient (mm/°C/d)
TT_F	The Threshold temperature for soil frost (°C)
F_T	The freezing time (d)
t_API	The antecedent precipitation index time (d)
f_runoff	The runoff factor (-)
sw_m	The maximum soil water content (mm)
f_inf	The infiltration factor (-)

Value

An object of class hydrobudget

---

Progress option

Description

Progress option

Usage

with_progress(progress = TRUE)

Arguments

progress

Logical to set for having a progress bar

Value

(Invisible) the return value of handlers

---

Verbose option

Description

Verbose option

Usage

with_verbose(verbose = TRUE)

Arguments

verbose

Logical to set for having verbose messages

Value

(Invisible) the return value of options

---

Write result as raster files

Description

Export raster for interannual runoff, aet and GWR.

Usage

write_recharge_rasters(
  obj,
  water_budget,
  input_rcn,
  crs,
  output_dir = tempdir(),
  ...
)

## Default S3 method:
write_recharge_rasters(
  obj,
  water_budget,
  input_rcn,
  crs,
  output_dir = tempdir(),
  ...
)

## S3 method for class 'hydrobudget'
write_recharge_rasters(
  obj,
  water_budget,
  input_rcn,
  crs,
  output_dir = tempdir(),
  ...
)

Arguments

obj	The recharge object.
water_budget	The computed water budget. Input can be a data.frame/data.table or a path to a data file.
input_rcn	The RCN values. Input can be a data.frame/data.table or a path to a data file.
crs	The coordinate reference systems.
output_dir	The output directory where result files will be written. Default is a temporary directory.
...	Other arguments passed to methods

Value

(Invisible) the output directory.

---

Write result as data files

Description

Export water budget.

Supported formats are "csv" (default) or "nc" (NetCDF).

Usage

write_recharge_results(obj, water_budget, output_dir = tempdir(), ...)

## Default S3 method:
write_recharge_results(obj, water_budget, output_dir = tempdir(), ...)

## S3 method for class 'hydrobudget'
write_recharge_results(
  obj,
  water_budget,
  output_dir = tempdir(),
  format = "csv",
  input_rcn = NULL,
  names = list(lon = list(longname = "Longitude", unit = "deg"), lat = list(longname =
    "Lattitude", unit = "deg"), time = list(longname =
    "Month since start of the water budget", unit = "month")),
  ...
)

Arguments

obj	The recharge object.
water_budget	The computed water budget.
output_dir	The output directory where result files will be written. Default is a temporary directory.
...	Other arguments passed to methods
format	The file output format. Use "nc" for NetCDF format. Default is "csv".
input_rcn	The RCN values. Input can be a data.frame/data.table or a path to a data file.
names	The long names and units of the NetCDF dimensions.

Value

(Invisible) the output directory.

---