Package {rCTOOL}

rCTOOL package

Description

Provides an 'R' interface to the 'C-TOOL' soil carbon turnover model for simulating soil organic carbon dynamics in agricultural systems. The package supports the definition of carbon inputs, management schedules, soil parameters, and temperature forcing, and includes tools for scenario analysis and calibration of selected model parameters against observed soil organic carbon stocks. The 'C-TOOL' model and related modelling framework are described by Petersen et al. (2002) doi:10.1016/S0304-3800(02)00034-0, Petersen et al. (2005) doi:10.1016/j.soilbio.2004.08.006, Petersen et al. (2013) doi:10.1016/j.jclepro.2013.03.007, and Taghizadeh-Toosi et al. (2014) doi:10.1016/j.ecolmodel.2014.08.016. Further applications and developments are described by Taghizadeh-Toosi et al. (2016) doi:10.1016/j.agsy.2016.03.004, Keel et al. (2017) doi:10.1111/ejss.12454, Taghizadeh-Toosi et al. (2020) doi:10.1007/s11104-020-04500-9, and Taghizadeh-Toosi and Christensen (2021) doi:10.1038/s41598-021-97744-z.

Author(s)

Maintainer: Franca Giannini-Kurina francagk@agro.au.dk

Authors:

• Evandro H. Figueiredo Moura da Silva ehfmsilva@agro.au.dk

• João Serra

.clean_monthly_allocations

Description

Clean and harmonize monthly allocation inputs.

Usage

.clean_monthly_allocations(m_config)

Arguments

Details

Reads management configuration with monthly allocation vectors and returns a configuration containing 'plant_monthly_allocation'.

Depending on the user input: - if plant, grain and grass allocations are all provided, plant allocation is recalculated as grain plus grass - if only one allocation is provided, it is treated as plant allocation - if two allocations are provided, they must correspond to grain and grass; otherwise an error is returned

Value

A management configuration list containing 'plant_monthly_allocation'.

.decay

Description

Calculate soil carbon loss by first-order decomposition.

Usage

.decay(CO_t, k, tempCoefficient)

Arguments

Value

Carbon change due to decomposition during the timestep.

.soil_temp

Description

.soil_temp

Usage

.soil_temp(depth, month, T_ave, Amplitude, th_diff)

Arguments

Value

Soil temperature at the midpoint of the soil layer for the specified monthly timestep.

.temp_coef

Description

Calculate the temperature response coefficient for carbon decomposition.

Usage

.temp_coef(T_zt)

Arguments

Value

Temperature response coefficient for carbon decomposition.

FOM_sub_calculations

Description

Calculate FOM decomposition and carbon fluxes in the subsoil layer.

Usage

FOM_sub_calculations(FOM_sub_t, month, t_avg, amplitude, s_config)

Arguments

Value

A list with updated pool values and fluxes for FOM subsoil layer.

Examples

FOM_sub_calculations(
  FOM_sub_t = 10,
  month = 7,
  t_avg = 15,
  amplitude = 10,
  s_config = soil_config()
)

FOM_top_calculations

Description

Calculate FOM decomposition and carbon fluxes in the topsoil layer.

Usage

FOM_top_calculations(
  FOM_top_t,
  month,
  t_avg = t_avg,
  amplitude = amplitude,
  s_config
)

Arguments

Value

A list with updated pool values and fluxes for FOM topsoil layer.

Examples

FOM_top_calculations(
  FOM_top_t = 10,
  month = 7,
  t_avg = 15,
  amplitude = 10,
  s_config = soil_config()
)

HUM_sub_calculations

Description

Calculate HUM decomposition and carbon fluxes in the subsoil layer.

Usage

HUM_sub_calculations(HUM_sub_t, month, t_avg, amplitude, s_config)

Arguments

Value

A list with updated HUM subsoil pool values and associated fluxes.

Examples

HUM_sub_calculations(
  HUM_sub_t = 20,
  month = 7,
  t_avg = 15,
  amplitude = 10,
  s_config = soil_config()
)

HUM_top_calculations

Description

Calculate HUM decomposition and carbon fluxes in the topsoil layer.

Usage

HUM_top_calculations(
  HUM_top_t,
  month,
  t_avg = t_avg,
  amplitude = amplitude,
  s_config
)

Arguments

Value

