The sensitivity Package

Transcription

1 The sensitivity Package January 5, 2007 Version Date Title Sensitivity Analysis Author Gilles Pujol (this package was originally developped at Commissariat a l Energie Atomique CEA, Service d Etudes et de Simulation du Comportement des Combustibles CEA/DEN/CAD/DEC/SESC, France ; the author would like to thank : Patrick Obry, Bertrand Iooss, Claire Cannamela and Frederic Michel). Maintainer Bertrand Iooss <bertrand.iooss@cea.fr> Depends R, boot This package allows to perform sensitivity analyses within the R environment. Implemented methods are : linear sensitivity analysis (SRC, PCC, rank analysis), the screening method of Morris, the Sobol global sensitivity indices (two methods of estimation), and the FAST method. License CeCILL version 2 R topics documented: fast morris INTRODUCTION sobol srcpcc tell testmodels Index 12 1

2 2 fast fast Fourier Amplitude Sensitivity Test Usage fast is the implementation of the Fourier Amplitude Sensitivity Test. fast(method = "saltelli99", model = NULL, factors, n, M = 4, omega = NULL, q = NULL, q.arg = NULL,...) Arguments method model factors n M omega q Details q.arg the method: "saltelli99" only the model the number of factors, or their names the sample size the interference parameter the set of frequencies the names of the quantile functions for the factors distributions the quantile parameters... any other arguments for model which are passed unchanged each time it is called The method "saltelli99" is the so-called extended fast method wich provides estimations of both first order and total indices at a low computational cost. model is a function or a predictor (a class with a predict method) computing the response y based on the sample given by x. If no model is specified, the indices will be computed when one gives the response. factors could either be a single number or a vector of character strings. n is the length of the discretization of the s-space (for computing Fourier coefficients) and M is the number of harmonics to sum (for computing partial variances). If the set of frequencies omega is not given, the function use the set recommended by the corresponding method. For the method "saltelli99", the first frequency is the greater, associated with the input variable to assess, and the other frequencies are associated with the complementary set. If q and q.args are not given, the factors will be considerd uniform on [0,1]. q is a list of character strings giving the names of the quantile functions (one for each factor), such as qunif, qnorm... q could also be a single character string (the same for all). q.arg is a list of lists, each list being additional parameters for the corresponding quantile function. For example, the parameters of the quantile qunif could be (min=1, max=2) giving an uniform distribution on [1,2]. If q is a single character string, then q.arg must be a single list.

3 morris 3 Value fast returns an object of class "fast". An object of class "fast" is a list containing the following components: x y S St the factor sample the response the estimations of the first-order indices the estimations of the total indices (method "saltelli99") Computational cost For the method "saltelli99", the number of model evaluations is p n where p is the number of factors. References Saltelli, A., Tarantola, S. and Chan, K., 1999, A quantitative, model independent method for global sensitivity analysis of model output. Technometrics, 41, Saltelli, A., Chan, K. and Scott, E. M., 2000, Sensitivity analysis. Wiley. Cukier, R. I., Levine, H. B. and Schuler, K. E., 1978, Nonlinear sensitivity analysis of multiparameter model systems. J. Comput. Phys., 26, Examples # Test case : the non-monotonic Ishigami function sa <- fast(model = ishigami.fun, factors = 3, n = 1000, q = "qunif", q.arg = list(min = -pi, max = pi)) print(sa) plot(sa) morris The Morris OAT Screening Method morris is the implementation of the Morris OAT Screening method. This function generates the Morris design of experiments and computes the measures of sensitivity µ and σ. Usage morris(model = NULL, factors, levels, R, jump = NULL, min = 0, max = 1, scale = TRUE, optim = NULL,...)

4 4 morris Arguments model factors levels R jump min max Details Value scale optim the model the number of factors, or their names the number of levels of the design grid the number of repetitions of the design, i.e. the number of elementary effect computed per factor the grid jump coefficient the minimum values for the factors the maximum values for the factors logical. If TRUE, the input and output data are scaled optimization of the design for better coverage of the space (cf Campolongo 2005), not documented yet (for informations feel free to ask the maintainer)... any other arguments for model which are passed unchanged each time it is called model is a function or a predictor (a class with a predict method) computing the response y based on the sample given by x. If no model is specified, the indices will be computed when one gives the response. factors could either be a single number or a vector of character strings. The number of levels is not necessary the same for each space coordinate. It is the case when levels is a single integer. min and max are boundaries of the region of experimentation. They can be single values (the same for each factor) or vectors. jump is such that: i = jump i max i min i levels i 1 If jump is given as NULL and the number of levels is even (for each component), then jump has the value recommended by Morris: jump = levels/2. If jump is a single value, then it is taken the same for each coordinate. morris returns an object of class "morris". An object of class "morris" is a list containing the following components: x y ee mu sigma the design of experiments (input sample) the response the matrix of the elementary effects the estimations of the µ index the estimations of the σ index

