Batch run MACRO simulations with different substance properties and application patterns

Source: R/macrounchained.r

Batch run MACRO simulations with different substance properties and application patterns, starting from a template imported MACRO par-file, including metabolites.

macrounchained(s, ...)

# S3 method for data.frame
macrounchained(s, parfile, verbose = 1L,
  indump = TRUE, run = TRUE, overwrite = FALSE, analyse = NULL,
  analyse_args = NULL, analyse_summary = NULL, dt50_depth_f = NULL,
  keep0conc = TRUE, focus_mode = "no", anonymise = TRUE,
  archive = TRUE, ...)

Arguments

s

A data.frame containing different sets of substance properties and application patterns to be simulated. Each row is a substance. The order of the column has no importance, but the order of the row will steer the simulation order. Substances deriving from the same applied substance will nonetheless be simulated together. The following columns must or can be provided

  • "soil"(optional) Name of the FOCUS-scenario (soil/ site) to be used for the parameter set. Can only be used when the argument focus_mode is set to "gw". When the column "soil" is provided, the column "crop" should be provided too (see below), but the argument parfile should not be used, and neither the optional column "parfile", as the template par-file is determined internally. Partial matching and transliteration are used, and casing is ignored, and so that input like "Ch\^{a}teaudun", "chateaudun" or "chat" will all refer to the same "Ch\^{a}teaudun" FOCUS-scenario. An error will be raised in case of multiple matches or no match.

  • "crop"(optional) Name of the FOCUS-crop to be used for the parameter set. Can only be used when the argument focus_mode is set to "gw". When the column "crop" is provided, the column "soil" should be provided too (see above). Partial matching and transliteration are used, and casing is ignored. Important qualifiers such as "winter" and "spring" (for cereals and oil seed rape), or "bulb", "fruiting", "leafy" and "root" (for vegetables), should be separated from the crop name by a comma (as in MACRO In FOCUS user interface), but the can come either before or after the crop name. Spaces are otherwise ignored. Input like "Cereals, Winter", "cereals, winter", "cer, win" or even "win, cer" will all refer to the same Winter cereals FOCUS-crop. "Sugar beets" is equivalent to "sugarbeets". An error will be raised in case of multiple matches or no match.

  • "id"Integer-value, between 1 and 998. Unique identifier of the substance. Will also be used as a Run ID.

  • "name"Character-string. Name of the substance. Names don't need to be unique, but it may be a good idea if they are.

  • "kfoc"Numeric-value. [L/kg]. Freundlich adsorption coefficient of the substance.

  • "nf"Numeric-value. [-]. Freundlich exponent of the substance.

  • "dt50"Numeric-value. [days]. Half-life of the substance in soil.

  • "dt50_ref_temp"Numeric-value. [Degrees Celsius]. Reference temperature at which the half-life was measured.

  • "dt50_pf"Integer-value. [log10(cm)]. pF at which the DT50 was measured.

  • "exp_temp_resp"Numeric-value. [-]. Exponent of the temperature response (effect of temperature on degradation).

  • "exp_moist_resp"Numeric-value. [-]. Exponent of the moisture response (effect of soil water content on degradation).

  • "crop_upt_f"Numeric-value. [-]. Crop uptake factor. Between 0 (no root uptake of the substance) and 1 (passive uptake of the substance with root water uptake).

  • "diff_coef"Numeric-value. [m2/s]. Substance diffusion coefficient (in water).

  • "parent_id"Integer-value. Only for metabolites. Leave empty (NA_integer_) for substances that are not the degradation product of another substance. id of the parent substance, i.e. the substance that degrades into the metabolite described in this row. For secondary metabolites (and further), the "parent" will also be a metabolite.

  • "g_per_mol"Numeric-value. [g/mol]. Molar mass of the substance. Only needed when the substance is degrading into a degradation product or is the degradation product of another substance. Leave empty (NA_integer_) otherwise.

  • "g_as_per_ha"Numeric-value or, in case of multiple applications, character string. [g/ha]. Application rate (in g substance per hectare) of the substance. Set to 0 g/ha if the substance is a degradation product. In case of several applications per year, give the values separated with a vertical bar (see https://en.wikipedia.org/wiki/Vertical_bar). Do quote the values. For example, for two applications of 1000g/ha and 90g/ha, respectively, type "1000|900".

  • "app_j_day"Integer-value or, in case of multiple applications, character string. Between 1 and 365. [Julian day]. Application date of the substance. Use the application date of the applied substance (the top parent) if the substance is a degradation product. In case of several applications per year, give the values separated with a vertical bar (see https://en.wikipedia.org/wiki/Vertical_bar). Do quote the values. For example, for two applications on Julian days 298 and 305, respectively, type "298|305"

  • "f_int"Numeric-value. [-]. Fraction of the applied product that is intercepted by the crop canopy.

The columns "parent_id" and "g_per_mol" can be entirely skipped (missing), and should at least be only NA when no metabolite is to be simulated.
…

Additional parameters passed to specific methods. Currently not used.
parfile

A macroParFile, as imported with rmacroliteImportParFile-methods
verbose

Single integer value. If set to a value < 1, the program is silent (except on errors or warnings). If set to 1, the program outputs messages. Values > 1 may also activate messages from lower level functions (for debugging purpose).
indump

Single logical value. If TRUE (the default), the so called indump.tmp parameter file is produced. Must be TRUE when run is TRUE.
run

Single logical value. If TRUE (the default), the parametrised simulations are run.
overwrite

Single logical value. If FALSE (the default), the function will check that the files to be created do not exist yet, and will stop if some of the files already exist. Set to TRUE to silently overwrite existing files.
analyse

Single R function. Function to be used by macrounchained to analyse the results of MACRO simulations. An example of such function is macroutilsFocusGWConc. Notice that the appropriate function depends on what output needs to be analysed and what parameters are exported from MACRO, as defined in parfile, so there is no generic all purpose function to be used here. When analyse is NULL (the default), MACRO output is not analysed.
analyse_args

A list containing named-items to be passed as arguments to analyse. An example of use is analyse_args = list( "quiet" = TRUE ).
analyse_summary

Single R function. Function to be used by macrounchained to summarise all the results of MACRO simulations, as output by analyse. An example of such function is macroutilsFocusGWConc_summary. Notice that the appropriate function depends on what output needs to be summarised and what output analyse is returning, so there is no generic all purpose function to be used here.
dt50_depth_f

See rmacroliteDegradation.
keep0conc

See rmacroliteApplications.
focus_mode

See rmacroliteApplications.
anonymise

Single boolean value. If TRUE, the function tries to replace USERNAME, HOMEPATH and USERPROFILE (i.e Windows environment variables) in paths displayed in messages by their environment variables, in order to preserve the user anonymity in the logs produced.
archive

Single boolean value. If TRUE, all the files generated are archived in a .tar.gz-file when all other operations are finished. Default to FALSE.

Value

TO BE WRITTEN.