Package 'OptirrigCORE'

Description

This function adds missing parameters to a given list or data frame x by referencing parameter definitions from INI files associated with a specified type (e.g., crop, soil, irrigation, run). The function loads the appropriate INI file(s) based on the types argument and fills in any missing parameters in x with default values and types as specified in the INI files.

Usage

add_missing_params(x, types, ..., cfg = load_config())

Arguments

Details

The function searches for INI files using the per-type sources declared in cfg$ini_sources. Each source can be a package name or a directory path, and sources are searched in order. It selects the relevant INI file(s) based on the types argument and the contents of x (e.g., x$crop or x$soil). Parameter types are inferred from the INI file and used to cast values appropriately (e.g., integer, numeric, logical, date).

Value

A list with the same contents as x, but with any missing parameters added and cast to the appropriate types.

Description

Generic and method-specific functions to assign the temperature response parameter alpha based on thermal time (TT) and a threshold TTmax. For each TT value, alpha1 is used when TT <= TTmax and alpha2 otherwise. Methods are provided for numeric vectors, data.frames and matrices.

Usage

calc_alpha(x, ...)

## S3 method for class 'numeric'
calc_alpha(x, TTmax, alpha1, alpha2, TT = x, ...)

## S3 method for class 'data.frame'
calc_alpha(
  x,
  TT = x[iday, TT_name, drop = TRUE],
  TTmax,
  alpha1,
  alpha2,
  iday = seq.int(nrow(x)),
  TT_name = "TT_sowing",
  alpha_name = "alpha",
  ...
)

## S3 method for class 'matrix'
calc_alpha(
  x,
  TT = x[iday, TT_name],
  TTmax,
  alpha1,
  alpha2,
  iday = seq.int(nrow(x)),
  alpha_name = "alpha",
  TT_name = "TT_sowing",
  ...
)

Arguments

Details

The numeric method applies a simple piecewise-constant mapping: alpha1 is used when TT <= TTmax and alpha2 otherwise. Methods for matrix and data.frame inputs extract TT values from the specified column or layer, compute alpha for the selected time indices (iday), and store the result in alpha_name. If the target column or layer does not exist, it is created and initialised with NA_real_.

Value

For numeric input: a numeric vector of alpha values. For matrix/data.frame input: an object of the same class as x with a column alpha_name created or updated for the specified indices (iday).

Description

Generic function and methods to calculate biomass accumulation (B) based on photosynthetically active radiation (PAR), intercepted radiation (IR), radiation use efficiency (RUE), and stress factors. Supports various input types: numeric, matrix and data.frame.

Usage

calc_B(x = NULL, ...)

## S3 method for class ''NULL''
calc_B(x = NULL, B0, ...)

## S3 method for class 'numeric'
calc_B(
  x,
  PAR,
  IR,
  RUE,
  stress_B,
  stress_noci_B,
  iday_crop_dev = rep(1, ifelse(length(x) == 1, length(PAR), length(x))),
  B0 = x,
  ...
)

## S3 method for class 'matrix'
calc_B(
  x,
  B0,
  PAR = x[iday, PAR_name],
  IR = x[iday, IR_name],
  RUE,
  stress_B = x[iday, stress_B_name],
  stress_noci_B = x[iday, stress_noci_B_name],
  iday = seq.int(nrow(x)),
  stress_B_name = "stress_B",
  stress_noci_B_name = "stress_noci_B",
  PAR_name = "PAR",
  IR_name = "IR",
  B_name = "B",
  ...
)

## S3 method for class 'data.frame'
calc_B(
  x,
  PAR = x$PAR,
  B0,
  IR = x$IR,
  RUE = x$RUE,
  stress_B = x$stress_B,
  stress_noci_B = x$stress_noci_B,
  iday = seq.int(nrow(x)),
  B_name = "B",
  ...
)

Arguments

Details

The function computes biomass incrementally for each time step, using the formula:

$B_{i} = B0_{i} + 0.0001 \times PAR_{i} \times IR_{i} \times RUE_{i} \times (stress_{B,i})^{stress\_noci_B}$

Here PAR is expected in $J~cm^{-2}~day^{-1}$ and IR is a dimensionless intercepted fraction. The factor 0.0001 converts $J~cm^{-2}$ to $MJ~m^{-2}$ and then $g~m^{-2}$ to $t~ha^{-1}$, so B remains expressed in $t~ha^{-1}$. If i == 0, the output is set to NA.

For matrix, data.frame methods, the function iterates over time steps, updating the biomass column or array.

Value

Returns a numeric vector, matrix or data.frame with the calculated biomass values.

See Also

• calc_B_root(),

• calc_TT_sowing()

Description

Generic and method-specific functions to compute root biomass using thermal-time thresholds. The numeric method updates root biomass for a single time step. Matrix and data.frame methods apply the same rule sequentially over a time series.

Usage

calc_B_root(x = NULL, ...)

## S3 method for class 'numeric'
calc_B_root(x, B0, B_root0, TT_sowing, TT_B_root5, TT_B_root70, ...)

## S3 method for class 'matrix'
calc_B_root(
  x,
  B0,
  B_root0,
  TT_sowing = x[iday, TT_sowing_name],
  TT_B_root5,
  TT_B_root70,
  iday = seq.int(nrow(x)),
  B_name = "B",
  B_root_name = "B_root",
  TT_sowing_name = "TT_sowing",
  ...
)

## S3 method for class 'data.frame'
calc_B_root(
  x,
  B0,
  B_root0,
  TT_sowing = x[iday, TT_sowing_name],
  TT_B_root5,
  TT_B_root70,
  iday = seq.int(nrow(x)),
  B_name = "B",
  B_root_name = "B_root",
  TT_sowing_name = "TT_sowing",
  ...
)

Arguments

Details

Root biomass (B_root) is updated from total biomass (B) and thermal time since sowing (TT_sowing) using two thresholds TT_B_root5 and TT_B_root70. A piecewise linear rule controls the fraction of the biomass increment allocated to roots:

• if $TT_{sowing} < TT_{B\_root5}$: $B_{root}$ increases by 5\

• if $TT_{B\_root5} \le TT_{sowing} \le TT_{B\_root70}$: $B_{root}$ increases linearly from 5\ increment in $B$;

