Important

This package is no longer maintained. All functionalities were transfered to the SticsRPacks suite of packages. Please use these packages instead.

sticRs: The R package for the STICS model

Overview

This package allows the user to programmatically:

read (read_param) or set (set_param) parameters
set (set_usm) one or more simulations (USM)
call STICS to run them (run_stics)
import the results for analyzes (read_output), or the observations available in the USM (read_obs)
compare observations and simulations (eval_output)
make all previous at once in parallel to evaluate and compare the output of STICS versions or parameter values effect (stics_eval)
run sensitivity analyzes (sensitive_stics) to one or more input parameters and their possible interactions on one or more output variables. Note that stics_eval can evaluate parameter change effect also, but doesn’t run full sensitivity analyzes.
and optimize parameter values (optimi_stics)

The package is under intensive development, so you can fill an issue or request me a feature here at any time.

The following diagram presents a typical workflow using the main functions from sticRs:

A scientific article is available here.

Installation

The development version from GitHub can be installed with:

devtools::install_github("VEZY/sticRs")

Or using the lightweight remotes package:

# install.packages("remotes")
remotes::install_github("VEZY/sticRs")

The package is tested routinely to pass all CRAN tests using Travis-CI (linux) and AppVeyor (Windows), but it is not released to the CRAN servers because we believe sticRs users are not widespread enough to bother CRAN people and use their free server time.

Examples

Toy examples are given here for users in a hurry, but it is highly recommended to read the introductory vignette for a good start, and the sensitivity and parameter optimization vignettes if needed.

Setting a parameter, running the model and compare with observations

Manually

This is a basic example using the default dummy simulation (parameters and meteorology) for a mixed crop of wheat-wheat (not a real mixed crop, for testing the model behavior) :

library("sticRs")
# Path to a preconfigured USM:
path_origin_USM= "Your_path_goes_here"
# Path where the simulation will be made:
path_simulation= "Your_path_goes_here_again"
# Path to the STICS model executable:
path_STICS= "Your_path_goes_here_again_and_again"
# Importing the preconfigured USM into a new folder:
import_usm(dir.orig = path_origin_USM, 
           dir.targ = path_simulation,
           stics = path_STICS, 
           usm_name = "test")
# Reading the interrang parameter for both plants (= interrow):
read_param(dirpath = file.path(path_simulation,"test"),
           param='interrang')
# Setting the interrang parameter to 0.30m for both plants:
set_param(dirpath = file.path(path_simulation,"test"),
          param= "interrang", value= 0.3,plant = c(1,2))
# Setting the outputs needed from STICS:
set_out_var(filepath = file.path(path_simulation,"test","var.mod"),
            vars = c("hauteur","lai(n)",'masec(n)'))
# Running the model:
run_stics(dirpath= file.path(path_simulation,"test"))
# Reading the model outputs:
out= read_output(dirpath= file.path(path_simulation,"test"))
# Plotting automatically the outputs along the observations: 
plot_output(file.path(path_simulation,"test"),
            obs_name = c("wheat.obs","pea.obs"))

To use your own data, simply use the folder of your simulation as the reference path; like you would do with javaSTICS.

To find a possible output variable with a partial match, you can use the find_STICS_var function.

Automatically

You can run all previous code using the simple, standardized stics_eval function:

library("sticRs")
out= 
  stics_eval(dir.orig = path_origin_USM, 
             dir.targ = path_simulation,
             stics = path_STICS,
             Parameter = list(interrang= 0.3),Plant = c(1,2),
             obs_name = c("wheat.obs","pea.obs"),
             Out_var = c("hauteur","lai(n)",'masec(n)'),
             Title = "Wheat-Wheat", plot_it = T)

This function will import the USM in a new folder, change the parameter values, run the model, return the outputs (simulation output + ggplot object) and plot it.

Comparing model simulations

Comparing STICS outputs with different parameter values

If you want to compare the effect of different values of one or several parameters values on several STICS outputs, you can give different parameter values to the stics_eval function. Here is an example with the P_rapforme parameter:

Eval_stics= 
  stics_eval(dir.orig = path_origin_USM, 
             dir.targ = path_simulation,
             stics = path_STICS,
             Parameter = list(P_rapforme= list(1.5,2,4)),Plant = c(1,2),
             obs_name = c("wheat.obs","pea.obs"),
             Out_var = c("hauteur","laisen(n)","lai(n)","eai","largeur",
                         "varrapforme","dfol","dominant"),
             Title = "Wheat-Wheat", plot_it = T)

The function will return a list of STICS outputs for each parameter value, and a plot comparing the model simulations.

Comparing STICS outputs with different STICS versions

If you want to compare different versions of the model after modifying the code for example, you can give different stics values to the stics_eval function. Here is an example:

Eval_stics= 
  stics_eval(dir.orig = path_origin_USM, 
             dir.targ = path_simulation,
             stics = list(Original= path_STICS,
                          Modified= "Path_to_modified_stics/stics.exe"),
             obs_name = c("wheat.obs","pea.obs"),
             Out_var = c("hauteur","laisen(n)","lai(n)","eai","largeur",
                         "varrapforme","dfol","dominant"),
             Title = "Wheat-Wheat", plot_it = T)

The function will return a list of STICS outputs for each stics executable provided, and a plot comparing the model simulations.

Making a sensitivity analysis

Make a sensitivity analysis using the fast99 algorithm for the interrow (interrang parameter) for three main variables: the intercepted radiation (raint), the leaf area index (lai(n)), and the dry mass (masec(n)):

library("sticRs")
sens= sensitive_stics(dir.orig = path_origin_USM,
                      dir.targ = path_simulation,
                      stics = path_STICS,
                      obs_name = "Wheat.obs",Parameters = "interrang",
                      Vars = c("raint", "lai(n)", "masec(n)"),
                      method= "fast99", n= 10,
                      q= "qunif",Parameters = list(interrang= list(min=0.05, max=0.25),
                                              interrang= list(min=140, max=280)))

NB: n and q are parameters from the fast99 function, and the Parameters argument is passed to the q.arg parameter from fast99.

The output from sensitive_stics is a list of two:

A list of ggplot objects to plot the sensitivity of each variable to the parameter(s) along the rotation
A list of the output from the method function, e.g. a list of class fast99 for the fast99 method.

Example data

Example data are available in the tests folder, but also as a separate repository for download convenience. Download instructions are available on the companion repository.
This example data is a dummy USM of wheat in self-intercropping, meaning that the model is run on the same plant planted in intercropping, to test if the model outputs are close to a sole crop simulation.
Warning: this example USM is made primarily to test the sticRs package, and is available to the user only for training, not for model validation. These data are dummy data that were entirely fabricated from scratch. It is not reflecting any real observations.

Code of conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Authors and acknowledgments

The STICS (Simulateur mulTIdisciplinaire pour les Cultures Standard, or multidisciplinary simulator for standard crops) model is a dynamic, generic and robust model aiming to simulate the soil-crop-atmosphere system. It was first developed in 1996 by INRA -the French National Institute for Agricultural research- by Nadine Brisson and Dominique Ripoche. An overview of the model is available here.

The sticRs package was developed by Rémi Vezy and the STICS group thanks to the European H2020 funded ReMIX project.