The goal of SticsRFiles is to perform manipulations of
all types of files related to the input and outputs of the STICS
model.
This article presents the design of the package and its basic features, i.e. the main functions to deal with the XML files. For a complete introduction to SticsRPacks (managing files, running simulations, plotting, optimization…), see the tutorial from the SticsRPacks package.
The executable of the STICS model reads text files with standard names and format to import the inputs describing a single unit of simulation (USM), e.g. one crop for one year.
Here’s a typical list of the input files for the STICS executable (without the optional files):
workspace
│
├── 📜climat.txt # The meteorological data for the USM
├── 📜ficini.txt # The initialization
├── 📜ficplt1.txt # Parameters for the plant to be simulated
├── 📜fictec1.txt # The management applied to the soil and crop
├── 📜new_travail.usm # The general configuration parameters for the USM
├── 📜param.sol # Soil parameters
├── 📜station.txt # The site parameters (*e.g.* altitude, latitude)
├── 📜tempopar.sti # More general parameters not in the other files
├── 📜tempoparv6.sti # Parameters for the custom versions of STICS
└── 📜var.mod # Variables to write in the outputsBecause these files only describe one USM at a time and can be tedious to explore and parameterize, we usually don’t interact with them directly, but through another program: JavaSTICS.
JavaSTICS is a graphical user interface used to easily create input text files for the STICS executable according to the user’s choices, and for managing STICS simulations. JavaSTICS saves the parameter values and options choices in XML files.
The XML files store more information than the text files: not only do they store the parameter values but also their description, maximum and minimum boundary values, all existing formalisms, the different choices allowed, and more importantly they allow for the management of several USMs in the same folder (called workspace), and can help make successive USMs.
It is important to note that only JavaSTICS interact with the XML files, not the STICS executable. The STICS input text files are then automatically created by JavaSTICS when running a simulation, just before calling the STICS executable.
SticsRFiles is an R package that uses JavaSTICS from the
command line to manage the XML and the text files. We can generate XML
or text files, get and set parameter values, import simulations outputs,
and manage observation files.
Advanced features also include:
Here’s a simple example usage of SticsRFiles using an
example workspace.
All the example data used in this article are available from the data
repository in the SticsRPacks organization.
SticsRFiles provides a function to download it from the
command line. Please execute the following command in R:
library(SticsRFiles)
example_data <- SticsRFiles::download_data(
example_dirs = "study_case_1",
stics_version = "V10.0"
)The example data is downloaded by default in a temporary folder.
For the sake of readability, we’ll declare the workspace path and the path to the plant file here. But remember the functions can be applied to any XML files or workspaces.
get_var_info() helps to get any STICS variable name by
doing a fuzzy search. For example to get all variables with
lai in their names, you would do:
SticsRFiles::get_var_info("lai")
#> name
#> 5 albedolai
#> 243 exolai
#> 349 innlai
#> 365 lai(n)
#> 366 lai_mx_av_cut
#> 367 laimax
#> 368 laisen(n)
#> 757 splai
#> 820 ulai(n)
#> definition
#> 5 albedo of the crop including soil and vegetation
#> 243 reduction factor on leaf growth due to water excess
#> 349 reduction factor on leaf growth due to NNI (nitrogen deficiency)
#> 365 leaf area index (table)
#> 366 LAI before cut (for cut crops , for others = lai(n) )
#> 367 maximum leaf area index
#> 368 leaf area index of senescent leaves (table)
#> 757 source to sink ratio of assimilates in the leaves
#> 820 relative development unit for LAI
#> unit type
#> 5 SD real
#> 243 0-1 real
#> 349 innmin to 1 real
#> 365 m2.m-2 real
#> 366 SD real
#> 367 m2.m-2 real
#> 368 m2.m-2 real
#> 757 SD real
#> 820 0-3 realSometimes it is also useful to search in the variable definition
instead of its name. To do so, you can use the keyword
argument like so:
SticsRFiles::get_var_info(keyword = "lai")
#> name
#> 5 albedolai
#> 171 diftemp1intercoupe
#> 172 diftemp2intercoupe
#> 243 exolai
#> 345 inn1intercoupe
#> 347 inn2intercoupe
#> 349 innlai
#> 365 lai(n)
#> 366 lai_mx_av_cut
#> 367 laimax
#> 368 laisen(n)
#> 372 leai
#> 757 splai
#> 760 str1intercoupe
#> 761 str2intercoupe
#> 762 stu1intercoupe
#> 763 stu2intercoupe
#> 816 tustress
#> 820 ulai(n)
#> definition
#> 5 albedo of the crop including soil and vegetation
#> 171 mean difference between crop and air temperatures during the vegetative phase (emergence - maximum LAI)
#> 172 mean difference between crop and air temperatures during the reproductive phase (maximum LAI - maturity)
#> 243 reduction factor on leaf growth due to water excess
#> 345 average NNI during the cut (cut crop vegetative phase: emergence to maximum LAI)
#> 347 average NNI during the cut (cut crop reproductive phase: maximum LAI to maturity)
#> 349 reduction factor on leaf growth due to NNI (nitrogen deficiency)
#> 365 leaf area index (table)
#> 366 LAI before cut (for cut crops , for others = lai(n) )
#> 367 maximum leaf area index
#> 368 leaf area index of senescent leaves (table)
#> 372 Leaf+ear area index = lai +eai
#> 757 source to sink ratio of assimilates in the leaves
#> 760 average stomatal water stress index during the vegetative phase (emergence - maximum LAI) of forage crops
#> 761 average stomatal water stress index during the reproductive phase (maximum LAI - maturity) of forage crops
#> 762 average turgescence water stress index during the vegetative phase (emergence - maximum LAI) of forage crops
#> 763 average turgescence water stress index during the reproductive phase (maximum LAI - maturity) of forage crops
#> 816 reduction factor on leaf growth due to the effective water stress (= min(turfac,innlai))
#> 820 relative development unit for LAI
#> unit type
#> 5 SD real
#> 171 degreeC real
#> 172 degreeC real
#> 243 0-1 real
#> 345 0-2 real
#> 347 0-2 real
#> 349 innmin to 1 real
#> 365 m2.m-2 real
#> 366 SD real
#> 367 m2.m-2 real
#> 368 m2.m-2 real
#> 372 m2.m-2 real
#> 757 SD real
#> 760 0-1 real
#> 761 0-1 real
#> 762 0-1 real
#> 763 0-1 real
#> 816 0-1 real
#> 820 0-3 realget_param_info() can be used giving a part of parameters
names, here is a subset of the parameters names containing
lai:
head(get_param_info(param = "lai"))
#> name file min max
#> 53 cielclair STATION 0 1
#> 94 codeclaircie PARTEC 1 2
#> 128 codelaitr PARPLT 1 2
#> 187 codlainet PARPLT 1 2
#> 251 dlaimax PARPLT 0.000005 0.5
#> 252 dlaimaxbrut PARPLT 0.000005 0.5
#> definition
#> 53 fraction of sunny hours allowing the inversion of thermal gradient with altitude
#> 94 option to simulate fruit removal: 1 = no, 2 = yes (for smallest fruits)
#> 128 option to calculate the intercepted radiation according to: 1 = LAI, 2 = soil cover
#> 187 option to calculate the LAI: 1 = net LAI, 2 = difference between gross LAI and senescent LAI
#> 251 maximum rate of net daily increase of LAI
#> 252 maximum rate of gross daily increase of LAI
#> unit cultivar
#> 53 SD NA
#> 94 code 1/2 NA
#> 128 code 1/2 NA
#> 187 code 1/2 NA
#> 251 m2.degree_d-1 NA
#> 252 m2.degree_d-1 NAit can also be used by giving a keyword that will be searched in the
parameters names and definitions, here is a subset of the parameters
names containing plant:
head(get_param_info(keyword = "plant"))
#> name file min max
#> 5 adens PARPLT -2 0
#> 7 adil PARPLT 1 7
#> 8 adilmax PARPLT 3 10
#> 16 albedomulchresidus PARAM 0.05 0.8
#> 32 bdens PARPLT 1 200
#> 33 bdil PARPLT 0.01 0.8
#> definition unit
#> 5 Interplant competition parameter SD
#> 7 parameter of the critical dilution curve [Nplante]=adil MS^(-bdil) %
#> 8 parameter of the maximum dilution curve [Nplante]=adilmax MS^(-bdilmax) %
#> 16 albedo of plant mulch SD
#> 32 minimal plant density above which interplant competition starts m-2
#> 33 parameter of the critical dilution curve [Nplante]=adil MS^(-bdil) SD
#> cultivar
#> 5 NA
#> 7 NA
#> 8 NA
#> 16 NA
#> 32 NA
#> 33 NAget_param_xml() is used to get the values of a parameter
in an XML file. For example if we want to get dlaimax, we
would do:
dlaimax <- get_param_xml(plant_file, "dlaimax")
dlaimax
#> $maisopti_plt.xml
#> $maisopti_plt.xml$dlaimax
#> [1] 0.00321 0.00321 0.00321 0.00321 0.00321But this function is way more powerful than just that. You can also
get the values for all parameters in a given formalism
(formalisme in French, yes some variables are still written
in French in STICS). To do so, use the select argument like
so:
values <- get_param_xml(plant_file,
select = "formalisme",
select_value = "radiation interception"
)
unlist(values) # For pretty-printing
#> maisopti_plt.xml.codetransrad maisopti_plt.xml.forme
#> 1 1
#> maisopti_plt.xml.rapforme maisopti_plt.xml.adfol
#> 4 1
#> maisopti_plt.xml.dfolbas maisopti_plt.xml.dfolhaut
#> 5 5We can also change the value of a parameter by programming using
set_param_xml(). It is used similarly to
get_param_xml(). For example if we want to increase
dlaimax by 30%:
new_values <- unlist(dlaimax) * 1.3
set_param_xml(file = plant_file, param = "dlaimax", values = new_values, overwrite = TRUE)Don’t forget to use the overwrite argument and set it to
TRUE. It is FALSE by default to avoid any
mishandling.
New values written in the file can be checked:
We can generate observation files from a data.frame
using gen_obs().
Lets create some dummy data.frame first:
Then we can write the data to a file using
gen_obs():
We can read the observation files in a workspace using
get_obs(). Note that all observation files should be named
after the USM they are linked to. See the help page for more details,
e.g. about intercrops.
Likewise, we can read the observation files in a workspace using
get_sim():
sim <- get_sim(workspace)
#> Warning in get_file_(workspace = x, usm_name = usm_name, usms_filepath =
#> usms_path, : Not any sim file detected in
#> workspace/tmp/RtmpjkDYAq/data-master/
#> study_case_1/V10.0/XmlFilesBut as there aren’t any simulations yet in the workspace, the function will return an error. To make a simulation, head to SticsOnR. Then to plot both observations and simulations, you can use CroPlotR.