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).
morris(model = NULL, factors, r, design, binf = 0, bsup = 1,
scale = TRUE, …)
# S3 method for morris
tell(x, y = NULL, …)
# S3 method for morris
print(x, …)
# S3 method for morris
plot(x, identify = FALSE, atpen = FALSE, y_col = NULL,
y_dim3 = NULL, …)
# S3 method for morris
plot3d(x, alpha = c(0.2, 0), sphere.size = 1, y_col = NULL,
y_dim3 = NULL)a function, or a model with a predict method,
defining the model to analyze.
an integer giving the number of factors, or a vector of character strings giving their names.
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. 2007). In this case, r1 is the
wanted design size, and r2 (\(> \code{r1}\))
is the size of the (bigger) population in which is extracted the
design (this can throw a warning, see below).
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 design, or a vector of integers for different
values for each factor.
grid.jump : either an integer specifying the number of
levels that are increased/decreased for computing the
elementary effects, or a vector of integers for different values
for each factor. If not given, it is set to grid.jump =
1. Notice that this default value of one does not follow
Morris's recommendation of
\(\texttt{levels} / 2\).
type = "simplex" for simplex-based design (Pujol
2009), with the parameter:
scale.factor : a numeric value, the homothety factor of
the (isometric) simplexes. Edges equal one with a scale factor
of one.
either an integer, specifying the minimum value for the factors, or a vector for different values for each factor.
either an integer, specifying the maximum value for the factors, or a vector for different values for each factor.
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 relatively to its corresponding bsup and binf.
a list of class "morris" storing the state of the
screening study (parameters, data, estimates).
a vector of model responses.
logical. If TRUE, the user selects with the
mouse the factors to label on the \((\mu^*,\sigma)\)
graph (see identify).
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 factor points). If FALSE (and identify = TRUE),
the labels are automatically adjusted to the lower, left, upper or right
side of the factor point. For further information, see
identify. Defaults to FALSE.
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 (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).
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 (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).
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.
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.
morris returns a list of class "morris", containing all
the input argument detailed before, plus the following components:
the matched call.
a data.frame containing the design of experiments.
either a vector, a matrix or a three-dimensional array of model
responses (depends on the output of model).
if y is 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.
Notice that the statistics of interest (\mumu, \mu^*mu* and \sigmasigma) are not stored. They can be printed by the print method, but to extract numerical values, one has to compute them with the following instructions: If x$y is a vector: mu <- apply(x$ee, 2, mean) mu.star <- apply(x$ee, 2, function(x) mean(abs(x))) sigma <- apply(x$ee, 2, sd)
If x$y is a matrix: mu <- apply(x$ee, 3, function(M){ apply(M, 2, mean) }) mu.star <- apply(abs(x$ee), 3, function(M){ apply(M, 2, mean) }) sigma <- apply(x$ee, 3, function(M){ apply(M, 2, sd) })
If x$y is a three-dimensional array: 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")
It is highly recommended to use the function with the argument scale = TRUE to avoid an uncorrect interpretation of factors that would have different orders of magnitude.
when generating the design of experiments, identical repetitions are removed, leading to a lower number than requested.
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).
When using the space-filling improvement (Campolongo et al. 2007) of the Morris design, we recommend to install before the "pracma" R package: its "distmat"" function makes running the function with a large number of initial estimates (r2) significantly faster (by accelerating the inter-point distances calculations).
This version of morris also supports matrices and three-dimensional
arrays as output of model.
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.
# NOT RUN {
# 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)
# }
# NOT RUN {
library(rgl)
plot3d.morris(x) # (requires the package 'rgl')
# }
# NOT RUN {
# 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