• if $TT_{sowing} > TT_{B\_root70}$: $B_{root}$ increases by 70\

The update rule can be written as:

$B_{root} = B_{root0} + f(TT_{sowing}) \times (B - B_{0})$

where $f(TT_{sowing})$ is the allocation fraction defined above.

For matrix and data.frame methods, B0 and B_root0 are taken from the previous time step in the series, so that root biomass is updated sequentially along the time dimension.

Value

For numeric input: a numeric scalar (B_root). For matrix/data.frame input: the object x with a column or layer named B_root_name created or updated for the selected indices (iday).

See Also

• calc_B()

• calc_TT_sowing()

Description

Generic and method-specific functions to calculate potential biomass production (Bp).

Usage

calc_Bp(x, ...)

## S3 method for class 'model_init'
calc_Bp(x, ...)

## S3 method for class 'matrix'
calc_Bp(x, ...)

Arguments

Value

Updated model_init object with potential biomass production (Bp) values.

See Also

• calc_IR()

• calc_PAR()

• calc_B()

Description

Generic function and methods to compute the root component of the biomass associated with the "Bp" pool.

Usage

calc_Bp_root(x = NULL, ...)

## S3 method for class 'matrix'
calc_Bp_root(x, TT_B_root5, TT_B_root70, ...)

Arguments

Details

The generic calc_Bp_root dispatches on the class of x. Methods call calc_B_root(...) with B_name = "Bp" and B_root_name = "Bp_root" so that the computed root variable is named "Bp_root" in the returned object.

Value

An object of the same class as x with the computed root variable ("Bp_root") added or returned according to the underlying calc_B_root behavior.

See Also

• calc_B_root()

Description

Generic and method-specific functions to calculate model water balance cases.

Usage

calc_case(x, ...)

## S3 method for class 'numeric'
calc_case(x, zES, zroot = x, ...)

## S3 method for class 'matrix'
calc_case(
  x,
  zroot = x[iday, zroot_name],
  zES,
  iday = seq.int(nrow(x)),
  zroot_name = "zroot",
  case_name = "case",
  ...
)

Arguments

Description

Generic function to calculate the Cp value, which is used in crop coefficient calculations. This function dispatches methods based on the class of the input x.

Usage

calc_Cp(x, ...)

## S3 method for class 'numeric'
calc_Cp(
  x,
  c1,
  c2,
  Kc,
  Ksol = NULL,
  iday_crop_dev = rep(1, length(x)),
  LAI = x,
  ...
)

Arguments

Details

The Cp value is calculated based on the provided parameters. For numeric inputs, the calculation uses the formula :

$Cp = c_1 - e^{-c_2 \times LAI}$

If Ksol is provided and Cp > 0 and Kc < Ksol, then Cp is adjusted as:

$Cp = \frac{Kc \times Cp}{Ksol}$

Value

Numeric value representing the Cp calculation.

See Also

• calc_Kc()

• calc_Ksol()

• calc_LAI()

Examples

calc_Cp(3, c1 = 1.2, c2 = 0.5, Kc = 0.8, Ksol = 1.0)

Description

Generic and method-specific functions to calculate root growth crac parameters.

Usage

calc_crac(x, ...)

## S3 method for class 'numeric'
calc_crac(x, ks_root, seuil, iday_crop_dev = rep(1, length(x)), taum = x, ...)

## S3 method for class 'matrix'
calc_crac(
  x,
  taum = x[iday, taum_name],
  ks_root = x[iday - 1, "ks_root"],
  seuil,
  iday = seq.int(nrow(x)),
  taum_name = "taum",
  crac_name = "crac",
  ...
)

## S3 method for class 'model_output'
calc_crac(x, crop, iday, ...)

Arguments

Details

The calc_crac function calculates the root growth "crac" parameter. Different methods handle numeric vectors, matrices, and model outputs. For numeric inputs, crac is computed as:

$crac = taum * ks\_root + seuil$

where crac is set to 0 if there is no crop development on the given day/layer (i.e., when iday_crop_dev is 0).

Value

An object of the same class as x, with the calculated "crac" values added.

See Also

• calc_ks_root()

Description

Generic and method-specific functions to calculate drainage from multiple possible inputs (gravity water reserve, water content, etc.)

Usage

calc_d(x, from = "Rgravity", ...)

calc_d_from_Rgravity(x, ...)

## S3 method for class 'numeric'
calc_d_from_Rgravity(x, Kd, Rgravity = x, ...)

## S3 method for class 'matrix'
calc_d_from_Rgravity(
  x,
  Rgravity = x[iday, Rgravity_name],
  Kd,
  iday = seq.int(nrow(x)),
  Rgravity_name = "Rgravity",
  d_name = "d",
  ...
)

Arguments

Details

Currently, only drainage calculation from gravity water reserve is implemented. Drainage is computed as the minimum between available gravity water reserve and the maximum possible outflow (hydraulic conductivity Kd in mm/h multiplied by 24 h).

Drainage values are compute by the next formula:

$d = \min(Rgravity, Kd \times 24)$

Value

An object of the same class as x with an additional column or layer for calculated drainage.

See Also

• calc_Rgravity()

Description

Generic and method-specific functions to calculate "degred" root growth calculation input.

Usage

calc_degred(x, ...)

## S3 method for class 'Date'
calc_degred(x, degred, vroot, dates = x, ...)

## S3 method for class 'matrix'
calc_degred(
  x,
  dates = x[iday, dates_name],
  degred,
  vroot,
  iday = seq.int(nrow(x)),
  dates_name = "dates",
  degred_name = "degred",
  ...
)

## S3 method for class 'model_init'
calc_degred(x, crop, dates, iday_sowing, iday_harvest, ...)

Arguments

Value

An object of the same class as x, with the calculated "degred" values added.

Description

Generic dispatcher to calculate an irrigation dose based on soil water content, soil properties (field capacity and wilting point) and a target soil moisture level. The default numeric method assumes a two-layer soil profile and uses water stored in each layer (R1, R2) and their depths (z1, z2).

Usage

calc_dose(x = NULL, ...)

## S3 method for class ''NULL''
calc_dose(x, R1, ...)

