2-Sensitivity analyses

Rémi Vezy

2020-03-26

Sensitivity analyses

Sensitivity analyses are critical steps for model evaluation. This step is often complicated because it is hard to implement and hard to understand. One purpose of the sticRs package is to make this step easy by abstracting all the complex code and reduce it to only one main function. Currently, the package supports two different and well known algorithms: fast99 and sobol. Both functions come from the excellent sensitivity package. The function is simply called sensitive_stics, and make automatic sensitivity analyses of any STICS output variable to any given number of parameter.

DOE

The design of experiment, or DOE, is a sample of parameter values that will be tested during the sensitivity analysis. If the user wants to study the interaction between several parameters, the DOE will be a data.frame with parameters in column and their values in rows. The values are sampled using distribution functions, such as the uniform distribution or the normal distribution. In sensitive_stics, the DOE is always computed using the fast99 function.

Here is the first four rows of an example DOE to study the intercations between the interrow and the sowing density:

#> Registered S3 method overwritten by 'sensitivity':
#>   method    from 
#>   print.src dplyr

interrang	P_densitesem
0.1500000	210
0.1957143	214
0.2414286	218
0.2128571	222

Description and parameterization

Here is an example of a sensitive_stics call for the previous example:

library("sticRs")
sens= sensitive_stics(dir.orig = "0-Data",
                      dir.targ = "2-Simulations",
                      stics = "0-Data/stics_executable/stics.exe",
                      obs_name = "Wheat.obs",
                      Vars = c("lai(n)", "masec(n)"),
                      Parameters = list(interrang= list(min = 0.05, max = 0.25),
                                        P_densitesem= list(min = 140, max = 280)),
                      method = "fast99", n = 70, q = "qunif")

The function will use the STICS inputs located in “0-Data”, use the STICS executable located in “0-Data/stics_executable/stics.exe”, and execute the simulations in automatically generated sub-folders in “2-Simulations”. The function will test the sensitivity of the leaf area index (lai(n)) and the above-ground dry mass (masec(n)) variables to the interrow (interrang) and the sowing density (P_densitesem) parameters. The parameter values are sampled using a uniform distribution (its quantile function name is provided: “qunif”) with a minimum value of 0.05 and 140 and a maximum of 0.25 and 280 for the interrow and the sowing density respectively. The fast99 algorithm will be used to perform the sensitivty analysis with 70 simulations.

If a parameter distribution is closer to a normal distibution, which is often the case in reality, the user should set the q parameter to “qnorm” instead to better sample plausible values of the parameter. If so, the user should also replace the parameter arguments (min and max) and values that correspond to qunif arguments by the arguments of the qnorm function, such as:

library("sticRs")
sens= sensitive_stics(dir.orig = "0-Data",
                      dir.targ = "2-Simulations",
                      stics = "0-Data/stics_executable/stics.exe",
                      obs_name = "Wheat.obs",
                      Vars = c("lai(n)", "masec(n)"),
                      Parameters = list(interrang= list(mean = 0.15, sd = 0.05),
                                        P_densitesem= list(mean = 210, sd = 70)),
                      method = "fast99", n = 70, q = "qnorm")

Run with caution

The sensitivity analysis is performed by running a STICS simulation with input parameter(s) values taken from each row of the DOE. As the number of simulations required to perform a sensitivity analysis on several parameters can be gigantic, the function make the simulations in parallel using all cores minus one from the computer to reduce computation time, and delete each simulation files and folders recursively as soon as its results are imported in R to reduce disk occupation. However, if R or the computer crashes during the sensitivity analysis, all results would be lost if Erase= T (as they were continuously erased). There is an argument to disable the deleting (Erase), but the user should proceed with care as the disk space occupied by the simulations can grow very rapidly.

Outputs

sensitive_stics returns a list of three objects:

• gg_objects: A list of ggplot objects to plot the sensitivity of each variable to the parameter(s)
• sensi_objects: A list of the sensitivity analysis output, e.g. a list of class fast99 for the fast99 method.
• DOE: A list of the design of experiment, with parameter values used for each simulation.

Here is the ggplot2 object for the leaf area index from our previous example:

sens$gg_objects$`lai(n)`

Figure 1: Sensitivity analysis output

The plot is not very usefull as it is. It only tell us that the leaf area index seems to be sensitive to the variability of the parameters values. These results are only interesting when coupled with the sensi_objects outputs, but they also can be improved if rendered interactively, for exemple using plotly::ggplotly.

Save / Load

The sensitivity object can be easily saved on disk using the save_sensi function, and then reloaded using load_sensi.