Manipulating STICS text files

Overview

This package allows the user to programmatically manipulate either the XML files used to store more information, or the text files directly used as inputs by the STICS model. This vignette explains the second one. For more details on how to manipulate XML files, please refer to the vignette Manipulating STICS XML files.

Disclaimer: These functionalities are more oriented toward advanced users and/or developers.

Using this package, it is possible to:

convert the XML files to text files (convert_xml2txt()), please see the Generating STICS text files vignette;
read (get_param_txt() or set (set_param_txt()) parameters;
Read the climate (get_climate_txt());
Set the output variables required (gen_varmod()).

To run a STICS simulation on these input files, please refer to the run_stics() function from SticsOnR.

Some example data are available from the package and can be retrieved using the following function call for the STICS version V10.2.0:

example_txt_dir <-
  get_examples_path(file_type = "txt", stics_version = stics_version)

The example_txt_dir directory is: /tmp/RtmpxX0vxz/txt/V10.0. By default, the latest STICS version is taken into account. For getting an example directory for another version, an additional argument must be given stics_version according to an existing version included in the package. The version list can be retrieved using:

get_stics_versions_compat()$versions_list
#> [1] "V8.5"    "V9.0"    "V9.1"    "V9.2"    "V10.0"   "V10.1.0" "V10.2.0"

Getting parameter value

get_param_txt() helps to get the value of a given parameter in a USM. It has two main arguments, the directory of the USM (workspace, where the text files lives), and the parameter names (param) to be searched. But, if param is not used, the returned named list contains all the STICS parameters for a given USM.

Additional arguments can be set for specific extractions:

variety is for getting parameters for a cultivar or a vector of
exact may be used for indicating that the parameter(s) name(s) given by param must be matching exactly parameters names in files
stics_version is to be used if one want to get parameters for another STICS version than the latest one (default), as for getting the example directory

For example to get the value of the atmospheric pressure:

get_param_txt(workspace = example_txt_dir, param = "patm")
#> $station
#> $station$patm
#> [1] 1000

The function returns a named list according to the file where it found the parameter value (here “station”) containing all the values found for the patm parameter (here 1000), along with the parameter name as found in the file. The function performs a fuzzy search, so here after the name of the parameter is only partially given, e.g.: atm

get_param_txt(workspace = example_txt_dir, param = "atm")
#> $station
#> $station$patm
#> [1] 1000

Note that the function does not require the user to know in which file the parameter is because it search the parameter in all files. So if it finds several parameter with the same given name, it will return all. The next example shows how to get parameters from the soil file containing the letter “a”:

get_param_txt(workspace = example_txt_dir, param = "a")$soil
#> $nbcouchessol_max
#> [1] 1000
#> 
#> $argi
#> [1] 22
#> 
#> $calc
#> [1] 1
#> 
#> $albedo
#> [1] 0.2
#> 
#> $obstarac
#> [1] 200
#> 
#> $pluiebat
#> [1] 50
#> 
#> $mulchbat
#> [1] 0.5
#> 
#> $codecailloux
#> [1] 2
#> 
#> $codemacropor
#> [1] 2
#> 
#> $codrainage
#> [1] 2
#> 
#> $coderemontcap
#> [1] 2
#> 
#> $ecartdrain
#> [1] 0
#> 
#> $profdrain
#> [1] 0
#> 
#> $capiljour
#> [1] 1
#> 
#> $humcapil
#> [1] 10
#> 
#> $cailloux
#> [1] 0 0 0 0 0
#> 
#> $typecailloux
#> [1] 1 1 1 1 1

For an exact search of parameters, a specific argument exact must be set to TRUE (the default value is FALSE if not provided).

Here we see another peculiarity: the name associated to the value has more information for the plant file, e.g. ” plant$plant1$P_Nmeta” instead of “plant$P_Nmeta”. This is because a USM can potentially have two plant files if it is an intercrop, so the function returns the plant file index where the parameter was found.

It is the same case for the tec file:

get_param_txt(workspace = example_txt_dir, param = "interrang")
#> $tec
#> $tec$plant1
#> $tec$plant1$interrang
#> [1] 2

A particular search in plant parameters for specific varieties, can be done using the variety argument:

either using names,

get_param_txt(workspace = example_txt_dir, param = "stlevamf",
              variety = c("Pactol", "Cecilia", "clarica"))
#> $plant
#> $plant$plant1
#> $plant$plant1$stlevamf
#>  Pactol Cecilia clarica 
#>     253     300     280

or using varieties indexes in plant file,

get_param_txt(workspace = example_txt_dir, param = "stlevamf",
              variety = c(1, 2, 5))
#> $plant
#> $plant$plant1
#> $plant$plant1$stlevamf
#>  DK250 Pactol  Dunia 
#>    225    253    285

The get_param_txt() function is a wrapper around other lower-level functions that reads the parameter values in a given file:

get_ini_txt() for the ficini.txt file;
get_general_txt() for the tempopar.sti file;
get_tmp_txt() for the tempoparv6.sti file;
get_plant_txt() for the ficplt.txt file;
get_tec_txt() for the fictec.txt file;
get_soil_txt() for the param.sol file;
get_station_txt() for the station.txt file;
get_usm_txt() for the new_travail.usm file;
get_varmod() for the var.mod file;

All these functions are exported for convenience, but get_param_txt() is easier to use.

Getting the meteorological data

The get_climate_txt() function helps to get the data from the climat.txt file, and is used as:

get_climate_txt(workspace = example_txt_dir)

#> 
#> Attachement du package : 'dplyr'
#> Les objets suivants sont masqués depuis 'package:stats':
#> 
#>     filter, lag
#> Les objets suivants sont masqués depuis 'package:base':
#> 
#>     intersect, setdiff, setequal, union

The function adds a Date column that is at the standard POSIXct format for convenience.

Setting parameter value

set_param_txt() is used to set the value of a given parameter in a USM. It has three main arguments, the directory of the USM (workspace, where the text files lives), the parameter name (param), and the new value of the parameter.

The actual value of of the atmospheric pressure read above is:

get_param_txt(workspace = example_txt_dir, param = "patm")
#> $station
#> $station$patm
#> [1] 1000

To set a new value of patm to 900:

set_param_txt(workspace = example_txt_dir, param = "patm", value = 900)

Now we can check that the value is changed:

get_param_txt(workspace = example_txt_dir, param = "patm")
#> $station
#> $station$patm
#> [1] 900

There are four more arguments to the function:

append: instead of changing the value of a parameter that already exist in the files, a parameter can be added to the file using this argument. This is used mainly by developers that added a parameter to the model and need to programmatically add it to the input files.
plant_id: This is used for intercropping when there are two plant and tec files. The user can then choose to which plant the value will be changed.
variety: This optional argument may be used for replacing varietal parameter values either giving a name (codevar in the plant file) or an index of the variety specified in the technical file (variete)
layer: This may be used for replacing specific parameters values, for specific soil layers either for the soil characteristics (soil file: param.sol), or roots density and mineral elements concentration at the simulation start (initialisation file: ficini.txt).
stics_version: At last, the model version can be specified through that argument, because files content may vary according to the version.

Specific replacements may be performed combining additional arguments as plant_id, layer:

The initial values of densinitial are:

get_param_txt(workspace = example_txt_dir, param = "densinitial")
#> $ini
#> $ini$plant
#> $ini$plant$plant1
#> $ini$plant$plant1$densinitial
#> [1] 0 0 0 0 0
#> 
#> 
#> $ini$plant$plant2
#> $ini$plant$plant2$densinitial
#> [1] "     "

The values for the plant 1 and layers 1 and 4 are replaced as follows:

set_param_txt(workspace = example_txt_dir,
              param = "densinitial",
              plant_id = 1,
              layer = c(1, 4),
              value = c(0.5, 0.1))
#> Warning: The `plant` argument of `set_param_txt()` is deprecated as of SticsRFiles
#> 1.4.0.
#> ℹ Please use the `plant_id` argument instead.
#> This warning is displayed once every 8 hours.
#> Call `lifecycle::last_lifecycle_warnings()` to see where this warning was
#> generated.

The final values in the file are:

get_param_txt(workspace = example_txt_dir, param = "densinitial")
#> $ini
#> $ini$plant
#> $ini$plant$plant1
#> $ini$plant$plant1$densinitial
#> [1] 0.5 0.0 0.0 0.1 0.0
#> 
#> 
#> $ini$plant$plant2
#> $ini$plant$plant2$densinitial
#> [1] "                     "

Note that as for get_param_txt(), set_param_txt() finds automatically the file where the parameter is. It is also a wrapper around lower-level functions that set the parameter values in a given file:

set_ini_txt() for the ficini.txt file;
set_general_txt() for the tempopar.sti file;
set_tmp_txt() for the tempoparv6.sti file;
set_plant_txt() for the ficplt.txt file;
set_tec_txt() for the fictec.txt file;
set_soil_txt() for the param.sol file;
set_station_txt() for the station.txt file;
set_usm_txt() for the new_travail.usm file;

All these functions are exported for convenience, but set_param_txt() is easier to use. These low-level functions may be used when a parameter name is replicated between files and the user wants to change the value of one only, or if the user need to replace the values for a particular variety in the plant file.

Set the output variables

The gen_varmod() function is used to set the required output variables in the var.mod file. For example if the user need the LAI and the dry mass:

gen_varmod(workspace = example_txt_dir, var = c("lai(n)", "masec(n)"))

Controlling if the values where written:

get_varmod(example_txt_dir)
#> [1] "lai(n)"   "masec(n)"

Alternatively, the user can append a variable to the pre-existing vector of values using the append argument:

gen_varmod(workspace = example_txt_dir, var = c("hauteur"), append = TRUE)
get_varmod(example_txt_dir)
#> [1] "lai(n)"   "masec(n)" "hauteur"

To get the possible output variables from the model, the user can use the get_var_info() function that provide a fuzzy search:

get_var_info("lai")
#>              name
#> 5       albedolai
#> 242        exolai
#> 338        innlai
#> 353        lai(n)
#> 354 lai_mx_av_cut
#> 355        laimax
#> 356     laisen(n)
#> 742         splai
#> 805       ulai(n)
#>                                                           definition
#> 5                   albedo of the crop including soil and vegetation
#> 242              reduction factor on leaf growth due to water excess
#> 338 reduction factor on leaf growth due to NNI (nitrogen deficiency)
#> 353                                          leaf area index (table)
#> 354            LAI before cut (for cut crops , for others = lai(n) )
#> 355                                          maximum leaf area index
#> 356                      leaf area index of senescent leaves (table)
#> 742                source to sink ratio of assimilates in the leaves
#> 805                                relative development unit for LAI
#>            unit type
#> 5            SD real
#> 242         0-1 real
#> 338 innmin to 1 real
#> 353      m2.m-2 real
#> 354          SD real
#> 355      m2.m-2 real
#> 356      m2.m-2 real
#> 742          SD real
#> 805         0-3 real