vignettes/Manipulating_Stics_text_files.Rmd
Manipulating_Stics_text_files.Rmd
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_xml2txt()
), please see the Generating
STICS text files vignette;get_param_txt()
or set
(set_param_txt()
) parameters;get_climate_txt()
);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.1.0:
example_txt_dir <-
get_examples_path(file_type = "txt", stics_version = stics_version)
The example_txt_dir
directory is:
/private/var/folders/xz/lz5thm6s3vb1vdkk77vmkgbr0000gn/T/RtmpMJ2A7h/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"
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 ofexact
may be used for indicating that the parameter(s)
name(s) given by param
must be matching exactly parameters
names in filesstics_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 directoryFor 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:
ficini.txt
file;tempopar.sti
file;tempoparv6.sti
file;ficplt.txt
file;fictec.txt
file;param.sol
file;station.txt
file;new_travail.usm
file;var.mod
file;All these functions are exported for convenience, but
get_param_txt()
is easier to use.
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)
#>
#> Attaching package: 'dplyr'
#> The following objects are masked from 'package:stats':
#>
#> filter, lag
#> The following objects are masked from 'package:base':
#>
#> intersect, setdiff, setequal, union
The function adds a Date
column that is at the standard
POSIXct
format for convenience.
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
:
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] " "
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:
ficini.txt
file;tempopar.sti
file;tempoparv6.sti
file;ficplt.txt
file;fictec.txt
file;param.sol
file;station.txt
file;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.
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