## S3 method for class 'numeric'
calc_dose(
  x,
  R1 = x,
  R2,
  z1,
  z2,
  theta_fc,
  theta_wp,
  RU_target = NA,
  RU_units = 2,
  THETA_target = NA,
  ...
)

Arguments

Details

The numeric method converts water stored in the two soil layers (R1, R2, in mm) and their depths (z1, z2, in m) into an average volumetric soil water content over the total depth (Hz = z1 + z2). Readily available water (RU) and its maximum (RUmax) are computed relative to the wilting point and field capacity.

The target can be specified either as a volumetric soil moisture (THETA_target) or as a target readily available water (RU_target), but not both at the same time. If both are provided, the function throws an error. If neither is provided, a dose of 0 is returned.

When RU_target is given in mm (RU_units = 1), it is clamped to the range ⁠[0, RUmax]⁠. When RU_units = 2, RU_target is interpreted as a fraction or percent of RUmax (values in ⁠[0,1]⁠ or ⁠[0,100]⁠ are accepted and normalized to ⁠[0,1]⁠).

The computed dose is the water depth (mm) required to raise the current soil moisture to the target, limited by optional minimum and maximum dose constraints (dose_min, dose_max) and never negative.

Value

A numeric value representing the irrigation dose (mm), as determined by the method for the class of x.

See Also

• calc_theta_fc()

• calc_theta_wp()

• calc_RU()

Description

Generic and method-specific functions to calculate a relative soil moisture term (dtheta_RU) based on volumetric water content (theta), field capacity (theta_fc) and wilting point (theta_wp). In the numeric method, dtheta_RU is the amount by which theta exceeds field capacity, capped by the total range between field capacity and wilting point.

Usage

calc_dtheta_RU(x, ...)

## S3 method for class 'numeric'
calc_dtheta_RU(x, theta_fc, theta_wp, theta = x, ...)

## S3 method for class 'matrix'
calc_dtheta_RU(
  x,
  theta = x[iday, theta_name],
  theta_fc,
  theta_wp,
  iday = seq.int(nrow(x)),
  theta_name = "theta",
  dtheta_RU_name = "dtheta_RU",
  ...
)

Arguments

Details

The numeric implementation computes:

$d\theta_{RU} = \max\left( \min\left(\theta - \theta_{FC}, \theta_{FC} - \theta_{WP}\right), 0 \right)$

i.e. the excess water content above field capacity, limited to the maximum available water between field capacity and wilting point and not allowed to be negative.

If you instead want the classical available water between wilting point and field capacity, you can replace the core formula with:

$\max\left( \min\left(\theta - \theta_{WP}, \theta_{FC} - \theta_{WP}\right), 0 \right)$

Value

For numeric input: a numeric vector of dtheta_RU values. For matrix input: a matrix with a column dtheta_RU_name created or updated for the specified indices (iday).

See Also

• calc_RU()

• calc_dtheta_RU_WP()

• calc_theta()

Description

Generic and method-specific functions to calculate the increment in root depth (dzroot) for a given time step, based on crop state and empirical parameters. Typically used in crop growth models to simulate root development over time.

Usage

calc_dzroot(x, ...)

## S3 method for class 'numeric'
calc_dzroot(
  x,
  dcrac,
  dzrootp,
  iday_crop_dev = rep(1, length(x)),
  taum = x,
  ...
)

## S3 method for class 'matrix'
calc_dzroot(
  x,
  taum = x[iday, "taum"],
  dcrac = x[iday, "dcrac"],
  dzrootp = x[iday, "dzrootp"],
  iday = seq.int(nrow(x)),
  dzroot_name = "dzroot",
  ...
)

## S3 method for class 'model_output'
calc_dzroot(x, crop, iday, ...)

Arguments

Details

The numeric method applies a simple rule to each time step:

• if iday_crop_dev[i] == 0, no root growth is computed and NA_real_ is returned for that step;

• if taum[i] <= 0.25, the root depth increment is taken as dcrac[i];

• otherwise, the increment is limited by the potential value dzrootp[i] and never exceeds dcrac[i].

In practice, this is implemented as a piecewise expression using taum, dcrac and dzrootp, with the result returned as a numeric vector. Matrix and model_output methods wrap this numeric logic and write dzroot into the appropriate column or layer.

Value

For numeric input: a numeric vector of dzroot values. For matrix and model_output input: an object of the same class as x with a column or layer named dzroot_name (default "dzroot") created or updated for the specified indices.

See Also

• calc_taum()

• calc_crac()

• calc_dzrootp()

Description

Generic and method-specific functions to compute the change in root depth (dzrootp) for different input types. The generic dispatcher selects a method based on the class of x.

Usage

calc_dzrootp(x, ...)

## S3 method for class 'numeric'
calc_dzrootp(x, zrootp_init, zrootp = x, ...)

## S3 method for class 'matrix'
calc_dzrootp(
  x,
  zrootp = x[iday, "zrootp"],
  zrootp_init,
  iday = seq.int(nrow(x)),
  dzrootp_name = "dzrootp",
  ...
)

Arguments

Details

Methods:

• numeric: computes dzrootp as the simple difference zrootp - zrootp_init.

• matrix: computes dzrootp row-wise for the indices iday, ensuring that a column named dzrootp_name exists (it is created if missing). When zrootp_init is a single value, it is treated as the root depth at the previous time step and expanded to a lagged vector using c(zrootp_init, zrootp[-length(zrootp)]).

This helper is typically used in root growth routines to express root extension as a per-step increment rather than an absolute depth.

Value

For numeric input: a numeric value (or vector) of dzrootp. For matrix input: the matrix x with a column dzrootp_name created or updated for the selected indices iday.

See Also

• calc_taum()

• calc_crac()

• calc_dzroot()

Examples

calc_dzrootp(5, zrootp_init = 2)

mat <- matrix(c(1, 2, 3, 4), ncol = 2)
colnames(mat) <- c("zrootp", "other")
calc_dzrootp(mat, zrootp_init = 1)

Description

Generic S3 interface to compute soil evaporation (ES). This function dispatches to class-specific implementations (for example calc_ES.numeric) that perform the actual calculation.

Usage

calc_ES(x, ...)

## S3 method for class 'numeric'
calc_ES(x, ES0, KES, Rmin = NULL, R = x, ...)

