SticsRFiles

In SticsRFiles: Read and Modify 'STICS' Input/Output Files

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

library(SticsRFiles)

suppressWarnings(library(SticsRFiles))
# just in case for unzipping examples files in tempdir
get_examples_path(c("xml", "csv"))

Introduction

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.

Concepts

Input files

Text files

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 outputs

Because 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.

XML files

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

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:

• The generation of XML input files from templates included in the package, and
• The production of XML input files using a mailing process from XML templates and Excel sheets containing multiple simulations contexts

Short example

Here's a simple example usage of SticsRFiles using an example workspace.

Example data

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:

example_data <- SticsRFiles::download_data(out_dir = tempdir(),
                                           example_dirs = "study_case_1",
                                           "V10.0")

library(SticsRFiles)
example_data <- SticsRFiles::download_data(example_dirs = "study_case_1",
                                           "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.

workspace <- file.path(example_data, "XmlFiles")
plant_file <- file.path(workspace, "plant", "maisopti_plt.xml")

Example usage

Find a STICS variable

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")

Sometimes 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")

Get informations on parameters

get_param_info() can be used giving a part of parameters names :

get_param_info(param = "lai")

it can also be used by giving a keyword that will be searched in the parameters names and definitions:

get_param_info(keyword = "plant")

Get parameter values

get_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

But 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

Set parameter values

We can also change the value of a parameter programmatically using set_param_xml(). It is used similarly to get_param_xml(). For example if we want to increase dlaimax by 30%:

set_param_xml(plant_file, "dlaimax", unlist(dlaimax) * 1.3, 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:

dlaimax <- get_param_xml(plant_file, "dlaimax")
dlaimax

Generate observations files

We can generate observation files from a data.frame using gen_obs().

Lets create some dummy data.frame first:

obs_df <- data.frame(usm_name = "Test", ian = 2021, mo = 3:10, jo = 1,
                     `masec(n)` = 0.1 * 3:10)

Then we can write the data to a file using gen_obs():

gen_obs(df = obs_df, out_dir = "/path/to/dest/dir")

Read observations files

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.

obs <- get_obs(workspace)

Read simulation files

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/XmlFiles

But 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.

SticsRFiles documentation built on Sept. 12, 2024, 7:41 a.m.