Title:	HydroBudget – Groundwater Recharge Model
Version:	1.0.0
Description:	HydroBudget is a spatially distributed groundwater recharge model that computes a superficial water budget on grid cells with outputs aggregated into monthly time steps. It was developed as an accessible and computationally affordable model to simulate groundwater recharge over large areas (thousands of km2, regional-scale watersheds) and for long time periods (decades), in cold and humid climates. Model algorithms are based on the research of Dubois, E. et al. (2021a) <doi:10.5683/SP3/EUDV3H> and Dubois, E. et al. (2021b) <doi:10.5194/hess-25-6567-2021>.
Depends:	R (≥ 4.0)
Imports:	airGR, data.table, future, doFuture, foreach, hydrostats, lubridate, ncdf4, plyr, progressr, raster, stats, sp, zoo, R.utils
Suggests:	testthat (≥ 3.0.0), curl
URL:	https://github.com/gwrecharge/rechaRge/, https://gwrecharge.github.io/rechaRge-book/
BugReports:	https://github.com/gwrecharge/rechaRge/issues/
License:	CC BY 4.0
Encoding:	UTF-8
RoxygenNote:	7.3.1
Config/testthat/edition:	3
NeedsCompilation:	no
Packaged:	2024-05-13 14:47:40 UTC; ymarcon
Author:	Yannick Marcon [cre, ctb], Emmanuel Dubois [aut, cph]
Maintainer:	Yannick Marcon <yannick.marcon@epfl.ch>
Repository:	CRAN
Date/Publication:	2024-05-14 08:20:02 UTC

Make a data.table from input: coerce it or read it (if it is a file path) and ensure column names

Description

Make a data.table from input: coerce it or read it (if it is a file path) and ensure column names

Usage

.as.data.table(input, colmap = NULL)

Make a data.table from input: coerce it or read it (if it is a file path) and ensure column names

Description

Make a data.table from input: coerce it or read it (if it is a file path) and ensure column names

Usage

.is.verbose()

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

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)

Compute PET based on the Oudin formula

Description

Compute PET based on the Oudin formula

Usage

compute_potential_evapotranspiration_cell(obj, input_dd)

Arguments

Value

Spatially distributed daily PET

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

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)

Determine if precipitation is rain or snow and simulate the snowpack (accumulation and melt) to compute the vertical inflow (vi), the liquid water available per day (rainfall + melt water).

Description

Determine if precipitation is rain or snow and simulate the snowpack (accumulation and melt) to compute the vertical inflow (vi), the liquid water available per day (rainfall + melt water).

Usage

compute_vertical_inflow(obj, climate_data)

Arguments

Compute the vertical inflow and the potential evapotranspiration (PET) for a single cell

Description

Compute the vertical inflow and the potential evapotranspiration (PET) for a single cell

Usage

compute_vertical_inflow_cell(obj, input_dd)

Arguments

Compute the water budget

Description

Compute the water budget

Usage

compute_water_budget(obj, rcn_data, climate_data, workers)

Arguments

Compute the water budget for a single cell

Description

Compute the water budget for a single cell

Usage

compute_water_budget_cell(obj, rcn_climate)

Arguments

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

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)

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

Value

An object of class hydrobudget

River flow processing

Description

Processing of the river flow to compute the baseflow with Lyne and Hollick and resample them into monthly observations by:

1. select the available river flow observations for the simulation period and fill the gaps (up to 5 missing days),

2. extract the list of the available gauging stations for the simulation period (list of the names),

3. compute the Lyne and Hollick baseflow and resample river flow and baseflow with a monthly time step.

Usage

process_river_flow(obj, observed_flow, alpha_lyne_hollick)

Arguments

Value

A list of observed_flow_month and gauging

Progress option

Description

Progress option

Usage

with_progress(progress = TRUE)

Arguments

Value

(Invisible) the return value of handlers

Verbose option

Description

Verbose option

Usage

with_verbose(verbose = TRUE)

Arguments

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

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

Value

(Invisible) the output directory.