## S3 method for class 'matrix'
calc_ES(
  x,
  R = x[iday, R_name],
  ES0 = x[iday, ES0_name],
  KES = x[iday, KES_name],
  Rmin = x[iday, Rmin_name],
  iday = seq.int(nrow(x)),
  R_name = "R",
  ES0_name = "ES0",
  KES_name = "KES",
  Rmin_name = "Rmin",
  ES_name = "ES",
  ...
)

Arguments

Details

For numeric input, soil evaporation is computed as:

$ES = \min\left(R, ES0 \times KES\right)$

i.e. evaporation cannot exceed either the potential rate (ES0 * KES) or the available water R. When a residual Rmin is provided, the result is adjusted so that:

$R - ES \ge Rmin$

for each element, i.e. evaporation is reduced where necessary so as not to deplete soil water below Rmin. Matrix input methods extract the required columns by name for the selected rows (iday) and write the result to a column named ES_name, which is created if missing.

Value

For numeric input: a numeric vector of soil evaporation values (ES, $mm~day^{-1}$). For matrix input: the matrix x with a column ES_name created or updated for the selected rows.

Description

Generic and method-specific functions to calculate potential soil evaporation (ES0), representing the atmospheric demand for evaporation from the soil surface given reference evapotranspiration and partitioning coefficients.

Usage

calc_ES0(x, ...)

## S3 method for class 'numeric'
calc_ES0(x, Kc, Cp, Ksol, ET0 = x, ...)

## S3 method for class 'matrix'
calc_ES0(
  x,
  ET0 = x[iday, ET0_name],
  Kc = x[iday, Kc_name],
  Cp = x[iday, Cp_name],
  Ksol,
  iday = seq.int(nrow(x)),
  ET0_name = "ET0",
  Kc_name = "Kc",
  Cp_name = "Cp",
  ES0_name = "ES0",
  ...
)

Arguments

Details

The numeric implementation computes potential soil evaporation as:

$ES0_{i} = ET0_{i} \times \max(K_{c,i}, K_{sol}) \times \left(1 - \max(C_{p,i}, 0)\right)$

i.e. the reference evapotranspiration is scaled by the larger of the crop and soil coefficients, and then reduced by the fraction attributed to the canopy (Cp, truncated at 0). The result is a potential soil evaporation rate expressed in $mm~day^{-1}$.

For matrix inputs, ET0, Kc and Cp are read from the specified columns for rows indexed by iday, and ES0 is written to the column named ES0_name, which is created if it does not exist.

Value

For numeric input: a numeric vector of potential soil evaporation (ES0, $mm~day^{-1}$). For matrix input: an object of the same class as x with a column ES0_name created or updated where applicable.

See Also

• calc_ES()

Description

Generic and method-specific functions to calculate reference evapotranspiration (ET0) from potential evapotranspiration (ETP) using a specified ratio. Methods are provided for numeric vectors and matrices.

Usage

calc_ET0(x, ...)

## S3 method for class 'numeric'
calc_ET0(x, ratio_ET0_ETP, ETP = x, ...)

## S3 method for class 'matrix'
calc_ET0(
  x,
  ETP = x[iday, "ETP"],
  ratio_ET0_ETP = 1,
  iday = seq.int(nrow(x)),
  ET0_name = "ET0",
  ...
)

Arguments

Details

For numeric and matrix inputs, the function applies a simple scaling:

$ET0 = ratio\_{ET0/ETP} \times ETP$

For matrices, ETP is taken from the column named "ETP" by default, and the result is written to a column named ET0_name, which is created if missing.

For model_init objects, the ratio ratio_ET0_ETP is first computed via calc_ET0_mulch_effect using soil and irrigation parameters (e.g. mulch and irrigation method), then the appropriate next method is called to perform the actual ET0 computation.

Value

For numeric input: a numeric vector of ET0 values ($mm~day^{-1}$). For matrix input: a matrix with an added or updated ET0 column. For model_init input: a model_init object with ET0 calculated.

Examples

# Numeric method
etp <- c(2.1, 2.5, 2.3)
calc_ET0(etp, ratio_ET0_ETP = 0.95)

# Matrix method
m <- matrix(c(1:6, rep(NA, 3)), ncol = 3)
colnames(m) <- c("ETP", "foo", "bar")
calc_ET0(m, ratio_ET0_ETP = 1.0, ET0_name = "ET0")

Description

Generic S3 function to compute a multiplicative factor representing the effect of mulch on reference evapotranspiration (ET0). The returned value is intended to multiply ET0 to account for mulch presence or specific simulation conditions.

Usage

calc_ET0_mulch_effect(x = NULL, ...)

## S3 method for class ''NULL''
calc_ET0_mulch_effect(x = NULL, mulch, ...)

## S3 method for class 'numeric'
calc_ET0_mulch_effect(x, gge, mulch = x, ...)

Arguments

Details

The numeric method returns a scalar multiplicative factor for ET0 based on gge and mulch:

• if gge == 999 and mulch == 1000, a fixed factor 0.1 is returned (special GGS simulation case);

• if gge == 1, a proportional reduction is used:

  $f = \frac{1}{1 + 0.1 \times mulch / 1000}$

• if gge == 0, mulch has no effect and the factor is 1.

Any other value of gge triggers an error. This function is intended to be applied at the time-step level; both gge and mulch are treated as scalar values.

Value

A numeric scalar representing the multiplicative factor to apply to ET0 to account for mulch effects.

seealso:

• calc_ET0()

Examples

# Using mulch as an explicit argument
calc_ET0_mulch_effect(5, gge = 1, mulch = 50)

# Using x as mulch when mulch is omitted
calc_ET0_mulch_effect(50, gge = 1)

Description

Generic and method-specific functions to calculate maximum evapotranspiration (ETM), representing the crop water demand as the sum of soil evaporation (ES0) and potential transpiration (TP0).

Usage

calc_ETM(x = NULL, ...)

## S3 method for class ''NULL''
calc_ETM(x, ES0, ...)

## S3 method for class 'numeric'
calc_ETM(x = NULL, TP0, ES0 = x, ...)

