# Kriging-based sensitivity analysis Perform a kriging-based global sensitivity analysis taking into account both the meta-model and the Monte-Carlo errors. The Sobol indices are estimated with a Monte-Carlo integration and the true function is substituted by a kriging model. It is built thanks to the function `km` of the package `DiceKriging`. The complete conditional predictive distribution of the kriging model is considered (not only the predictive mean). ```r sobolGP( model, type="SK", MCmethod="sobol", X1, X2, nsim=100, nboot=1, conf = 0.95, sequential = FALSE, candidate, sequential.tot=FALSE, max_iter = 1000) ## S3 method for class 'sobolGP' ask(x, tot = FALSE, ...) ## S3 method for class 'sobolGP' tell(x, y=NULL, xpoint=NULL, newcandidate=NULL, ...) ## S3 method for class 'sobolGP' print(x, ...) ## S3 method for class 'sobolGP' plot(x,...) ``` ## Arguments - `model`: an object of class `"km"` specifying the kriging model built from package `"DiceKriging"` (see `km`). - `type`: a character string giving the type of the considered kriging model. `"SK"` refers to simple kriging and `"UK"` refers to universal kriging (see `km`). - `MCmethod`: a character string specifying the Monte-Carlo procedure used to estimate the Sobol indices. The avaible methods are : `"sobol"`, `"sobol2002"`, `"sobol2007"`, `"sobolEff"` and `"soboljansen"`. - `X1`: a matrix representing the first random sample. - `X2`: a matrix representing the second random sample. - `nsim`: an integer giving the number of samples for the conditional Gaussian process. It is used to quantify the uncertainty due to the kriging approximation. - `nboot`: an integer representing the number of bootstrap replicates. It is used to quantify the uncertainty due to the Monte-Carlo integrations. We recommend to set `nboot = 100`. - `conf`: a numeric representing the confidence intervals taking into account the uncertainty due to the bootstrap procedure and the Gaussian process samples. - `sequential`: a boolean. If `sequential=TRUE`, the procedure provides a new point where to perform a simulation. It is the one minimizing the sum of the MAIN effect estimate variances. The variance is taken with respect to the conditional Gaussian process. The new point is selected in the points `candidate`. - `candidate`: a matrix representing the candidate points where the best new point to be simulated is selected. The lines represent the points and the columns represent the dimension. - `sequential.tot`: a boolean. If `sequential.tot=TRUE`, the procedure provides a new point where to perform the simulation. It is the one minimizing the sum of the TOTAL effect estimate. The variance is taken with respect to the conditional Gaussian process. The new point is selected in the points `candidate`. - `max_iter`: a numeric giving the maximal number of iterations for the propagative Gibbs sampler. It is used to simulate the realizations of the Gaussian process. - `x`: an object of class S3 `"sobolGP"` obtaining from the procedure `sobolGP`. It stores the results of the Kriging-based global sensitivity analysis. - `tot`: a boolean. If `tot=TRUE`, the procedure ask provides a point relative to the uncertainty of the total Sobol' indices (instead of first order' ones). - `xpoint`: a matrix representing a new point added to the kriging model. - `y`: a numeric giving the response of the function at `xpoint`. - `newcandidate`: a matrix representing the new candidate points where the best point to be simulated is selected. If `newcandidate=NULL`, these points correspond to `candidate` without the new point `xpoint`. - ``...``: any other arguments to be passed ## Returns An object of class S3 `sobolGP`. * call : a list containing the arguments of the function `sobolGP` : * X1 : X1 * X2 : X2 * conf : conf * nboot : nboot * candidate : candidate * sequential : sequential * max_iter : max_iter * sequential.tot : sequential.tot * model : model * tot : tot * method : MCmethod * type : type * nsim : nsim * S : a list containing the results of the kriging-based sensitivity analysis for the MAIN effects: * mean : a matrix giving the mean of the Sobol index estimates. * var : a matrix giving the variance of the Sobol index estimates. * ci : a matrix giving the confidence intervals of the Sobol index estimates according to `conf`. * varPG : a matrix giving the variance of the Sobol index estimates due to the Gaussian process approximation. * varMC : a matrix giving the variance of the Sobol index estimates due to the Monte-Carlo integrations. * xnew : if `sequential=TRUE`, a matrix giving the point in `candidate` which is the best to simulate. * xnewi : if `sequential=TRUE`, an integer giving the index of the point in `candidate` which is the best to simulate. * T : a list containing the results of the kriging-based sensitivity analysis for the TOTAL effects: * mean : a matrix giving the mean of the Sobol index estimates. * var : a matrix giving the variance of the Sobol index estimates. * ci : a matrix giving the confidence intervals of the Sobol index estimates according to `conf`. * varPG : a matrix giving the variance of the Sobol index estimates due to the Gaussian process approximation. * varMC : a matrix giving the variance of the Sobol index estimates due to the Monte-Carlo integrations. * xnew : if `sequential.tot=TRUE`, a matrix giving the point in `candidate` which is the best to simulate. * xnewi : if `sequential.tot=TRUE`, an integer giving the index of the point in `candidate` which is the best to simulate. ## Details The function `ask` provides the new point where the function should be simulated. Furthermore, the function `tell` performs a new kriging-based sensitivity analysis when the point `x` with the corresponding observation `y` is added. ## References L. Le Gratiet, C. Cannamela and B. Iooss (2014), A Bayesian approach for global sensitivity analysis of (multifidelity) computer codes, SIAM/ASA J. Uncertainty Quantification 2-1, pp. 336-363. ## Author(s) Loic Le Gratiet, EDF R&D ## See Also `sobol`, `sobol2002`, `sobol2007`, `sobolEff`, `soboljansen`, sobolMultOut , km ## Examples ```r library(DiceKriging) #--------------------------------------# # kriging model building #--------------------------------------# d <- 2; n <- 16 design.fact <- expand.grid(x1=seq(0,1,length=4), x2=seq(0,1,length=4)) y <- apply(design.fact, 1, branin) m <- km(design=design.fact, response=y) #--------------------------------------# # sobol samples & candidate points #--------------------------------------# n <- 1000 X1 <- data.frame(matrix(runif(d * n), nrow = n)) X2 <- data.frame(matrix(runif(d * n), nrow = n)) candidate <- data.frame(matrix(runif(d * 100), nrow = 100)) #--------------------------------------# # Kriging-based Sobol #--------------------------------------# nsim <- 10 # put nsim <- 100 nboot <- 10 # put nboot <- 100 res <- sobolGP( model = m, type="UK", MCmethod="sobol", X1, X2, nsim = nsim, conf = 0.95, nboot = nboot, sequential = TRUE, candidate, sequential.tot=FALSE, max_iter = 1000 ) res plot(res) x <- ask(res) y <- branin(x) # The following line doesn't work (uncorrected bug: # unused argument in km(), passed by update(), eval(), tell.sobolGP() ??) #res.new <- tell(res,y,x) #res.new ```

sobolGP function