Normaly, all packages dependencies will be installed, either CRAN packages or SticsRPacks needed packages. In that case SticsRFiles and CroptimizR will be installed as well.
Examples
-
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 soon.
+
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.
Running the JavaStics command line interface
-
We need for that a JavaStics folder and a JavaStics workspace folder. For example using the last distribution version for Stics 9.1 (JavaSTICS-1.41-stics-9.1).
+
We need for that a JavaStics installed and a JavaStics workspace folder. For example using the last distribution version for Stics 9.1, (JavaSTICS-1.41-stics-9.1 downloadable here).
It contains an example folder with a set of runnable usms.
-
For running simulations from it, we can use the run_javastics function as follows:
For running simulations from it, we can use the run_javastics function.
+
In this SticsOnR package, for the moment, only one Stics version can be used with it (i.e. the one delivered with the JavaStics installation archive). JavaStics GUI, allows to manage several Stics executables, but in that case one must take care of consistency between executables version and input files format (advanced use case).
+
So, at this point, it is at your own risk if you try to use another version than the JavaStics distribution one.
In the returned information, the error field name gives a list of messages got from JavaStics commandline 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 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).
Converting JavaStics workspace files
-
For using the model directly neither using the JavaStics graphical interface nor the run_javastics function interface, we provide a function, gen_usms_xml2txt, for converting JavasStics XML files to Stics text files from a JavaStics workspace.
+
For using the model directly neither using the JavaStics graphical interface nor the run_javastics function interface, we provide a function, gen_usms_xml2txt, for converting JavasStics XML files to Stics text files from a JavaStics workspace.
Observation files may also be copied if they have a standard name as an usm name and a .obs extension. If not, they must be renamed to do so.
We need for that a JavaStics folder and a directory, or a folder containing usms subdirectories with text input files (converted from xml JavaStics files).
+
We need for that a JavaStics folder and a directory, or a folder containing usms subdirectories with text input files (converted from xml JavaStics files, see previous section).
The run_stics function can be used as follows with one folder or multiple sub-folders.
A specific function stics_wrapper is dedicated to manage simulations with a higher level of parameterization than the run_stics function which only executes runs.
+
This is a transitional version of the function that will be modified in order to simplify parameter forcing independently from the optimization goal, so apart from the CroptimizR package context.
+
This stics_wrapper function allows:
+
+
Configuring simulations run behaviour ( through an options list )
+
Parameters forcing for usms (common or specific values)
+
Returning specific outputs daily data for each usm with possible dates and variables filtering
+
Parallelizing simulations runs, and execution time display
+
+
As the run_stics function, the stics_wrapper operates on directories containing text stics input files.
+
In the next uses case, the directory in which usms sub-directories with text input files were generated will be used.
+
+
+Defining simulations options
+
The mandatory simulation options are fixed using the stics_wrapper_options: the model executable path and the directory path containing usms sub-directories with text input files.
Filtering outputs on usms variables and dates using observations data
+
+
The argument sit_var_dates_mask must contain a named list (with usms names) containing data.frames organized as observations data or corresponding to observations data.
Some warnings may occur, indicating that observed variables and/or observations dates are missing in simulated data. Simulation period and output variables list may be fixed before restarting simulations.
+
But, for variables names, perhaps they can be badly written and do not correspond exactly the model variables names.
+
+
+
+Simulations with forcing parameters
+
In this case, we can define variables containing information used for parameters forcing management. They are transmitted to stics_wrapper through 2 arguments, one containing a named vector of parameters values param_values and the other storing corresponding usms groups to which each parameter value of param_values will be applied before running the model.
+
+
Applying a single parameter values vector for all the usms
For the moment, usms names must be restricted to usms names existing in groups_list. So usms names list must be provided as sit_var_dates_mask argument value (in this case c("wheat", "pea", "maize"))
Looking in JavaStics for a workspace path in JavasStics preferences
+or producing a full path to a workspace located in JavaStics root directory
+or validating an external absolute path. And also checking if the path is a
+valid JavaStics workspace
Stics model executable name (current, matching given model name)
+
+
Examples
+
if (FALSE) {
+# Getting the current model executable
+model_exe<-get_model_exe("/home/plecharpent/Work/JavaSTICS-v131-stics-v841")
+# Getting model executable correponding to the given "model_name"
+model_exe<-get_model_exe("/home/plecharpent/Work/JavaSTICS-v131-stics-v841","model_name")
+}
Name(s) vector of sub-directory(ies) of data_dir
+or "all" for extracting all sub-directories path
check_exe
@@ -162,9 +163,13 @@
Examp
"/home/username/Work/SticsInputsDir2"))
# Specifying a parent directory of usms directories
+# running one or several usmsrun_stics("/home/username/bin/Stics","/home/username/Work/SticsInputsRootDir","wheat")
run_stics("/home/username/bin/Stics","/home/username/Work/SticsInputsRootDir",
c("wheat","maize"))
+# running all usms
+run_stics("/home/username/bin/Stics","/home/username/Work/SticsInputsRootDir",
+"all")
}
named vector containing the value(s) and names of the
-parameters to force (optional)
+
a named vector containing the value(s) and names of the
+parameters to force (optional). It may contains either unique value for each
+parameter name or multiple values for each parameter when prior_information
+argument is provided.
sit_var_dates_mask
-
List of situations, variables and dates for which
-simulated values should be returned. Typically a list containing the
-observations to which simulations should be compared as provided by
-SticsRFiles::read_obs_to_list
+
List of situations:
+may be either a character vector of situation names or a named list containing
+information about variables and dates for which simulated values should be returned.
+Typically a list containing the observations to which simulations should be
+compared as provided by SticsRFiles::read_obs
prior_information
@@ -174,12 +177,36 @@
Value
(flag_allsim) indicating if all required situations, variables and
dates were simulated.
+
Examples
+
+if (FALSE) {
+
+# Specifying the JavaStics folder
+javastics_path<-"/path/to/javastics"
+
+# Setting the model executable path (windows, linux)
+stics_path<-file.path(javastics_path, "bin","stics_modulo")
+
+# Setting the input data folder path, root directory of the usms directories
+data_path<-"/path/to/usms/subdirs/root"
+
+# Setting the mandatory simulations options
+# Running all the usms
+sim_options<-stics_wrapper(stics_path=stics_path, data_dir=data_path)
+
+# Running an usm list
+usms_list<-c("wheat", "pea", "maize")
+sim_options<-stics_wrapper(stics_path=stics_path, data_dir=data_path,
+sit_var_dates_mask=usms_list)
+
+}
+