## S3 method for class 'matrix'
calc_ETM(
  x,
  ES0 = x[iday, ES0_name],
  TP0 = x[iday, TP0_name],
  iday = seq.int(nrow(x)),
  ES0_name = "ES0",
  TP0_name = "TP0",
  ETM_name = "ETM",
  ...
)

Arguments

Details

The calc_ETM function is a generic S3 interface with methods for different input types:

• NULL: delegates to the next method using the ES0 argument as input;

• numeric: computes ETM as the sum $ES_{0,i} + TP_{0,i}$;

• matrix: ensures an ETM column exists, then fills it for the selected rows as $ES_{0,i} + TP_{0,i}$.

In all cases, ETM_{i} is expressed in $mm~day^{-1}$, consistent with ES0_{i} and TP0_{i}.

Value

For numeric input: a numeric vector of ETM values ($mm~day^{-1}$). For matrix input: the matrix x with a column ETM_name created or updated. For NULL input: dispatches to the numeric method using ES0.

See Also

• calc_ET0()

• calc_TP0()

Examples

# Numeric example
calc_ETM(ES0 = 2, TP0 = 1)

# Matrix example
mat <- matrix(c(2, 1, 3, 2), ncol = 2)
colnames(mat) <- c("ES0", "TP0")
calc_ETM(mat)

Description

Generic and method-specific functions to calculate actual evapotranspiration (ETR) as the sum of soil evaporation (ES) and crop transpiration (TP).

Usage

calc_ETR(x, ...)

## S3 method for class 'numeric'
calc_ETR(x, TP, ES = x, ...)

## S3 method for class 'matrix'
calc_ETR(
  x,
  ES = x[iday, ES_name],
  TP = x[iday, TP_name],
  iday = seq.int(nrow(x)),
  ES_name = "ES",
  TP_name = "TP",
  ETR_name = "ETR",
  ...
)

Arguments

Details

The numeric implementation combines soil evaporation and crop transpiration as:

$ETR_{i} = ES_{i} + \max(TP_{i}, 0)$

i.e. negative transpiration values, if present, are treated as zero. For matrix inputs, ES and TP are read from the specified columns for rows indexed by iday, and ETR is written to a column named ETR_name, which is created if missing.

All fluxes are assumed to be expressed in $mm~day^{-1}$ and consistent across ES, TP and ETR.

Value

For numeric input: a numeric vector of actual evapotranspiration (ETR, $mm~day^{-1}$). For matrix input: the matrix x with a column ETR_name created or updated.

See Also

• calc_ES()

• calc_TP()

Description

Generic and method-specific functions to calculate harvest index (HI), defined as the ratio between harvested (economic) yield and total above-ground biomass.

Usage

calc_HI(x, ...)

## S3 method for class 'numeric'
calc_HI(x, Bp, HIp, iday_crop_dev = rep(1, length(x)), B = x, ...)

## S3 method for class 'matrix'
calc_HI(
  x,
  B = x[iday, B_name],
  Bp = x[iday, Bp_name],
  HIp = x[iday, HIp_name],
  iday = seq.int(nrow(x)),
  B_name = "B",
  Bp_name = "Bp",
  HIp_name = "HIp",
  HI_name = "HI",
  ...
)

Arguments

Details

The numeric method computes harvest index for each time step or element where the crop is in development:

$HI_{i} = HIp_{i} \times \frac{B_{i}}{Bp_{i}}$

where $HIp_{i}$ is either a scalar potential harvest index or a time-varying value. For elements where iday_crop_dev[i] == 0, NA_real_ is returned.

Matrix methods extract biomass and potential biomass (and HIp) from the specified columns for rows indexed by iday, compute the corresponding harvest index values using the numeric method, and store them in a column named HI_name, which is created if it does not exist.

Value

For numeric input: a numeric vector of harvest index values. For matrix input: the matrix x with a column HI_name created or updated.

See Also

• calc_Bp()

Examples

# Numeric example
calc_HI(1:100, Bp = seq(1, 200, 2), HIp = 1)

# Matrix example
calc_HI(cbind(B = 1:100, Bp = seq(1, 200, 2), HIp = 1))

Description

Generic and method-specific functions to calculate the fraction of intercepted radiation (IR) based on leaf area index (LAI) and the Beer-Lambert extinction coefficient (k_BL).

Usage

calc_IR(x = NULL, ...)

## S3 method for class ''NULL''
calc_IR(x, LAI, ...)

## S3 method for class 'numeric'
calc_IR(x, k_BL, iday_crop_dev = rep(1, length(x)), LAI = x, ...)

## S3 method for class 'matrix'
calc_IR(
  x,
  LAI = x[iday, LAI_name],
  iday = seq.int(nrow(x)),
  k_BL,
  LAI_name = "LAI",
  IR_name = "IR",
  ...
)

Arguments

Details

The intercepted fraction is computed from the Beer-Lambert law as:

$IR_{i} = 1 - \exp(-k_{BL} \cdot LAI_{i})$

For the numeric method, this expression is applied element-wise. For indices where iday_crop_dev[i] == 0, the result is set to NA_real_ to indicate no crop development.

Matrix methods extract LAI values for the rows or time indices specified by iday, compute intercepted radiation using the numeric method, and store the results in a column or layer named IR_name, which is created if it does not exist.

Value

For numeric input: a numeric vector of intercepted radiation values (dimensionless, between 0 and 1). For matrix input: the object x with a column variable named IR_name created or updated.

See Also

• calc_LAI()

Examples

# Numeric usage
LAI <- c(0.5, 1.5, 3.0)
k <- 0.5
calc_IR(LAI, k_BL = k)

# Matrix usage
mat <- matrix(c(0.5, 1.5, 3.0), ncol = 1)
colnames(mat) <- "LAI"
calc_IR(mat, k_BL = k)

Description

Generic and method-specific functions to calculate the crop coefficient (Kc) using leaf area index (LAI), a maximum crop coefficient (Kc_max) and an extinction coefficient (k). Methods are provided for numeric vectors and matrices.

Usage

calc_Kc(x, ...)

## S3 method for class 'numeric'
calc_Kc(x, Kc_max, k, iday_crop_dev = rep(1, length(x)), LAI = x, ...)