A list with updated HUM topsoil pool values and associated fluxes.

Examples

HUM_top_calculations(
  HUM_top_t = 20,
  month = 7,
  t_avg = 15,
  amplitude = 10,
  s_config = soil_config()
)

ROM_sub_calculations

Description

Calculate ROM decomposition and carbon fluxes in the subsoil layer.

Usage

ROM_sub_calculations(ROM_sub_t, month, t_avg, amplitude, s_config)

Arguments

Value

A list with updated ROM subsoil pool values and associated fluxes.

Examples

ROM_sub_calculations(
  ROM_sub_t = 10,
  month = 7,
  t_avg = 15,
  amplitude = 10,
  s_config = soil_config()
)

ROM_top_calculations

Description

Calculate ROM decomposition and carbon fluxes in the topsoil layer.

Usage

ROM_top_calculations(ROM_top_t, month, t_avg, amplitude, s_config)

Arguments

Value

A list with updated ROM topsoil pool values and associated fluxes.

Examples

ROM_top_calculations(
  ROM_top_t = 10,
  month = 7,
  t_avg = 15,
  amplitude = 10,
  s_config = soil_config()
)

Basic rCTOOL example dataset

Description

Example dataset used to demonstrate a basic rCTOOL simulation.

Usage

basic_example

Format

A data frame.

Source

Internal example dataset distributed with rCTOOL.

check_balance

Description

Check carbon balance consistency of a simulation.

Usage

check_balance(ctool_output, cin_config, s_config)

Arguments

Details

Computes the balance between initial soil carbon, cumulative carbon inputs, final carbon stocks and cumulative CO2 emissions. The balance should be zero or very close to zero.

Value

The input 'ctool_output' data.frame, returned unchanged after checking carbon balance consistency.

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

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)
# )

Calculate C-TOOL calibration metrics

Description

Calculates performance metrics between observed and simulated SOC values.

Usage

ctool_calibration_metrics(observed, simulated)

Arguments

Details

The returned 'd_index' is the Willmott index of agreement.

Value

A data frame with 'd_index', 'RMSE', 'R2', 'Bias', 'MAE', and 'n'.

References

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

Examples

ctool_calibration_metrics(
  observed = c(50, 52, 55),
  simulated = c(49, 53, 54)
)

define_Cinputs

Description

Prepare annual carbon input (from plants and/or manure) configuration.

Usage

define_Cinputs(
  management_filepath = NULL,
  Cin_top = NULL,
  Cin_sub = NULL,
  Cin_man = NULL,
  time_config = NULL
)

Arguments

Value

A list containing 'Cin_top', 'Cin_sub' and 'Cin_man'.

Examples

time_config <- define_timeperiod(yr_start = 2006, yr_end = 2008)
define_Cinputs(
  Cin_top = c(2, 2, 2),
  Cin_sub = c(0.5, 0.5, 0.5),
  Cin_man = c(1, 1, 1),
  time_config = time_config
)

define_physical_boundaries

Description

Check whether a parameter value lies within specified physical bounds.

Usage

define_physical_boundaries(value, min_limit, max_limit)

Arguments

Value

The input value if it lies within the specified physical bounds.

Examples

define_physical_boundaries(0.3, 0, 1)

define_timeperiod

Description

Create the monthly simulation time structure.

Usage

define_timeperiod(yr_start, yr_end)

Arguments

Value

A list with two elements: 'timeperiod', a data.frame containing monthly timesteps, years and annual timestep identifiers; and 'steps', the total number of simulated months.

Examples

 define_timeperiod(yr_start=2006, yr_end=2010)

export_management_template

Description

Exports a template that can be used to provide management inputs for the model. The exported file includes monthly allocation variables and carbon input columns initialized with zeros, so they can be filled by the user before being read by the model.

Usage

export_management_template(yr_start, yr_end, filepath)

Arguments

Details

Users should keep only the columns relevant to their workflow and avoid double accounting among allocation variables. For example, when 'plant_monthly_allocation' is used, grain and grass allocation columns should not be used simultaneously.

If monthly carbon inputs are provided directly, additional allocation columns may not be needed. These consistency checks are not enforced automatically and must be handled by the user when preparing the input file.

Value

The exported template as a data.frame.

Examples

path <- tempfile(fileext = ".csv")
export_management_template(2006, 2010, path)

