suppressPackageStartupMessages(library(SticsRFiles)) suppressPackageStartupMessages(library(SticsOnR)) knitr::opts_chunk$set( collapse = TRUE, comment = "#>", fig.path = "man/figures/README-" ) options(tibble.print_min = 5, tibble.print_max = 5) javastics_dist <- params$javastics_dist root_path <- normalizePath(params$root_path, winslash = "/") javastics_path <- file.path(root_path, params$javastics_dist) workspace_path <- file.path(javastics_path, params$work_dir) output_path <- file.path(root_path, "gen_usms_xml2txt") windows <- params$windows linux <- !windows java_cmd <- "java" if (linux) java_cmd <- normalizePath(params$java_cmd, winslash = "/")
# For testing consistency betwen JavaSTICS and java version # Adding a test to see if javastics is compatible with java version res <- try(run_javastics(javastics_path, workspace_path, usm = "wheat", verbose = FALSE, java_cmd = java_cmd), silent = TRUE) try_err <- attr(res, "class") if (!is.null(try_err) && attr(try_err, "class") == "try-error") { ver <- system2(command = "java", args = "-version", stdout = TRUE, stderr = TRUE) stop(javastics_dist, ": javastics not compatible with java\n", ver[1], paste0("\nA java path must be provided for a ", "compatible java version (11) to run_javastics")) }
The R package for the STICS model
The goal of SticsOnR is to perform simulations of the Stics model, downloadable with its graphical user interface from https://eng-stics.paca.hub.inrae.fr/Download.
If you want to be notified when a new release of this package is made, you can tick the Releases box in the "Watch / Unwatch => Custom" menu at the top right of this page.
JavaStics must be installed and the minimal version is version 1.41.
The latest distribution version for Stics is downloadable here.
The installation process only consists of unzipping the JavaStics archive, except for MacOS system (see MacOS installation specificities)
Be aware that the java virtual machine does not need to be installed to use the
JavaSTICS software, neither the graphical interface (JavaStics.exe
) nor the command line interface (JavaSticsCmd.exe
). Because, a Java machine is embedded in the JavaStics archive.
For using the JavaStics software (GUI and command line interface) under a linux
operating system, the java version must be consistent with the JavaStics version
So, for adapting the java version to the JavaStics version some manipulations must be done either by switching between versions through system commands see here, using a specific java executable path (see running JavaStics).
For the linux operating system, the SticsOnR package may require to install an xslt
library.
If the SticsOnR installation fails, and the xslt
library is missing, the error message indicates what is the name of the xslt library to be installed (according to the common linux distributions). For example, for the Ubuntu or Debian OS libxslt1-dev
must be installed.
The STICS executable must be compiled and imported in the JavaStics directory. The procedure is fully described in the JavaStics documentation (see JavaStics_documentation.html under the doc folder), in the prerequisites sub-section under the Software section. Java version installation management is also described in it.
Under all systems, file paths must not contain any special character or space.
Under unix like systems, using the ~
in files or directories paths may cause errors in SticsOnR functions. So, it is safer for the moment to use absolute paths. This will be fixed in the future versions.
For installing packages from the Github site an additional package must be installed. One can use either devtools
or remotes
For devtools
, installation requires system dependent tools. They must be installed first.
build-essentials
package for a Debian like distribution for example.Then the devtools
package can be installed using:
install.packages("devtools")
For remotes
, it can be directly installed using:
install.packages("remotes")
SticsRPacks
The best way to install the packages from SticsRPacks
, from which SticsOnR
is part of, is by installing the [SticsRPacks]
package:
devtools::install_github("SticsRPacks/SticsRPacks")
remotes
remotes::install_github("SticsRPacks/SticsRPacks")
The package will install the packages for you at the latest release version.
The package installation can be remotely done directly from GitHub using either devtools
or the lightweight remote
one package
The latest release version can be installed using:
devtools
devtools::install_github("SticsRPacks/SticsOnR@*release")
remotes
remotes::install_github("SticsRPacks/SticsOnR@*release")
Normally, all the package dependencies will be installed for CRAN packages.
SticsRFiles
must be installed manually using the above syntax, just replacing SticsOnR with SticsRFiles.
library(SticsOnR) library(SticsRFiles)
Here are basic examples which show you how to run the model either from a R model interface or a JavaStics (command line) one. More complete examples will be detailed in a specific documentation later.
The JavaStics installation folder (for example, r javastics_dist
) contains an example
workspace folder with a set of runnable usms.
For running simulations from it, we can use the run_javastics()
function.
Specifying the JavaStics folder
javastics_path <- r paste0('/path/to/',javastics_dist)
Specifying a workspace
workspace_path <- "example"
workspace_path <- "/path/to/javastics/workspace"
########## For Windows or linux with a compatible java version ################ # Running specific usms from the workspace run_javastics(javastics_path, workspace_path, usm = c("banana", "wheat"), verbose = FALSE) # Running all usms contained in the workspace run_javastics(javastics_path, workspace_path, verbose = FALSE) # Getting information about execution: runs_info <- run_javastics(javastics_path, workspace_path, usm = c("banana", "wheat"), verbose = FALSE) runs_info
java_cmd <- "/path/to/java/exe"
################ Only for linux with a specific java executable################ # Running specific usms from the workspace run_javastics(javastics_path, workspace_path, usm = c("banana", "wheat"), verbose = FALSE, java_cmd = java_cmd) # Running all usms contained in the workspace run_javastics(javastics_path, workspace_path, verbose = FALSE, java_cmd = java_cmd) # Getting information about execution: runs_info <- run_javastics(javastics_path, workspace_path, usm = c("banana", "wheat"), verbose = FALSE, java_cmd = java_cmd) runs_info
In the returned information, the error field name gives a list of messages from the JavaStics command line interface. If any Error
key word appears in a message, the corresponding simulation failed. But, at the moment it is impossible to identify what is the error's origin. Things must be checked manually in the workspace, after running again the faulty usm (because the model input files are overwritten at each usms simulation).
We need for that a JavaStics folder and a directory with text input files for Stics, or a folder containing individual sub-directories for usms.
These directories can be generated using the [SticsRFiles::gen_usms_xml2txt()]
function from the SticsRFiles package, by converting automatically XML files to Stics input text files. See the documentation here.
Example of use:
# For Windows # Generating files for all the usms contained in the workspace SticsRFiles::gen_usms_xml2txt(javastics_path, workspace = workspace_path, out_dir = output_path, verbose = FALSE)
# For linux, using a specific java executable # Generating files for all the usms contained in the workspace SticsRFiles::gen_usms_xml2txt(javastics_path, workspace = workspace_path, out_dir = output_path, verbose = FALSE, java_cmd = java_cmd)
unlink(x = file.path(output_path, "intercrop_pea_barley"), recursive = TRUE)
The run_stics()
function can be used as follows with one folder or multiple sub-folders.
The Stics executable path is set according to each operating system:
stics_path <- file.path(javastics_path,"bin","stics_modulo.exe")
stics_path <- file.path(javastics_path,"bin","stics_modulo")
stics_path <- file.path(javastics_path,"bin","stics_modulo_mac")
# Specifying the Stics executable file path stics_path <- file.path(javastics_path, "bin", "stics_modulo.exe") # for linux if (is_unix()) stics_path <- file.path(javastics_path, "bin", "stics_modulo")
# Specifying a directory containing Stics input files # For example reusing a generated sub-directory in the previous section # of the document # Running one usm files_dir_path <- file.path(output_path, "banana") run_stics(stics_path, files_dir_path) # Specifying a root directory containing usms individual directories # For example reusing a generated directory in the previous section # of the document # Running two usms run_stics(stics_path, output_path, usm = c("banana", "wheat")) # Running all the usms defined in the sub-directories of output_path run_stics(stics_path, output_path, usm = "all") # Getting returned information about stics runs runs_info <- run_stics(stics_path, output_path, usm = c("banana", "wheat")) runs_info
A specific function stics_wrapper()
is dedicated to manage simulations with a higher level
of parameterization than what run_stics()
offers.
This stics_wrapper()
function allows:
As the run_stics()
function, the stics_wrapper()
operates on directories
containing text stics input files.
Simulation options can be fixed using the stics_wrapper_options()
function.
Both of them are mandatory: the model executable path and the directory path containing usms sub-directories with text input files.
A template is returned by the function when called with no arguments:
stics_wrapper_options()
For the example, we will use the default stics model version shipping with JavaStics and the directory where individual usms input directories have been generated:
sim_options <- stics_wrapper_options(javastics = javastics_path, workspace = output_path, verbose = FALSE)
By default, stics_wrapper_options()
checks that javastics
, stics_exe
and workspace
exists.
There are different solutions if you need to use a custom version of stics:
sim_options <- stics_wrapper_options(javastics = javastics_path, stics_exe = "stics_custom", workspace = output_path, verbose = FALSE)
sim_options <- stics_wrapper_options(javastics = javastics_path, stics_exe = "stics_custom.exe", workspace = output_path, verbose = FALSE)
javastics_path
:sim_options <- stics_wrapper_options(stics_exe = "path/to/stics_custom.exe", workspace = output_path, verbose = FALSE)
results <- stics_wrapper(model_options = sim_options)
usm <- c("wheat", "maize") results <- stics_wrapper(model_options = sim_options, situation = usm)
usm <- c("wheat", "maize") stics_wrapper(model_options = sim_options, situation = usm, var = c("masec_n", "mafruit"))
The argument sit_var_dates_mask
must contain a named list (named by usms names) containing
data.frames, as the sim_list element of the list returned by stics_wrapper (see here-after) or as observations data.
It defines a mask: stics_wrapper will return a result for each USM, variable and date that contains at least a value (i.e. different from NA) in the mask.
The stics_wrapper function returns a list that contains two elements:
obs_list <- get_obs(workspace = workspace_path, usm = c("wheat", "maize"), verbose = FALSE) # Observations table for wheat obs_list$wheat sim_options <- stics_wrapper_options(javastics = javastics_path, workspace = output_path, verbose = TRUE) results <- stics_wrapper(model_options = sim_options, sit_var_dates_mask = obs_list) head(results)
Some warnings may occur, as in this case (that is why results$error
is TRUE), indicating that observed variables and/or observations dates are missing in simulated data.
Concerning the dates, this may be due to the USMs simulation period that may not include observed dates.
For the variables, this may be due to an incorrect spelling of the variables in obs_list.
Parameters values are prescribed using the param_values
argument. It can be a named vector containing the values and names of the parameters to force.
In this case, the same values will be applied for all the simulated usms.
param_values <- c(0.002, 50) names(param_values) <- c("dlaimax", "durvieF") results <- stics_wrapper(model_options = sim_options, situation = usm, param_values = param_values)
param_values
can also be a data.frame or a tibble having one named column per parameter and an optional column named situation
containing the name of the situations (USMs for Stics) that allows to define different values of the parameters for different situations.
# Let's run usm wheat with c(dlaimax=0.001, durvieF=50), # usm pea with c(dlaimax=0.001, durvieF=60), # and usm maize with c(dlaimax=0.001, durvieF=70) param_values <- data.frame(situation = c("wheat", "pea", "maize"), dlaimax = c(0.001, 0.001, 0.001), durvieF = c(50, 60, 70)) # Let's display it param_values results <- stics_wrapper(model_options = sim_options, param_values = param_values, situation = c("wheat", "maize"))
USMs can be run in successive mode, if they are adequately defined (i.e. if the beginning and end of simulations are consistent), using the option successive_usms
.
successive_usms
is a list of vectors containing the names of the UMSs to consider as successive (e.g. list(c("usm1.1","usm1.2"),c("usm2.1","usm2.2"))
defines 2 successions usm1.1 -> usm1.2 and usm2.1 -> usm2.2).
sim_options <- stics_wrapper_options(javastics = javastics_path, workspace = output_path, time_display = TRUE, verbose = FALSE) results <- stics_wrapper(model_options = sim_options)
On may specify the number of cores to use with the cores argument.
sim_options <- stics_wrapper_options(javastics = javastics_path, workspace = output_path, parallel = TRUE, time_display = TRUE, cores = 2, verbose = FALSE) results <- stics_wrapper(model_options = sim_options)
If cores is not given, parallel execution is performed over machine total cores number minus 1.
library(parallel) # Used cores number detectCores() - 1 sim_options <- stics_wrapper_options(javastics = javastics_path, workspace = output_path, parallel = TRUE, time_display = TRUE, verbose = FALSE) results <- stics_wrapper(model_options = sim_options)
If you have any question or suggestion or if you want to report a bug, please do it via the GitHub issues.
Thanks for that, this would greatly help us to improve this package.
If you have used this package for a study that led to a publication or report, please cite us. You can either use the citation tool from Github if you used the last version, or use citation("SticsOnR")
from R otherwise.
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.
The package is under intensive development, so you can fill an issue or request us a feature here at any time.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.