## S3 method for class 'matrix'
calc_Kc(x, LAI = x[iday, "LAI"], Kc_max, k, iday = seq.int(nrow(x)), ...)

Arguments

Details

For the numeric method, the crop coefficient is computed for each element as:

$K_{c,i} = K_{c\_max} \times \left(1 - \exp(-k \cdot LAI_{i})\right)$

for time steps where iday_crop_dev[i] == 1. For indices where iday_crop_dev[i] == 0, the crop is considered not developed and K_{c,i} is set to 0.

For the matrix method, LAI values are extracted from the rows specified by iday, converted to a numeric vector, and passed to the numeric method. The result is returned as a numeric vector of K_{c} values aligned with the rows of the input matrix (with NA_real_ for rows not in iday).

Value

For numeric input: a numeric vector of crop coefficient values . For matrix input: a numeric vector of Kc values aligned with the rows of x.

Examples

# Numeric vector example
calc_Kc(c(1, 2, 3), Kc_max = 1.2, k = 0.5)

# Matrix example (returns a vector of Kc values)
mat <- cbind(LAI = c(1, 2, 3))
calc_Kc(mat, Kc_max = 1.2, k = 0.5)

Description

Generic interface to compute hydraulic conductivity (Kd) for a given soil water content (theta) using different empirical methods. The default method "saxton" implements the Saxton-Rawls formulation.

Usage

calc_Kd(x, from = "saxton", ...)

calc_Kd_from_saxton(x, ...)

## S3 method for class 'numeric'
calc_Kd_from_saxton(x, Ks, theta_fc, theta_wp, theta_sat, ...)

## S3 method for class 'matrix'
calc_Kd_from_saxton(x, Ks, theta_fc, theta_wp, theta_sat, ...)

Arguments

Details

The Saxton-Rawls method (from = "saxton") estimates hydraulic conductivity as a function of soil water content and soil hydraulic properties. It uses a Campbell-type relationship:

$B_{Campbell} = \frac{\log(1500) - \log(33)} {\log(\theta_{fc}) - \log(\theta_{wp})}$

$s = \max\left( \min\left(\frac{\theta_{i}}{\max(\theta_{sat}, 10^{-9})}, 1\right), 0 \right)$

$e = 3 + 2 B_{Campbell}$

$K_{d,i} = \max(K_s, 10^{-9}) \times s^{e}$

where:

• $\theta_{i}$: current volumetric water content (x);

• $K_s$: saturated hydraulic conductivity;

• $\theta_{fc}$: water content at field capacity;

• $\theta_{wp}$: water content at permanent wilting point;

• $\theta_{sat}$: water content at saturation.

For matrix input, the Saxton method is applied element-wise and the result has the same dimensions as x. Parameters Ks, theta_fc, theta_wp and theta_sat may be scalars or arrays conformable with x.

Reference: Saxton, K.E., and Rawls, W.J. (2006). Soil water characteristic estimates by texture and organic matter. Soil Science Society of America Journal, 70, 1569-1578.

Value

For numeric input: a numeric vector of hydraulic conductivity values (Kd, same units as Ks). For matrix input: a numeric matrix of Kd values with the same dimensions as x.

See Also

• calc_theta_fc()

• calc_theta_wp()

• calc_theta_sat()

Examples

# Example for numeric input
calc_Kd(
  0.25,
  Ks = 0.1,
  theta_fc = 0.3,
  theta_wp = 0.1,
  theta_sat = 0.4
)

Description

Generic and method-specific functions to calculate the soil evaporation coefficient (KES) from soil water content. KES is a simple switch-like coefficient that indicates whether soil moisture is above a residual threshold.

Usage

calc_KES(x, ...)

## S3 method for class 'numeric'
calc_KES(x, theta_r, theta = x, ...)

## S3 method for class 'matrix'
calc_KES(
  x,
  theta = x[iday, theta_name],
  theta_r,
  iday = seq.int(nrow(x)),
  theta_name = "theta",
  KES_name = "KES",
  ...
)

Arguments

Details

For numeric input, KES is computed element-wise as:

$KES_i = \begin{cases} 1 & \text{if } \theta_i > \theta_{r,i} \\ 0 & \text{otherwise} \end{cases}$

where $\theta_{r,i}$ is either a scalar residual water content or a value specific to each element when theta_r has the same length as theta.

For matrix input, soil water content is taken from the column named theta_name for the rows specified by iday. The computed KES values are stored in a column named KES_name, which is created if it does not exist.

Value

For numeric input: a numeric vector of KES values (0 or 1). For matrix input: the matrix x with a column KES_name created or updated for the selected rows.

See Also

• calc_theta_r()

• calc_Kd()

Description

Generic interface and method-specific functions to estimate saturated hydraulic conductivity ($mm~h^{-1}$) from soil texture (percent sand and percent clay) using different empirical models.

Usage

calc_Ks(x, from = "saxton", ...)

calc_Ks_from_saxton(x, ...)

## S3 method for class 'numeric'
calc_Ks_from_saxton(
  x,
  psand,
  pclay = x,
  ref = data.frame(names = c("C", "CL", "L", "LSa", "Sa", "SaC", "SaCL", "SaL", "SiL",
    "SiC", "SiCL"), psand = c(25, 30, 40, 80, 88, 50, 60, 65, 20, 10, 10), pclay = c(50,
    35, 20, 5, 5, 40, 25, 10, 15, 45, 35), Ks_Saxton_mm_h = c(1.1, 4.3, 15.5, 96.7,
    108.1, 1.4, 11.3, 50.3, 16.1, 3.7, 5.7), stringsAsFactors = FALSE),
  ...
)

calc_Ks_from_cosby(x, ...)

## S3 method for class 'numeric'
calc_Ks_from_cosby(x, psand, pclay = x, ...)

calc_Ks_from_ottoni(x, ...)

## S3 method for class 'numeric'
calc_Ks_from_ottoni(x, psand, pclay = x, ...)

Arguments

Details

The main function calc_Ks() dispatches to the appropriate method based on the from argument:

Saxton method

Matches the input texture to the closest reference class using Euclidean distance in the (sand, clay) space and returns the corresponding Ks value. Based on Saxton and Rawls (2006).

Cosby method

Uses an empirical formula based on percent sand and clay (Cosby et al., 1984).