initialize_soil_pools

Description

Initialize topsoil and subsoil carbon pools.

Usage

initialize_soil_pools(cn, soil_config)

Arguments

Value

A list containing initialized topsoil and subsoil pools.

Examples

s_config <- soil_config()
initialize_soil_pools(cn=15, soil_config = s_config)

management_config

Description

Prepares management configuration for monthly carbon input allocation.

Usage

management_config(
  management_filepath = NULL,
  plant_monthly_allocation = NULL,
  grain_monthly_allocation = NULL,
  grass_monthly_allocation = NULL,
  manure_monthly_allocation = NULL,
  f_man_humification = 0.12
)

Arguments

Details

This function can be used in two ways: 1. from a management template file or data.frame, such as one exported with 'export_management_template()' 2. by directly providing fixed monthly allocation vectors of length 12.

In the first approach, the user can specify monthly allocation fractions directly in the input file. When no crop rotation is considered, 'plant_monthly_allocation' should be used. When crop rotation is considered, grain and grass allocation fractions can be specified separately.

In the second approach, the user can directly provide monthly allocation vectors of length 12.

Value

A list containing management allocation settings.

Examples

management_config(
f_man_humification=0.192,
plant_monthly_allocation = c(0,0,0,.08,.12,.16,.64,0,0,0,0,0),
 manure_monthly_allocation = c(0,0,1,0,0,0,0,0,0,0,0,0)
 )

run_ctool

Description

Run C-TOOL over the full simulation period.

Usage

run_ctool(
  time_config,
  cin_config,
  m_config,
  t_config,
  s_config,
  soil_pools,
  verbose = FALSE
)

Arguments

Details

Iteratively applies 'turnover()' over all timesteps defined in 'time_config' and returns monthly carbon pool sizes, soil carbon stocks, transport fluxes and CO2 emissions.

The temperature configuration must provide monthly mean air temperature. A single historical annual temperature amplitude is calculated internally from the monthly climatology of 'Tavg' and is used in the soil temperature response function.

Value

A data.frame containing the monthly simulation output across the full simulation period.

rCTOOL scenario example dataset

Description

Example dataset used to demonstrate scenario simulations in rCTOOL.

Usage

scenario

Format

A data frame.

Source

Internal example dataset distributed with rCTOOL.

rCTOOL scenario temperature dataset

Description

Monthly temperature dataset used in rCTOOL scenario simulations.

Usage

scenario_temperature

Format

A data frame.

Source

Internal example dataset distributed with rCTOOL.

set_monthly_temperature_data

Description

Prepare monthly temperature input data for rCTOOL.

Usage

set_monthly_temperature_data(file = NULL, Tavg = NULL)

Arguments

Details

Monthly temperature data can be provided in two ways: 1. directly through the argument 'file', as a filepath or data.frame containing monthly temperature data 2. directly through the argument 'Tavg', as a numeric vector of average monthly temperature values

Value

A data.frame containing monthly temperature input data. The output always contains 'Tavg'.

Examples

df_temp <- data.frame(Tavg = c(5, 6, 7, 8, 9, 15, 14, 11, 10, 9, 5, 1))
set_monthly_temperature_data(file = df_temp)

set_monthly_temperature_data(
  Tavg = c(5, 6, 7, 8, 9, 15, 14, 11, 10, 9, 5, 1)
)

set_monthly_temperature_data_historical_amplitude

Description

Prepare monthly temperature input with a single historical amplitude.

Usage

set_monthly_temperature_data_historical_amplitude(file = NULL, Tavg = NULL)

Arguments

Details

Monthly 'Tavg' data can be provided either as a filepath/data.frame through 'file' or directly as a numeric vector through 'Tavg'.

A single historical amplitude is calculated from the full monthly 'Tavg' series as:

(max(Tavg) - min(Tavg)) / 2

This historical amplitude is then assigned to the full series in the 'Amplitude' column.

Value

A data.frame containing 'Tavg' and a single historical 'Amplitude' repeated over the full series.

Examples

set_monthly_temperature_data_historical_amplitude(
  Tavg = c(1, 2, 4, 7, 11, 15, 17, 16, 13, 9, 5, 2)
)

soil_config

Description

Prepare soil configuration parameters.

Usage

