Manipulating STICS text files

library(SticsRFiles)

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:

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.1.0:

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

The example_txt_dir directory is: /tmp/RtmpzHQUrF/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"

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:

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:

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
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:

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:

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

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] "     "
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.
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:

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