Skip to contents

Calibrate a Hydrological Model

calibrate_model.Rd

Performs calibration of a hydrological model using a specified optimization algorithm. Supports models from the airGR, TUWmodel, hydromad, and topmodel packages, with optional snow module integration. The function supports both native calibration routines (e.g., Calibration_Michel for airGR) and general-purpose optimizers (e.g., DEoptim, hydroPSO, malschains).

Usage

calibrate_model(
  hydro_data,
  split_indices,
  model,
  input,
  snow_module = NULL,
  snow_input = NULL,
  snow_parameters = NULL,
  error_crit_transfo = "KGE__none",
  cal_maximize = TRUE,
  cal_fn = "DEoptim",
  do_transfo_param = FALSE,
  cal_par = default_cal_par
)

Arguments

hydro_data

A list or data frame containing observed runoff and meteorological data, typically loaded using load_meteo_data.

split_indices

A list of index vectors (e.g., from split_data_set) indicating warm-up and calibration periods.

model

A string specifying the hydrological model to calibrate. For a complete list see table in vignette("model_overview").

input

A list of model input data, typically created using create_input.

snow_module

Optional. A string specifying the snow module (currently "CemaNeige" and "TUWsnow").

snow_input

Optional. Input data for the snow module.

snow_parameters

Optional. A vector of fixed snow parameters. If NULL, snow parameters are assumed to be part of the calibration.

error_crit_transfo

A string combining the error criterion and runoff transformation, separated by "__" (e.g., "KGE__none"). Optionally, a third value (e.g., lambda) can be included for transformations like Box-Cox.

cal_maximize

Logical. If TRUE, the calibration maximizes the objective function.

cal_fn

A string specifying the calibration function. Supported options include "Calibration_Michel" (for airGR models), "DEoptim", "hydroPSO", "malschains", and other supported optimizers. For a complete list see table in vignette("calibration_methods_overview").

do_transfo_param

Logical. If TRUE, parameters are transformed to a unit hypercube before calibration.

cal_par

A list of calibration settings specific to the chosen calibration function. Defaults to default_cal_par, but can be customized by the user.

Value

A list containing:

  • model_param: Calibrated model parameters.

  • error_crit_transfo: The error criterion and transformation used.

  • error_crit_val: The final value of the error criterion.

  • cal_fn: The calibration function used.

  • do_transfo_param: Whether parameter transformation was applied.

  • duration: Duration of the calibration process.

  • cal_par: Calibration settings used.

  • more_info: Additional model- or method-specific output.

Note

  • Calibration_Michel is only available for airGR models.

  • If Calibration_Michel is used, parameters are assumed to be transformed.

  • The function supports power and Box-Cox runoff transformations, with lambda optionally specified.

  • Future improvements may simplify access to cal_par for end users.

See also

call_cal_fn, optim_fn, create_input, load_meteo_data, split_data_set, transfo_q

Examples

if (FALSE) {
calibration_results <- calibrate_model(
  hydro_data = hydro_data,
  split_indices = split_data_set(...),
  model = "GR4J",
  input = create_input(...),
  error_crit_transfo = "KGE__none",
  cal_maximize = TRUE,
  cal_fn = "DEoptim",
  do_transfo_param = TRUE,
  cal_par = default_cal_par
)
}