soil_config(
  Csoil_init = 70.4,
  f_hum_top = 0.48,
  f_rom_top = 0.49,
  f_hum_sub = 0.312,
  f_rom_sub = 0.6847,
  Cproptop = 0.47,
  clay_top = 0.1,
  clay_sub = 0.15,
  phi = 0.035,
  f_co2 = 0.628,
  f_romi = 0.012,
  k_fom = 0.12,
  k_hum = 0.0028,
  k_rom = 3.85e-05,
  ftr = 0.0025,
  temp_method = "rctool",
  temp_amplitude_hist = NA_real_,
  temp_offset = 0,
  temp_th_diff = 3.5e-07
)

Arguments

Details

Exports a template that can be used to provide management inputs for the model. The exported file includes monthly allocation variables and carbon input columns initialized with zeros, so they can be filled by the user before being read by the model.

Users should keep only the columns relevant to their workflow and avoid double accounting among allocation variables. For example, when 'plant_monthly_allocation' is used, grain and grass allocation columns should not be used simultaneously.

If monthly carbon inputs are provided directly, additional allocation columns may not be needed. These consistency checks are not enforced automatically and must be handled by the user when preparing the input file.

Value

A list containing soil configuration parameters.

Examples

soil_config(Csoil_init=72, f_hum_top=0.5, clay_sub = 0.35, clay_top=0.25)

soil_pool_decomposition

Description

Calculate temperature-modified decomposition of a soil carbon pool.

Usage

soil_pool_decomposition(
  soil_pool,
  k,
  soil_depth,
  month,
  t_avg,
  amplitude,
  s_config
)

Arguments

Value

Carbon change in the pool due to temperature-modified first-order decomposition.

turnover

Description

Perform one monthly turnover step of C-TOOL.

Usage

turnover(
  timestep,
  time_config,
  cin_config,
  m_config,
  t_config,
  s_config,
  out,
  amplitude_hist
)

Arguments

Details

Updates FOM, HUM and ROM pools for one monthly timestep using carbon inputs, management allocations, monthly mean air temperature, soil parameters, and the previous pool state.

Value

A data.frame containing updated monthly pool sizes, carbon stocks, transport fluxes and CO2 emissions for the current timestep.

turnover_beta

Description

Legacy monthly turnover routine retained for backward compatibility.

Usage

turnover_beta(i)

Arguments

Details

This function updates FOM, HUM and ROM pools for one monthly timestep using the historical C-TOOL workflow. It relies on objects defined in the calling environment and is retained only for backward compatibility.

Value

A one-row data.frame containing updated pool sizes, carbon stocks, transport fluxes and CO2 emissions for the current timestep.

update_monthly_FOM_sub

Description

update_monthly_FOM_sub

Usage

update_monthly_FOM_sub(
  FOM_sub_t1,
  FOM_transport,
  C_in_plant_sub,
  month,
  m_config
)

Arguments

Value

Updated FOM content in the subsoil layer after plant inputs and transport from the topsoil.

update_monthly_FOM_top

Description

update_monthly_FOM_top

Usage

update_monthly_FOM_top(FOM_top_t1, Cin_plant_top, Cin_manure, month, m_config)

Arguments

Value

Updated FOM content in the topsoil layer after monthly carbon inputs.

update_monthly_HUM_sub

Description

update_monthly_HUM_sub

Usage

update_monthly_HUM_sub(HUM_sub_t1, HUM_transport, FOM_humified_sub)

Arguments

Value

Updated HUM content in the subsoil layer after transport and humified FOM additions.

update_monthly_HUM_top

Description

update_monthly_HUM_top

Usage

update_monthly_HUM_top(HUM_top_t1, C_in_man, FOM_humified_top, month, m_config)

Arguments

Value

Updated HUM content in the topsoil layer after manure inputs and humified FOM additions.

update_monthly_ROM_sub

Description

update_monthly_ROM_sub

Usage

update_monthly_ROM_sub(ROM_sub_t1, HUM_romified_sub, ROM_transport)

Arguments

Value

Updated ROM content in the subsoil layer after romified HUM additions and transport from the topsoil.

update_monthly_ROM_top

Description

update_monthly_ROM_top

Usage

update_monthly_ROM_top(ROM_top_t1, HUM_romified_top)

Arguments

Value

Updated ROM content in the topsoil layer after romified HUM additions.