Learn R Programming

sensitivity (version 1.12.1)

morris: Morris's Elementary Effects Screening Method

Description

morris implements the Morris's elementary effects screening method (Morris 1991). This method, based on design of experiments, allows to identify the few important factors at a cost of $r \times (p+1)$ simulations (where $p$ is the number of factors). This implementation includes some improvements of the original method: space-filling optimization of the design (Campolongo et al. 2007) and simplex-based design (Pujol 2009).

Usage

morris(model = NULL, factors, r, design, binf = 0, bsup = 1,
       scale = TRUE, ...)
## S3 method for class 'morris':
tell(x, y = NULL, ...)
## S3 method for class 'morris':
print(x, ...)
## S3 method for class 'morris':
plot(x, identify = FALSE, atpen = FALSE, y_col = NULL, 
  y_dim3 = NULL, \dots)
## S3 method for class 'morris':
plot3d(x, alpha = c(0.2, 0), sphere.size = 1, y_col = NULL, 
  y_dim3 = NULL)

Arguments

model
a function, or a model with a predict method, defining the model to analyze.
factors
an integer giving the number of factors, or a vector of character strings giving their names.
r
either an integer giving the number of repetitions of the design, i.e. the number of elementary effect computed per factor, or a vector of two integers c(r1, r2) for the space-filling improvement (Campolongo et al.). In this ca
design
a list specifying the design type and its parameters:
  • type = "oat"for Morris's OAT design (Morris 1991), with the parameters:
    • levels: either an integer specifying the number of levels of the desi
binf
either an integer, specifying the minimum value for the factors, or a vector for different values for each factor.
bsup
either an integer, specifying the maximum value for the factors, or a vector for different values for each factor.
scale
logical. If TRUE, the input design of experiments is scaled after building the design and before computing the elementary effects so that all factors vary within the range [0,1]. For each factor, the scaling is done relativel
x
a list of class "morris" storing the state of the screening study (parameters, data, estimates).
y
a vector of model responses.
identify
logical. If TRUE, the user selects with the mouse the factors to label on the $(\mu^*,\sigma)$ graph (see identify).
atpen
logical. If TRUE (and identify = TRUE), the user-identified labels (more precisely: their lower-left corners) of the factors are plotted at the place where the user had clicked (if near enough to one of the fact
y_col
an integer defining the index of the column of x$y to be used for plotting the corresponding Morris statistics $\mu^*$ and $\sigma$ (only applies if x$y is a matrix or an array). If set to NULL (
y_dim3
an integer defining the index in the third dimension of x$y to be used for plotting the corresponding Morris statistics $\mu^*$ and $\sigma$ (only applies if x$y is an array). If set to NULL (a
alpha
a vector of three values between 0.0 (fully transparent) and 1.0 (opaque) (see rgl.material). The first value is for the cone, the second for the planes.
sphere.size
a numeric value, the scale factor for displaying the spheres.
...
for morris: any other arguments for model which are passed unchanged each time it is called. For plot.morris: arguments to be passed to plot.default.

Value

  • morris returns a list of class "morris", containing all the input argument detailed before, plus the following components:
  • callthe matched call.
  • Xa data.frame containing the design of experiments.
  • yeither a vector, a matrix or a three-dimensional array of model responses (depends on the output of model).
  • ee
    • ifyis a vector: a$(r \times p)$- matrix of elementary effects for all the factors.
    if y is a matrix: a $(r \times p \times ncol(y))$ - array of elementary effects for all the factors and all columns of y. if y is a three-dimensional array: a $(r \times p \times dim(y)[2] \times dim(y)[3])$ - array of elementary effects for all the factors and all elements of the second and third dimension of y.

eqn

$\sigma$

code

scale = TRUE

preformatted

mu <- sapply(1:dim(x$ee)[4], function(i){ apply(x$ee[, , , i, drop = FALSE], 3, function(M){ apply(M, 2, mean) }) }, simplify = "array") mu.star <- sapply(1:dim(x$ee)[4], function(i){ apply(abs(x$ee)[, , , i, drop = FALSE], 3, function(M){ apply(M, 2, mean) }) }, simplify = "array") sigma <- sapply(1:dim(x$ee)[4], function(i){ apply(x$ee[, , , i, drop = FALSE], 3, function(M){ apply(M, 2, sd) }) }, simplify = "array")

Details

plot.morris draws the $(\mu^*,\sigma)$ graph. plot3d.morris draws the $(\mu, \mu^*,\sigma)$ graph (requires the rgl package). On this graph, the points are in a domain bounded by a cone and two planes (application of the Cauchy-Schwarz inequality). This version of morris also supports matrices and three-dimensional arrays as output of model.

References

M. D. Morris, 1991, Factorial sampling plans for preliminary computational experiments, Technometrics, 33, 161--174. F. Campolongo, J. Cariboni and A. Saltelli, 2007, An effective screening design for sensitivity, Environmental Modelling & Software, 22, 1509--1518. G. Pujol, 2009, Simplex-based screening designs for estimating metamodels, Reliability Engineering and System Safety 94, 1156--1160.

Examples

Run this code
# Test case : the non-monotonic function of Morris
x <- morris(model = morris.fun, factors = 20, r = 4,
            design = list(type = "oat", levels = 5, grid.jump = 3))
print(x)
plot(x)
library(rgl)
plot3d.morris(x)  # (requires the package 'rgl')

# Only for demonstration purposes: a model function returning a matrix
morris.fun_matrix <- function(X){
  res_vector <- morris.fun(X)
  cbind(res_vector, 2 * res_vector)
}
x <- morris(model = morris.fun_matrix, factors = 20, r = 4,
            design = list(type = "oat", levels = 5, grid.jump = 3))
plot(x, y_col = 2)
title(main = "y_col = 2")

# Also only for demonstration purposes: a model function returning a
# three-dimensional array
morris.fun_array <- function(X){
  res_vector <- morris.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 <- morris(model = morris.fun_array, factors = 20, r = 4,
            design = list(type = "simplex", scale.factor = 1))
plot(x, y_col = 2, y_dim3 = 2)
title(main = "y_col = 2, y_dim3 = 2")

Run the code above in your browser using DataLab