Ottoni method

Uses an empirical formula based on percent sand and clay, with silt estimated as $100 - (sand + clay)$ (Ottoni et al., 2019).

All methods return Ks in $mm~h^{-1}$. For the Saxton method, a small reference table of texture classes and associated Ks values is used by default, but can be overridden via the ref argument.

References:

• Saxton, K.E., and Rawls, W.J. (2006). Soil water characteristic estimates by texture and organic matter. SSSAJ 70, 1569-1578.

• Cosby, B.J. et al. (1984). A statistical exploration of the relationships of soil moisture characteristics to the physical properties of soils. Water Resour. Res. 20(6), 682-690.

• Ottoni, M.V. et al. (2019). Pedotransfer functions for saturated hydraulic conductivity. Journal of Hydrology 575, 1214-1223.

Value

A numeric vector of estimated saturated hydraulic conductivity values (Ks, $mm~h^{-1}$), with one value per input texture.

Examples

calc_Ks(20, psand = 40, pclay = 20, from = "saxton")
calc_Ks(20, psand = 40, pclay = 20, from = "cosby")
calc_Ks(20, psand = 40, pclay = 20, from = "ottoni")

Description

Generic and method-specific functions to calculate root growth ks_root parameters.

Usage

calc_ks_root(x, ...)

## S3 method for class 'numeric'
calc_ks_root(
  x,
  ks_init,
  theta_raw,
  iday_crop_dev = rep(1, length(x)),
  theta = x,
  ...
)

## S3 method for class 'matrix'
calc_ks_root(
  x,
  theta = x[iday, "theta"],
  ks_init = NULL,
  iday_crop_dev = x[iday, "iday_crop_dev"],
  theta_raw,
  iday = seq.int(nrow(x)),
  ks_name = "ks_root",
  ...
)

Arguments

Value

An object of the same class as x, with the calculated "ks_root" values added.

Description

Generic and method-specific functions to calculate the transpiration reduction coefficient (KTP) from soil water content. KTP ranges between 0 and 1 and scales potential transpiration according to water availability between wilting point and readily available water.

Usage

calc_KTP(x, ...)

## S3 method for class 'numeric'
calc_KTP(x, theta_wp, theta_raw, theta = x, ...)

## S3 method for class 'matrix'
calc_KTP(
  x,
  theta = x[iday, theta_name],
  theta_wp,
  theta_raw,
  iday = seq.int(nrow(x)),
  theta_name = "theta",
  KTP_name = "KTP",
  ...
)

Arguments

Details

For numeric input, KTP is computed element-wise from theta as:

• if $\theta > \theta_{raw}$: $KTP = 1$ (no stress, full transpiration);

• if $\theta_{wp} < \theta \le \theta_{raw}$: $KTP$ decreases linearly from 1 to 0:

  $KTP = \frac{\theta - \theta_{wp}} {\theta_{raw} - \theta_{wp}}$

• if $\theta \le \theta_{wp}$: $KTP = 0$ (no transpiration).

For matrix input, soil water content is taken from the column named theta_name for rows specified by iday. The calculated KTP values are stored in a column named KTP_name, which is created if it does not exist.

Value

For numeric input: a numeric vector of KTP values in ⁠[0, 1]⁠. For matrix input: the matrix x with a column KTP_name created or updated for the selected rows.

See Also

• calc_theta_wp()

• calc_theta()

Examples

# Numeric example
theta <- c(0.08, 0.12, 0.18)
calc_KTP(theta, theta_wp = 0.1, theta_raw = 0.16)

# Matrix example
mat <- cbind(theta = c(0.08, 0.12, 0.18))
calc_KTP(mat, theta_wp = 0.1, theta_raw = 0.16)

Description

Generic function and methods to calculate leaf area index (LAI) from potential LAI (LAIp), its initial value (LAIp_init) and stress factors affecting leaf growth or senescence.

Usage

calc_LAI(x = NULL, ...)

## S3 method for class ''NULL''
calc_LAI(x = NULL, LAI0, ...)

## S3 method for class 'numeric'
calc_LAI(
  x,
  LAIp,
  LAIp_init,
  stress_LAI,
  stress_noci_LAI,
  LAImin = NA_real_,
  k = NA_real_,
  iday_crop_dev = rep(1, length(LAIp)),
  LAI0 = x,
  ...
)

## S3 method for class 'data.frame'
calc_LAI(
  x,
  LAI0 = NULL,
  LAIp = x$LAIp[iday],
  stress_LAI = x$stress_LAI[iday],
  stress_noci_LAI = x$stress_noci_LAI[iday],
  LAImin = NA_real_,
  k = NA_real_,
  iday = seq.int(nrow(x)),
  LAI_name = "LAI",
  ...
)

## S3 method for class 'matrix'
calc_LAI(
  x,
  LAI0 = ifelse(iday[1] == 1, 0, x[iday - 1, LAI_name]),
  LAIp = x[iday, LAIp_name],
  LAIp_init = ifelse(iday == 1, 0, x[iday - 1, LAIp_name]),
  stress_LAI = x[iday, "stress_LAI"],
  stress_noci_LAI = x[iday, "stress_noci_LAI"],
  LAImin = NA_real_,
  k = NA_real_,
  iday = seq.int(nrow(x)),
  LAIp_name = "LAIp",
  LAI_name = "LAI",
  ...
)

Arguments

Details

The numeric method updates LAI based on changes in potential LAI and a stress-modified increment. Let:

$\Delta LAI_i = LAIp_i - LAIp_{init,i}$

For each time step $i$, the increment is scaled by a stress factor:

$stress_{LAI,i} = \begin{cases} stress_{LAI,i} & \text{Growth Phase} \\ 2 - stress_{LAI,i} & \text{Senescence Phase (when } \Delta LAI_i < 0\text{)} \end{cases}$

and:

$LAI_i = LAI0_{i} + \Delta LAI_i \, stress_{LAI,i}^{stress\_noci_{LAI}}$

When both LAImin and k are provided and $\Delta LAI_i < 0$, the senescence step is damped by limiting the daily loss to:

$dLAI_i = k_i (LAI0_i - LAImin_i)$

and the retained LAI becomes:

