ctool_calibrate: Calibrate C-TOOL using observed topsoil SOC

In rCTOOL: Soil Organic Carbon Turnover Modelling with 'C-TOOL'

Calibrate C-TOOL using observed topsoil SOC

Description

Calibrates two C-TOOL parameters against observed SOC stocks: 'f_hum_top' and 'k_hum'.

Usage

ctool_calibrate(
  time_config,
  cinput_config,
  temperature_config,
  management_config,
  soil_config,
  observed,
  f_hum_top = c(min = 0.2, max = 0.6, by = 0.05),
  k_hum = c(min = 0.002, max = 0.004, by = 5e-04),
  cn_init = 10,
  years_col = "Year",
  obs_col = "SOC_obs",
  f_fom_top = 0.003,
  metric = "d_index",
  minimize = NULL,
  keep_simulations = FALSE,
  verbose = TRUE
)

Arguments

time_config	A C-TOOL time configuration object returned by [define_timeperiod()].
cinput_config	A C-TOOL carbon input configuration object returned by [define_Cinputs()].
temperature_config	A C-TOOL compatible temperature configuration used by [run_ctool()]. It must contain at least 'month' and 'Tavg'. A single historical annual temperature amplitude is calculated internally from the monthly climatology of 'Tavg'.
management_config	A C-TOOL management configuration object returned by [management_config()].
soil_config	A C-TOOL soil configuration object returned by [soil_config()]. All parameters are preserved, except 'f_hum_top', 'k_hum', and the internally recalculated 'f_rom_top'.
observed	A data frame with observed SOC values. By default, it must contain columns 'Year' and 'SOC_obs'.
f_hum_top	Named numeric vector defining the calibration range for 'f_hum_top', with names 'min', 'max', and 'by'.
k_hum	Named numeric vector defining the calibration range for 'k_hum', with names 'min', 'max', and 'by'.
cn_init	Initial C:N ratio used by [initialize_soil_pools()]. Default is '10'.
years_col	Name of the year column in 'observed'. Default is '"Year"'.
obs_col	Name of the observed SOC column in 'observed'. Default is '"SOC_obs"'.
f_fom_top	Fixed topsoil FOM transfer fraction used to calculate 'f_rom_top'. Default is '0.003'.
metric	Character. Metric used to select the best tested parameter set. Options are '"d_index"', '"RMSE"', '"R2"', '"MAE"', and '"Bias"'. Default is '"d_index"'. The legacy value '"d"' is also accepted and internally converted to '"d_index"'.
minimize	Logical. Should the selected metric be minimized? If 'NULL', sensible defaults are used: 'FALSE' for '"d_index"' and '"R2"', and 'TRUE' for '"RMSE"', '"MAE"', and absolute '"Bias"'.
keep_simulations	Logical. If 'TRUE', stores all calibrated simulation time series. Default is 'FALSE'.
verbose	Logical. If 'TRUE', prints progress messages.

Details

This function assumes that all C-TOOL simulation inputs have already been prepared using the standard rCTOOL workflow. The only additional data required for calibration is a two-column data frame containing observed SOC stocks by year.

The observed data frame must contain, by default:

- 'Year': observation year. - 'SOC_obs': observed SOC stock.

For each tested value of 'f_hum_top', 'f_rom_top' is calculated internally as:

'f_rom_top = 1 - f_hum_top - f_fom_top'

Invalid combinations where 'f_rom_top <= 0' are removed before model runs.

The function first evaluates the current C-TOOL parameter set supplied through 'soil_config'. It then evaluates the tested calibration grid. If the current C-TOOL parameter set performs as well as or better than the best tested calibration, the function recommends keeping the current parameters.

The main goodness-of-fit statistics returned by the function are RMSE, MAE, mean bias, R2, and the Willmott index of agreement, here reported as 'd_index'.

Value

An object of class '"ctool_calibration"', a list containing:

best_params

Best tested calibration parameter set and its metrics.

recommended_params

Recommended parameter set. This may be either the current C-TOOL parameter set or the best tested calibration.

recommendation

Text explaining whether to keep current parameters or use the best tested calibration.

metrics

Metrics for the current C-TOOL parameters and best tested calibration.

all_results

Metrics for all tested parameter combinations.

observed

Observed SOC data used for calibration.

default_simulation

Simulation using the supplied soil configuration.

best_simulation

Simulation using the best tested calibration.

recommended_simulation

Simulation using the recommended parameter set.

parameter_grid

Parameter grid used for calibration.

all_simulations

Optional list of all tested calibrated simulations.

settings

Calibration settings.

References

Willmott, C. J. (1981). On the validation of models. Physical Geography, 2(2), 184-194.

Examples

# Example workflow:
#
# observed <- data.frame(
#   Year = c(1923, 1932, 1942, 1950),
#   SOC_obs = c(54.2, 53.8, 52.1, 51.4)
# )
#
# calib <- ctool_calibrate(
#   time_config = time_cfg,
#   cinput_config = cin_cfg,
#   temperature_config = t_cfg,
#   management_config = m_cfg,
#   soil_config = soil_cfg,
#   observed = observed,
#   f_hum_top = c(min = 0.20, max = 0.60, by = 0.05),
#   k_hum = c(min = 0.0020, max = 0.0040, by = 0.0005)
# )

rCTOOL documentation built on July 4, 2026, 9:07 a.m.