5 INTRODUCTION 5 Computational cost The number of model evaluations is (p + 1) R where p is the number of factors. References Saltelli, A., Chan, K. and Scott, E. M., 2000, Sensitivity analysis. Wiley. Morris, M. D., 1991, Factorial sampling plans for preliminary computational experiments. Technometrics, 33, Examples # Test case : the non-monotonic function of Morris sa <- morris(model = morris.fun, factors = 20, levels = 4, R = 4) print(sa) plot(sa) INTRODUCTION Package sensitivity : Sensitivity Analysis The sensitivity package implements sensitivity analysis methods: linear and monotonic sensitivity analysis (SRC, PCC, SRRC, PRCC), the screening method of Morris, and non-linear global sensitivity analysis (the Sobol indices, the FAST method). The functions of this package generate the design of experiments (depending on the method of analysis) and compute the sensitivity indices based on the model inputs and outputs. All sensitivity indices can be estimated with the bootstrap technique which allows to estimate the bias, and basic bootstrap confidence intervals. Text and graphical outputs display the results of the analysis. Details The approach applied when performing a sensitivity analysis (SA) is as follows: step 1 The model is defined: it is a function that returns the (real) ouput values (called responses), corresponding to a sample of (real) input parameters (called factors). step 2 A sensitivity analysis method is chosen. Parameters of this method must be in accordance with objectives and technical constraints (like computational time). step 3 A design of experiments (DOE) corresponding to the SA method is generated. step 4 The model is evaluated on the DOE values. step 5 The sensitivity indices are computed, based on input and output values. step 6 Post-treatments...

6 6 sobol The sensitivity package allows to follow this methodology: (step 1) The model can be internal or external to R. If internal, it can be a function that takes an unique matrix or data.frame parameter and returns a numeric vector. It can also be a predictor, i.e. an object wich can be called with the predict method. One should note that all the responses must be computed by a single call to the model function (then, the model can be vectorized). If the model is external it does not have to be interfaced with R: the user won t have to give a model to the function. Then, it will stop just after generating the DOE. The responses have to be computed by the user, whithin R or not. Calculations will start again when the user gives the corresponding responses (via the tell function). The four next steps depend upon the type of the model: For internal models: (step 2-5) sa <- method(model, parameters...) For external models: (step 2-3) sa <- method(model = NULL, parameters...) (step 4) external to R (or not), and the result is loaded by the user in the y variable (step 5) tell(sa, y) method should be the name of a SA function, such as srcpcc, morris, sobol, or fast. These function create the object sa of class "srcpcc", "morris", "sobol", or "fast". For further information on these function, see the corresponding documentation. Finally, for displaying the results of the analysis: (step 6) print(sa); plot(sa) References Saltelli, A., Chan, K. and Scott, E. M., 2000, Sensitivity analysis. Wiley, See Also srcpcc morris sobol fast tell testmodels sobol Sobol Non-linear Sensitivity Analysis sobol is the implementation of the Monte Carlo estimation of the Sobol indices. Usage sobol(method = "sobol93", model = NULL, x1, x2, max.order = 1, nboot = 0, conf = 0.95,...)

7 sobol 7 Arguments method model x1 x2 Details Value max.order nboot conf the method: "sobol93" or "saltelli02" the model the first random sample the second random sample the maximum order of indices to compute (method "sobol93") the number of bootstrap replicates the confidence level for bootstrap confidence intervals... any other arguments for model which are passed unchanged each time it is called Two methods. The method "sobol93" computes all the Sobol indices (coming from the HDMR- ANOVA decomposition) from order 1 to order given by the argument max.order. The method "saltelli02" computes both first order and total indices at a reduced computational cost. model is a function or a predictor (a class with a predict method) computing the response y based on the sample given by x. If no model is specified, the indices will be computed when one gives the response. The Monte Carlo estimation requires two independent random samples x1 and x2. They must have the same dimensions. sobol returns an object of class "sobol". An object of class "sobol" is a list containing the following components: x y S St the factor sample the response used the estimations of the Sobol sensitivity indices the estimations of the total indices (method "saltelli02") Computational cost For the method "sobol93", the number of model evaluations is n (N + 1) where n is the size of the samples x1 and x2, and N is the number of indices to estimate. For the method "saltelli02", the number of model evaluations is n (p + 2) where p is the number of factors (for the estimation of 2p indices). References Saltelli, A., Chan, K. and Scott, E. M., 2000, Sensitivity analysis. Wiley. Sobol, I. M., 1993, Sensitivity analysis for non-linear mathematical model. Math. Modelling Comput. Exp., 1, Saltelli, A., 2002, Making best use of model evaluations to compute sensitivity indices. Computer Physics Communication, 145,

