# sobolmartinez: Monte Carlo Estimation of Sobol' Indices (formulas of... In sensitivity: Global Sensitivity Analysis of Model Outputs

## Description

`sobolmartinez` implements the Monte Carlo estimation of the Sobol' indices for both first-order and total indices using correlation coefficients-based formulas, at a total cost of (p + 2) * n model evaluations. These are called the Martinez estimators.

## Usage

 ```1 2 3 4 5 6 7 8 9``` ```sobolmartinez(model = NULL, X1, X2, nboot = 0, conf = 0.95, ...) ## S3 method for class 'sobolmartinez' tell(x, y = NULL, return.var = NULL, ...) ## S3 method for class 'sobolmartinez' print(x, ...) ## S3 method for class 'sobolmartinez' plot(x, ylim = c(0, 1), y_col = NULL, y_dim3 = NULL, ...) ## S3 method for class 'sobolmartinez' ggplot(x, ylim = c(0, 1), y_col = NULL, y_dim3 = NULL, ...) ```

## Arguments

 `model` a function, or a model with a `predict` method, defining the model to analyze. `X1` the first random sample. `X2` the second random sample. `nboot` the number of bootstrap replicates, or zero to use theoretical formulas based on confidence interfaces of correlation coefficient (Martinez, 2011). `conf` the confidence level for bootstrap confidence intervals. `x` a list of class `"sobol"` storing the state of the sensitivity study (parameters, data, estimates). `y` a vector of model responses. `return.var` a vector of character strings giving further internal variables names to store in the output object `x`. `ylim` y-coordinate plotting limits. `y_col` an integer defining the index of the column of `x\$y` to be used for plotting the corresponding sensitivity indices (only applies if `x\$y` is a matrix or an array). If set to `NULL` (as per default) and `x\$y` is a matrix or an array, the first column (respectively the first element in the second dimension) of `x\$y` is used (i.e. `y_col = 1`). `y_dim3` an integer defining the index in the third dimension of `x\$y` to be used for plotting the corresponding sensitivity indices (only applies if `x\$y` is an array). If set to `NULL` (as per default) and `x\$y` is a three-dimensional array, the first element in the third dimension of `x\$y` is used (i.e. `y_dim3 = 1`). `...` for `sobolmartinez`: any other arguments for `model` which are passed unchanged each time it is called

## Details

This estimator supports missing values (NA or NaN) which can occur during the simulation of the model on the design of experiments (due to code failure) even if Sobol' indices are no more rigorous variance-based sensitivity indices if missing values are present. In this case, a warning is displayed.

This version of `sobolmartinez` also supports matrices and three-dimensional arrays as output of `model`. Bootstrapping (including bootstrap confidence intervals) is also supported for matrix or array output. However, theoretical confidence intervals (for `nboot = 0`) are only supported for vector output. If the model output is a matrix or an array, `V`, `S` and `T` are matrices or arrays as well (depending on the type of `y` and the value of `nboot`).

The bootstrap outputs `V.boot`, `S.boot` and `T.boot` can only be returned if the model output is a vector (using argument `return.var`). For matrix or array output, these objects can't be returned.

## Value

`sobolmartinez` returns a list of class `"sobolmartinez"`, containing all the input arguments detailed before, plus the following components:

 `call` the matched call. `X` a `data.frame` containing the design of experiments. `y` either a vector, a matrix or a three-dimensional array of model responses (depends on the output of `model`). `V` the estimations of normalized variances of the Conditional Expectations (VCE) with respect to each factor and also with respect to the complementary set of each factor ("all but Xi"). `S` the estimations of the Sobol' first-order indices. `T` the estimations of the Sobol' total sensitivity indices.

Users can ask more ouput variables with the argument `return.var` (for example, bootstrap outputs `V.boot`, `S.boot` and `T.boot`).

## Author(s)

Bertrand Iooss, with contributions from Frank Weber (2016)

## References

J-M. Martinez, 2011, Analyse de sensibilite globale par decomposition de la variance, Presentation in the meeting of GdR Ondes and GdR MASCOT-NUM, January, 13th, 2011, Institut Henri Poincare, Paris, France.

M. Baudin, K. Boumhaout, T. Delage, B. Iooss and J-M. Martinez, 2016, Numerical stability of Sobol' indices estimation formula, Proceedings of the SAMO 2016 Conference, Reunion Island, France, December 2016

`sobol, sobol2002, sobolSalt, sobol2007, soboljansen, soboltouati, sobolMultOut`
 ``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41``` ```# Test case : the non-monotonic Sobol g-function # The method of sobol requires 2 samples # There are 8 factors, all following the uniform distribution # on [0,1] library(boot) n <- 1000 X1 <- data.frame(matrix(runif(8 * n), nrow = n)) X2 <- data.frame(matrix(runif(8 * n), nrow = n)) # sensitivity analysis x <- sobolmartinez(model = sobol.fun, X1, X2, nboot = 0) print(x) plot(x) library(ggplot2) ggplot(x) # Only for demonstration purposes: a model function returning a matrix sobol.fun_matrix <- function(X){ res_vector <- sobol.fun(X) cbind(res_vector, 2 * res_vector) } x_matrix <- sobolmartinez(model = sobol.fun_matrix, X1, X2) plot(x_matrix, y_col = 2) title(main = "y_col = 2") # Also only for demonstration purposes: a model function returning a # three-dimensional array sobol.fun_array <- function(X){ res_vector <- sobol.fun(X) res_matrix <- cbind(res_vector, 2 * res_vector) array(data = c(res_matrix, 5 * res_matrix), dim = c(length(res_vector), 2, 2)) } x_array <- sobolmartinez(model = sobol.fun_array, X1, X2) plot(x_array, y_col = 2, y_dim3 = 2) title(main = "y_col = 2, y_dim3 = 2") ```