$LAI_i = \max\left(LAI_i,\; LAI0_i - dLAI_i,\; LAImin_i\right)$

so that LAI tends progressively towards LAImin instead of dropping too quickly towards zero.

When LAI0 is a single scalar, the method maintains an internal cumulative value LAI0 across time:

• LAI0 is initialised to the scalar LAI0 (or 0 if LAI0 is NA);

• for each time step, LAI0 is updated by the scaled increment and stored as LAI[i];

• when i == 0, LAI[i] is NA_real_ and the internal LAI0 value is left unchanged.

When LAI0 is a vector, each time step is computed independently using the corresponding LAI0[i] (or 0 if NA).

For data.frame and matrix inputs, LAI is written to a column named LAI_name. For data.frame, LAI0 is taken from the argument for the first row and then from the previous row's LAI for subsequent rows. For matrix, a similar logic is applied using LAIp_name and LAI_name.

Value

For numeric input: a numeric vector of LAI values ($m^{2}~m^{-2}$). For data.frame and matrix input: the object x with a column LAI_name created or updated.

See Also

• calc_stress()

• calc_stress_noci_LAI()

• calc_LT()

• calc_LAIp()

Examples

# Numeric example
calc_LAI(
  1,
  LAIp = 2,
  LAIp_init = 1,
  stress_LAI = 0.8,
  stress_noci_LAI = 1,
  LAImin = 0.5,
  k = 0.05
)

# Data frame example
df <- data.frame(
  LAIp = c(1, 2, 3),
  stress_LAI = 0.8,
  stress_noci_LAI = 1
)
calc_LAI(df)

# Matrix example
mat <- as.matrix(
  data.frame(
    LAIp = c(1, 2, 3),
    stress_LAI = 0.8,
    stress_noci_LAI = 1
  )
)
calc_LAI(mat)

Description

Generic function and methods to calculate potential leaf area index (LAIp) from a normalized/logistic temperature index (LT), maximum LAI (LAImax) and an initial LAI (LAI0). Implemented for numeric vectors, matrices, data.frames and model initialisation objects.

Usage

calc_LAIp(x = NULL, ...)

## S3 method for class ''NULL''
calc_LAIp(x, LT, ...)

## S3 method for class 'numeric'
calc_LAIp(x, LAImax, LAI0, LT = x, ...)

## S3 method for class 'matrix'
calc_LAIp(
  x,
  LT = x[iday, LT_name],
  LAImax,
  LAI0,
  iday = seq.int(nrow(x)),
  LT_name = "LT",
  LAIp_name = "LAIp",
  ...
)

## S3 method for class 'data.frame'
calc_LAIp(
  x,
  LT = x[iday, LT_name, drop = TRUE],
  LAImax = x$LAImax,
  LAI0 = x$LAI0,
  iday = seq.int(nrow(x)),
  LT_name = "LT",
  LAIp_name = "LAIp",
  ...
)

## S3 method for class 'model_init'
calc_LAIp(x, crop, iday_sowing, iday_harvest, ...)

Arguments

Details

The numeric method computes potential LAI at each time step by a simple linear interpolation between LAI0 and LAImax using LT (⁠[0, 1]⁠):

$LAIp_{i} = LAI0_{i} + (LAImax_{i} - LAI0_{i}) \cdot LT_{i}$

with checks enforcing:

• $0 \le LT \le 1$,

• $LAI0 \ge 0$,

• $LAImax \ge LAI0$.

For matrix and data.frame inputs, LT values are read from the specified column (LT_name) and LAIp is written to a column named LAIp_name, which is created if missing.

The model_init method typically computes a normalized thermal time and an LT-like index using helper functions (e.g. calc_TT_norm(), calc_alpha(), calc_LT()), then delegates to the appropriate calc_LAIp method (usually the data.frame or matrix method) to fill LAIp between sowing and harvest.

Value

A numeric vector, matrix, data.frame or model_init object (same type as x) with a potential LAI field (LAIp) computed or updated.

See Also

• calc_LT()

• calc_LAI()

• calc_TT_norm()

Examples

# Numeric example
calc_LAIp(0.5, LAImax = 6, LAI0 = 0.1)

Description

Generic function and methods to calculate a logistic temperature index (LT) from a normalised thermal-time variable (TT_norm) and shape parameters alpha and beta.

Usage

calc_LT(x, ...)

## S3 method for class 'numeric'
calc_LT(x, alpha, beta, TTnorm_LTsat, TT_norm = x, ...)

## S3 method for class 'data.frame'
calc_LT(
  x,
  TT_norm = x[iday, TT_norm_name, drop = TRUE],
  alpha = x[iday, alpha_name, drop = TRUE],
  beta,
  TTnorm_LTsat,
  iday = seq.int(nrow(x)),
  TT_norm_name = "TT_norm",
  alpha_name = "alpha",
  LT_name = "LT",
  ...
)

## S3 method for class 'matrix'
calc_LT(
  x,
  TT_norm = x[iday, TT_norm_name],
  alpha = x[iday, alpha_name],
  beta,
  TTnorm_LTsat,
  iday = seq.int(nrow(x)),
  TT_norm_name = "TT_norm",
  alpha_name = "alpha",
  LT_name = "LT",
  ...
)

Arguments

Details

The numeric method computes LT element-wise from TT_norm, alpha, and beta using:

$LT_{i} = \mathrm{TT_{norm}}_{i}^{\beta} \exp\!\left[ \frac{\beta}{\alpha_{i}} \left( 1 - \mathrm{TT_{norm}}_{i}^{\alpha_{i}} \right) \right]$

where the parameter $\alpha_i$ depends on crop phenological phase:

$\alpha_i = \begin{cases} \alpha_{1}, & \text{Growth phase} \\[6pt] \alpha_{2}, & \text{Senescence phase} \end{cases}$

For data.frame and matrix inputs, TT_norm and alpha are read from the specified columns for the rows indexed by iday. The result is written to a column named LT_name, which is created if missing.

Value

For numeric input: a numeric vector of logistic temperature index values. For data.frame and matrix input: the object x with a column LT_name created or updated.

Examples

# Numeric example
calc_LT(
  seq(0, 1, length.out = 5),
  alpha = 2,
  beta = 3,
  TTnorm_LTsat = 1
)

Description