8 8 srcpcc Examples # 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] n < x <- data.frame(matrix(nr = 2 * n, nc = 8)) for (i in 1:8) x[, i] <- runif(2 * n) # sensitivity analysis sa <- sobol(model = sobol.fun, x1 = x[1:n,], x2 = x[(n+1):(2*n),], max.order = 2, nboot = 10 print(sa) #plot(sa) srcpcc Linear Sensitivity Analysis srcpcc computes the standardized regression coefficients (SRC) and the partial correlation coefficients (PCC). Analysis can be done on the ranks; then the indices are the standardized rank regression coefficients (SRRC) and the partial rank correlation coefficients (PRCC). Usage srcpcc(model = NULL, x, pcc = TRUE, rank = FALSE, nboot = 0, conf = 0.95,...) Arguments model x pcc Details rank nboot conf the model the input sample logical. If TRUE, the P(R)CCs are computed logical. If TRUE, the analysis is done on the ranks the number of bootstrap replicates the confidence level for bootstrap confidence intervals... any other arguments for model which are passed unchanged each time it is called model is a function or a predictor (a class with a predict method) computing the response y based on the sample given by x. If no model is specified, the indices will be computed when one gives the response.

9 tell 9 Value srcpcc returns an object of class "srcpcc". An object of class "srcpcc" is a list containing the following components: y src pcc the response the estimations of the SRC indices (or SRRC if rank analysis is requested) if requested, the estimations of the PCC indices (or PRCC if rank analysis is requested) Computational cost The number of model evaluations is n where n is the size of the sample x. References Saltelli, A., Chan, K. and Scott, E. M., 2000, Sensitivity analysis, Wiley. Examples # linear model : Y = X1 + X2 + X3 model1 <- function(x) x[, 1] + x[, 2] + x[, 3] # a 100-sample with X1 ~ U(0.5, 1.5) # X2 ~ U(1.5, 4.5) # X3 ~ U(4.5, 13.5) n <- 100 x <- data.frame(x1 = runif(n, 0.5, 1.5), X2 = runif(n, 1.5, 4.5), X3 = runif(n, 4.5, 13.5)) # sensitivity analysis sa <- srcpcc(model = model1, x = x, nboot = 100) print(sa) par(mfrow = c(1,2)) plot(sa, ask = FALSE) tell Computation Of Sensitivity Indices When The Model Is External tell is used to tell a sensitivity analysis object the results of the simulations. It is used when the model is not given when parametring the sensitivity analysis (whith the model=null argument). For example, it is the case when the model is external to R.

10 10 testmodels Usage tell(sa, y = NULL) Arguments sa y the sensitivity analysis object the response Details Value sa is an object returned by a sensitivity analysis function, such as srcpcc, morris, sobol,... y should be a numeric vector. tell doesn t return anything. It does the sensitivity analysis, and stores all the results in the variable sa. Examples # Example of the FAST method # (one should note the call with model = NULL) sa <- fast(model = NULL, factors = 8, n = 1000) # at this stage, only the design of experiment (sa$x) was generated # the response is computed "manually": y <- sobol.fun(sa$x) # at this place could be a # call to an external code # then, the sensitivity analysis: tell(sa, y) print(sa) # Remark : because the model is a simple R function, # this example is equivalent to : ## Not run: sa <- fast(model = sobol.fun, factors = 8, n = 1000) testmodels Test Models For Sensitivity Analysis These functions are standard testcase for sensitivity analysis benchmarks. There are: the g-function of Sobol, the function of Ishigami and the function of Morris.

11 testmodels 11 Usage sobol.fun(x) ishigami.fun(x) morris.fun(x) Arguments x the matrix or data.frame containing the input values. Value All these functions return a numeric vector containig the values of the function. These functions are vectorized. References Saltelli, A., Chan, K. and Scott, E. M., 2000, Sensitivity analysis. Wiley,

12 Index Topic misc fast, 1 INTRODUCTION, 5 morris, 3 sobol, 6 srcpcc, 8 tell, 9 testmodels, 10 fast, 1, 6 INTRODUCTION, 5 ishigami.fun (testmodels), 10 morris, 3, 6, 10 morris.fun (testmodels), 10 plot.fast.saltelli99 (fast), 1 plot.morris (morris), 3 plot.sobol.saltelli02 (sobol), 6 plot.sobol.sobol93 (sobol), 6 plot.srcpcc (srcpcc), 8 print.fast.saltelli99 (fast), 1 print.morris (morris), 3 print.sobol.saltelli02 (sobol), 6 print.sobol.sobol93 (sobol), 6 print.srcpcc (srcpcc), 8 sensitivity (INTRODUCTION), 5 sensitivity-package (INTRODUCTION), 5 sobol, 6, 6, 10 sobol.fun (testmodels), 10 srcpcc, 6, 8, 10 tell, 6, 9 tell.fast.saltelli99 (fast), 1 tell.morris (morris), 3 tell.sobol.saltelli02 (sobol), 6 tell.sobol.sobol93 (sobol), 6 tell.srcpcc (srcpcc), 8 testmodels, 6, 10 12