Title: | Multivariate Sensitivity Analysis |
---|---|
Description: | Functions to perform sensitivity analysis on a model with multivariate output. |
Authors: | Caroline Bidot <[email protected]>, Matieyendou Lamboni <[email protected]>, Hervé Monod <[email protected]> |
Maintainer: | Hervé Monod <[email protected]> |
License: | CeCILL-2 |
Version: | 2.1-1 |
Built: | 2024-12-10 06:36:04 UTC |
Source: | CRAN |
Sensitivity Analysis (SA) for models with multivariate output
This package generalises sensitivity analysis to simulation models with multivariate output. It makes it easy to run a series of independent sensitivity analyses on a set of output variables and to plot the results. Alternatively, it allows to apply sensitivity analyses to the variables resulting from the application of a multivariate method (such as PCA or splines or polynomial regression) to the output data (Lamboni et al., 2009).
The function multisensi
integrates all the different possible methods implemented in the package. Besides, the user may consider the functions which have existed since the first version of the package:
i) gsi
function for the Generalised Sensitivity Analysis (Lamboni et al., 2011, Xiao and Li, 2016) based on inertia decomposition. This method synthesizes the
information that is spread between the time outputs or between the
principal components and produces a unique sensitivity index for each
factor.
ii) gsi
function for the componentwise sensitivity analysis obtained by
computing sensitivity indices on principal components (Campbell et al., 2006)
iii) dynsi
function for the dynamic sensitivity analysis obtained by
computing sensitivity indices on each output variable.
In the first version of multisensi, sensitivity indices were based on using a factorial design and a classical ANOVA decomposition. It is now possible to use other methods for the design and for the sensitivity analysis.
Simulation model management
The multisensi package works on simulation models coded either in R or
using an external language (typically as an executable file). Models
coded in R must be either functions or objects that have a predict
method, such as lm objects. Models defined as functions will be called
once with an expression of the form y <- f(X)
where X
is a vector
containing a combination of levels of the input factors, and y
is the
output vector of length , where
is the number of output variables. If
the model is external to R, for instance a computational code, it must
be analyzed with the decoupled approach: the methods require an input
data frame (
X
) containing all the combinations of the input levels and
the outputs data frame (Y
) containing the response of the model
corresponding to these combinations. The size of X
is and the size
of
Y
is where
is the number of the input factor,
is the number
of the model outputs and
is the number of all the combinations of the
input levels. This approach can also be used on R models that do not
fit the required specifications.
Lamboni, M., Makowski, D., Monod, H., 2009. Multivariate global sensitivity analysis for dynamic crop models. Field Crops Research, volume 113, pp. 312-320.
Lamboni, M., Makowski, D., Monod, H., 2011. Multivariate sensitivity analysis to measure global contribution of input factors in dynamic models. Reliability Engineering & System Safety, volume 96, pp. 450-459.
Xiao, H., Li, L., 2016. Discussion of paper by M. Lamboni, H. Monod, D. Makowski Multivariate sensitivity analysis to measure global contribution of input factors in dynamic models, Reliab. Eng. Syst. Saf. 96 (2011) 450-459. Reliability Engineering & System Safety, volume 147, pp. 194-195.
Saltelli, A., Chan, K., Scott, E.M. eds, 2000. Sensitivity Analysis Wiley, New York.
The analysis.anoasg
function runs a series of analyses of variance on the columns of a data.frame, by using the aov
function.
analysis.anoasg(Y, plan, nbcomp = 2, sigma.car = NULL, analysis.args = list(formula = 2, keep.outputs = FALSE))
analysis.anoasg(Y, plan, nbcomp = 2, sigma.car = NULL, analysis.args = list(formula = 2, keep.outputs = FALSE))
Y |
a data.frame of output variables or principal components. |
plan |
a data.frame containing the design. |
nbcomp |
the number of |
sigma.car |
NULL or sum of squares of Y. If not NULL, compute the Generalised Sensitivity Indices (saved in the last column of the data.frame mSI/tSI/iSI outputs. |
analysis.args |
a list of arguments. The |
A list containing:
SI |
data.frame of sensitivity indices |
mSI |
data.frame of first-order sensitivity indices |
tSI |
data.frame of total sensitivity indices |
iSI |
data.frame of interaction sensitivity indices |
inertia |
vector of Inertia explained by the variables |
indic.fact |
0-1 matrix to indicate the factors associated with each factorial effect |
Hpredict |
prediction of outputs |
outputkept |
if |
call.info |
list with first element |
# Test case : the Winter Wheat Dynamic Models (WWDM) # input factors design data(biomasseX) # output variables (precalculated to speed up the example) data(biomasseY) res <- analysis.anoasg(biomasseY, biomasseX, nbcomp = 2, sigma.car = NULL, analysis.args = list(formula = 2, keep.outputs = FALSE))
# Test case : the Winter Wheat Dynamic Models (WWDM) # input factors design data(biomasseX) # output variables (precalculated to speed up the example) data(biomasseY) res <- analysis.anoasg(biomasseY, biomasseX, nbcomp = 2, sigma.car = NULL, analysis.args = list(formula = 2, keep.outputs = FALSE))
The analysis.sensitivity
function runs a series of sensitivity analyses on the columns of a data.frame, using a method implemented in the sensitivity package.
analysis.sensitivity(Y, plan, nbcomp = 2, sigma.car = NULL, analysis.args = list(keep.outputs = FALSE))
analysis.sensitivity(Y, plan, nbcomp = 2, sigma.car = NULL, analysis.args = list(keep.outputs = FALSE))
Y |
a data.frame of output variables or principal components. |
plan |
an object containing the design. It must be created by a function from the sensitivity package with argument |
nbcomp |
the number of |
sigma.car |
NULL or sum of squares of Y. If not NULL, compute the Generalised Sensitivity Indices (saved in the last column of the data.frame mSI/tSI/iSI outputs. |
analysis.args |
a list of arguments. If it contains |
The argument plan
must be an object created by a method implemented in the sensitivity package. Thus it belongs to a class such as morris
or fast99
. The name of the class is stored in the element call.info$fct
of the output returned by analysis.sensitivity
.
A list containing:
SI |
data.frame of sensitivity indices or other importance measures returned by the function from the sensitivity package used. Sometimes empty but kept for compatibility reasons. |
mSI |
data.frame of first-order sensitivity indices |
tSI |
data.frame of total sensitivity indices |
iSI |
data.frame of interaction sensitivity indices |
inertia |
empty (kept for compatibility reasons) |
indic.fact |
0-1 matrix to indicate the factors associated with each factorial effect |
Hpredict |
empty (kept for compatibility reasons) |
outputkept |
if |
call.info |
list with first element |
# Test case : the Winter Wheat Dynamic Models (WWDM) library(sensitivity) # to use fast99 # input factors design data(biomasseX) # input climate variable data(Climat) # example of the sensitivity:fast99 function # design newplan <- fast99(model = NULL, factors = names(biomasseX), n = 100, q = "qunif", q.arg = list(list(min = 0.9, max = 2.8), list(min = 0.9, max = 0.99), list(min = 0.6, max = 0.8), list(min = 3, max = 12), list(min = 0.0035, max = 0.01), list(min = 0.0011, max = 0.0025), list(min = 700, max = 1100))) # simulations wwdm.Y <- simulmodel(model=biomasse, plan=newplan$X, climdata=Climat) # analysis res <- analysis.sensitivity(data.frame(wwdm.Y), plan=newplan, nbcomp=4)
# Test case : the Winter Wheat Dynamic Models (WWDM) library(sensitivity) # to use fast99 # input factors design data(biomasseX) # input climate variable data(Climat) # example of the sensitivity:fast99 function # design newplan <- fast99(model = NULL, factors = names(biomasseX), n = 100, q = "qunif", q.arg = list(list(min = 0.9, max = 2.8), list(min = 0.9, max = 0.99), list(min = 0.6, max = 0.8), list(min = 3, max = 12), list(min = 0.0035, max = 0.01), list(min = 0.0011, max = 0.0025), list(min = 700, max = 1100))) # simulations wwdm.Y <- simulmodel(model=biomasse, plan=newplan$X, climdata=Climat) # analysis res <- analysis.sensitivity(data.frame(wwdm.Y), plan=newplan, nbcomp=4)
The basis.ACP
function decomposes a multivariate data set according to principal components analysis.
basis.ACP(simuls, basis.args = list())
basis.ACP(simuls, basis.args = list())
simuls |
a data.frame of size |
basis.args |
an empty list of arguments for the PCA decomposition. |
This function uses prcomp
.
H |
a data.frame of size |
L |
a matrix of size |
call.info |
list with the element |
data(biomasseY) res <- basis.ACP(biomasseY)
data(biomasseY) res <- basis.ACP(biomasseY)
The basis.bsplines
function decomposes a multivariate data set on a B-spline basis defined by its knots and mdegree parameters.
basis.bsplines(simuls, basis.args = list(knots = 5, mdegree = 3))
basis.bsplines(simuls, basis.args = list(knots = 5, mdegree = 3))
simuls |
a data.frame of size |
basis.args |
a list of arguments for the B-spline decomposition. The |
The optional x.coord
element of the list in basis.args
can
be used to specify the support of the B-spline decomposition, if
different from 1:T
. It must be a vector of length T
.
H |
a data.frame of size |
L |
a matrix of size |
call.info |
list with the element |
data(biomasseY) res <- basis.bsplines(biomasseY,basis.args=list(knots=7,mdegree=3))
data(biomasseY) res <- basis.bsplines(biomasseY,basis.args=list(knots=7,mdegree=3))
The basis.mine
function decomposes a multivariate data set on a user-defined basis.
basis.mine(simuls, basis.args = list( baseL=1*outer(sort(0:(ncol(simuls)-1)%%5),0:4,"==") ) )
basis.mine(simuls, basis.args = list( baseL=1*outer(sort(0:(ncol(simuls)-1)%%5),0:4,"==") ) )
simuls |
a data.frame of size |
basis.args |
a list of arguments for the polynomial decomposition. The |
The default basis.args
argument generates a projection on a moving-average basis. But if in the multisensi
function this basis.args
argument is not given for reduction=basis.mine
, the execution will be stopped.
H |
a data.frame of size |
L |
a matrix of size |
call.info |
list with the element |
data(biomasseY) M <- 1*outer(sort(0:(ncol(biomasseY)-1)%%5),0:4,"==") norm.M <- sqrt(colSums(M^2)) for (i in 1:ncol(M)){ M[,i]=M[,i]/norm.M[i] } res <- basis.mine(biomasseY, basis.args=list(baseL=M))
data(biomasseY) M <- 1*outer(sort(0:(ncol(biomasseY)-1)%%5),0:4,"==") norm.M <- sqrt(colSums(M^2)) for (i in 1:ncol(M)){ M[,i]=M[,i]/norm.M[i] } res <- basis.mine(biomasseY, basis.args=list(baseL=M))
The basis.osplines
function decomposes a multivariate data set on an orthogonalised B-spline (or O-spline) basis defined by its knots and mdegree parameters.
basis.osplines(simuls, basis.args = list(knots = 5, mdegree = 3))
basis.osplines(simuls, basis.args = list(knots = 5, mdegree = 3))
simuls |
a data.frame of size |
basis.args |
a list of arguments for the O-spline decomposition. The |
The optional x.coord
element of the list in basis.args
can be used to specify the support of the O-spline decomposition, if different from 1:T
. It must be a vector of length T
.
H |
a data.frame of size |
L |
a matrix of size |
call.info |
list with the element |
data(biomasseY) res <- basis.osplines(biomasseY,basis.args=list(knots=7,mdegree=3))
data(biomasseY) res <- basis.osplines(biomasseY,basis.args=list(knots=7,mdegree=3))
The basis.poly
function decomposes a multivariate data set on a polynomial basis.
basis.poly(simuls, basis.args = list(degree = 3))
basis.poly(simuls, basis.args = list(degree = 3))
simuls |
a data.frame of size |
basis.args |
a list of arguments for the polynomial decomposition. The |
This function uses poly
. The optional x.coord
element of the list in basis.args
can be used to specify the support of the polynomial decomposition, if different from 1:T
. It must be a vector of length T
.
H |
a data.frame of size |
L |
a matrix of size |
call.info |
list with the element |
data(biomasseY) res <- basis.poly(biomasseY,basis.args=list(degree=3))
data(biomasseY) res <- basis.poly(biomasseY,basis.args=list(degree=3))
The Winter Wheat Dynamic Model, a toy model to illustrate the main multisensi methods
biomasse(input, climdata, annee = 3)
biomasse(input, climdata, annee = 3)
input |
vector of input values. |
annee |
year. |
climdata |
a meteorological data.frame specific to biomasse. |
The Winter Wheat Dry Matter model (WWDM) is a dynamic crop model
running at a daily time step (Makowski et al, 2004). It has two state
variables, the above-ground winter wheat dry matter , in
and the leaf area index LAI(
) with
the day number from sowing
(
) to harvest (
). In the multisensi package implementation, the
biomasse
function simulates the output for only one parameter set (the
first row of input
if it is a matrix or a data.frame).
a vector of daily dry matter increase of the Winter Wheat biomass, over 223 days
Makowski, D., Jeuffroy, M.-H., Gu\'erif, M., 2004 Bayesian methods for updating crop model predictions, applications for predicting biomass and grain protein content. In: Bayesian Statistics and Quality Modelling in the Agro-Food Production Chain (van Boeakel et al. eds), pp. 57-68. Kluwer, Dordrecht
Monod, H., Naud, C., Makowski, D., 2006 Uncertainty and sensitivity analysis for crop models. In: Working with Dynamic Crop Models (Wallach D., Makowski D. and Jones J. eds), pp. 55-100. Elsevier, Amsterdam
Factorial design (resolution V) data for the 7 WWDM model input factors
data(biomasseX)
data(biomasseX)
A data frame with 2187 observations on the following 7 variables.
Eb
First WWDM input factor name
Eimax
Second WWDM input factor name
K
Thirth WWDM input factor name
Lmax
Fourth WWDM input factor name
A
Fifth WWDM input factor name
B
Sixth WWDM input factor name
TI
Seventh WWDM input factor name
data(biomasseX) ## maybe str(biomasseX) ; plot(biomasseX) ...
data(biomasseX) ## maybe str(biomasseX) ; plot(biomasseX) ...
Simplified output of the biomasse model (one column per decade), especially generated for examples in the package help files
data(biomasseY)
data(biomasseY)
A data frame with 2187 rows and 22 output variables (one per decade).
data(biomasseY) dim(biomasseY)
data(biomasseY) dim(biomasseY)
The bspline
function evaluates ith B-spline basis function of order m at the values in x, given knot locations in k
bspline(x = seq(0, 1, len = 101), k = knots, i = 1, m = 2)
bspline(x = seq(0, 1, len = 101), k = knots, i = 1, m = 2)
x |
vector or scalar, coordinate where to calculate the B-spline functions |
k |
vector of knot locations |
i |
integer; from 0 to length(knots)+1-m |
m |
integer, degree of the B-Splines |
B-splines are defined by recursion :
if
; 0 else.
values in x of the ith B-spline basis function of order m
This is essentially an internal function for the multisensi package
Wood Simon, 2006. Generalized Additive Models: An Introduction with R Chapman and Hall/CRC.
Climate data for the WWDM model (needed by the biomasse
function)
data(Climat)
data(Climat)
A data frame with 3126 observations on the following 4 variables.
ANNEE
a factor with levels 1 to 14, indicating 14 different years
RG
daily radiation variable
Tmin
daily maximum temperature
Tmax
daily minimum temperature
Makowski, D., Jeuffroy, M.-H., Gu\'erif, M., 2004 Bayesian methods for updating crop model predictions, applications for predicting biomass and grain protein content. In: Bayesian Statistics and Quality Modelling in the Agro-Food Production Chain (van Boeakel et al. eds), pp. 57-68. Kluwer, Dordrecht.
Monod, H., Naud, C., Makowski, D., 2006 Uncertainty and sensitivity analysis for crop models. In: Working with Dynamic Crop Models (Wallach D., Makowski D. and Jones J. eds), pp. 55-100. Elsevier, Amsterdam
dynsi implements the Dynamic Sensitivity Indices. This method allows to compute classical Sensitivity Indices on each output variable of a dynamic or multivariate model by using the ANOVA decomposition
dynsi(formula, model, factors, cumul = FALSE, simulonly=FALSE, nb.outp = NULL, Name.File=NULL, ...)
dynsi(formula, model, factors, cumul = FALSE, simulonly=FALSE, nb.outp = NULL, Name.File=NULL, ...)
formula |
ANOVA formula like |
model |
output data.frame OR the name of the R-function which calculates the model output. The only argument of this function must be a vector containing the input factors values. |
factors |
input data.frame (the design) if model is a data.frame
OR a list of factors levels such as
|
cumul |
logical value. If TRUE the sensitivity analysis will be done on the cumalative outputs. |
simulonly |
logical value. If TRUE the program stops after calculating the design and the model outputs. |
nb.outp |
The first nb.outp number of model outputs to be considered. If NULL all the outputs are considered. |
Name.File |
optional name of a R script file containing the
R-function that calculates the simulation model. e.g |
... |
possible fixed parameters of the model function. |
If factors
is a list of factors, the dynsi function generates a complete
factorial design. If it is a data.frame, dynsi expects that each column is
associated with an input factor.
dynsi returns a list of class "dynsi" containing the following components:
X |
a data.frame containing the experimental design (input samples) |
Y |
a data.frame containing the output (response) |
SI |
a data.frame containing the Sensitivity Indices (SI) on each output variable of the model and the Generalised SI (GSI) |
mSI |
a data.frame of first order SI on each output variable and first order GSI |
tSI |
a data.frame containing the total SI on each output variable and the total GSI |
iSI |
a data.frame of interaction SI on each output variable and interaction GSI |
Att |
0-1 matrix of association between input factors and factorial terms in the anovas |
call.info |
a list containing informations on the process (reduction=NULL, analysis, fct, call) |
inputdesign |
either the input data.frame or the sensitivity object used |
outputs |
a list of results on each output variable |
...
This function can now be replaced by a call to the multisensi
function. It is kept for compatibility with Version 1 of the multisensi package.
M. Lamboni, D. Makowski and H. Monod, 2009. Multivariate global sensitivity analysis for dynamic crop models. Field Crops Research, 113, 312-320.
A. Saltelli, K. Chan and E. M. Scott eds, 2000. Sensitivity Analysis. Wiley, New York.
# Test case : the Winter Wheat Dynamic Models (WWDM) # input factors design, data(biomasseX) # input Climate variables data(Climat) # output variables (precalculated to speed up the example) data(biomasseY) # DYNSI <- dynsi(2, biomasseY, biomasseX) summary(DYNSI) print(DYNSI) plot(DYNSI, color=heat.colors) #graph.bar(DYNSI,col=1, beside=F) # sensitivity bar plot # for the first output (col=1) #graph.bar(DYNSI,col=2, xmax=1) #
# Test case : the Winter Wheat Dynamic Models (WWDM) # input factors design, data(biomasseX) # input Climate variables data(Climat) # output variables (precalculated to speed up the example) data(biomasseY) # DYNSI <- dynsi(2, biomasseY, biomasseX) summary(DYNSI) print(DYNSI) plot(DYNSI, color=heat.colors) #graph.bar(DYNSI,col=1, beside=F) # sensitivity bar plot # for the first output (col=1) #graph.bar(DYNSI,col=2, xmax=1) #
A function that plots sensitivity indices by a bar graph
graph.bar(x, col = 1, nb.plot = 15, xmax = NULL, beside = TRUE, xlab = NULL, ...)
graph.bar(x, col = 1, nb.plot = 15, xmax = NULL, beside = TRUE, xlab = NULL, ...)
x |
an object of class gsi or dynsi |
col |
the column number of GSI to represent in the bar graph |
nb.plot |
number of input factors to be considered |
xmax |
a user-defined maximal |
beside |
if TRUE, the main and total sensitivity indices are represented by two bars; if FALSE, they are represented by the same bar |
xlab |
a label for the x axis |
... |
graphical parameters |
A function that plots the Principal Components (PCs) and the sensitivity indices on each PC
graph.pc(x, nb.plot = 15, nb.comp = NULL, xmax = NULL, beside = TRUE, cor.plot=FALSE, xtick=TRUE, type="l", ...)
graph.pc(x, nb.plot = 15, nb.comp = NULL, xmax = NULL, beside = TRUE, cor.plot=FALSE, xtick=TRUE, type="l", ...)
x |
gsi object. |
nb.plot |
number of input factors to be considered. |
nb.comp |
number of PCs. |
xmax |
a user-defined maximal |
beside |
if TRUE, the main and total sensitivity indices are represented by two bars; if FALSE, they are represented by the same bar. |
cor.plot |
if TRUE a correlation graph is made to represent the PCs ; if FALSE (default) a functionnal boxplot of the PCs is plotted. |
xtick |
if TRUE, put column names of outputs (Y) as ticks for the x axis. |
type |
what type of plot should be drawn for correlation graph ("l" for lines). |
... |
graphical parameters. |
An obsolete function that computed the GSI of a group factor as one factor
grpe.gsi(GSI, fact.interet)
grpe.gsi(GSI, fact.interet)
GSI |
a gsi or dynsi object |
fact.interet |
input factor to be grouped |
This is essentially an internal function for the multisensi package
The gsi function implements the calculation of Generalised Sensitivity Indices. This method allows to compute a synthetic Sensitivity Index for the dynamic or multivariate models by using factorial designs and the MANOVA decomposition of inertia. It computes also the Sensitivity Indices on principal components
gsi(formula, model, factors, inertia = 0.95, normalized = TRUE, cumul = FALSE, simulonly = FALSE, Name.File = NULL, ...)
gsi(formula, model, factors, inertia = 0.95, normalized = TRUE, cumul = FALSE, simulonly = FALSE, Name.File = NULL, ...)
formula |
ANOVA formula like |
model |
output data.frame OR the name of the R-function which calculates the model output. The only argument of this function must be a vector containing the input factors values |
factors |
input data.frame (the design) if model is a data.frame
OR a list of factors levels such as :
|
inertia |
cumulated proportion of inertia (a scalar |
normalized |
logical value. TRUE (default) computes a normalized Principal Component analysis. |
cumul |
logical value. If TRUE the PCA will be done on the cumulative outputs |
simulonly |
logical value. If TRUE the program stops after calculating the design and the model outputs |
Name.File |
optional name of a R script file containing the
R-function that calculates the simulation model. e.g |
... |
possible fixed parameters of the model function |
If factors is a list of factors, the gsi function generates a complete factorial design. If it is a data.frame, gsi expects that each column is associated with an input factor.
gsi returns a list of class "gsi", containing all the input arguments detailed before, plus the following components:
X |
a data.frame containing the experimental design (input samples) |
Y |
a data.frame containing the output matrix (response) |
H |
a data.frame containing the principal components |
L |
a data.frame whose columns contain the basis eigenvectors (the variable loadings) |
lambda |
the variances of the principal components |
inertia |
vector of inertia percentages per PCs and global criterion |
cor |
a data.frame of correlation between PCs and outputs |
SI |
a data.frame containing the Sensitivity Indices (SI) on PCs and the Generalised SI (GSI) |
mSI |
a data.frame of first order SI on PCs and first order GSI |
tSI |
a data.frame containing the total SI on PCs and the total GSI |
iSI |
a data.frame of interaction SI on PCs and interaction GSI |
pred |
a data.frame containing the output predicted by the metamodel arising from the PCA and anova decompositions |
residuals |
a data.frame containing the residuals between actual and predicted outputs |
Rsquare |
vector of dynamic coefficient of determination |
Att |
0-1 matrix of association between input factors and factorial terms in the anovas |
scale |
logical value, see the arguments |
normalized |
logical value, see the arguments |
cumul |
logical value, see the arguments |
call.info |
a list containing informations on the process (reduction, analysis, fct, call) |
inputdesign |
either the input data.frame or the sensitivity object used |
outputs |
a list of results on each output variable |
...
This function can now be replaced by a call to the multisensi
function. It is kept for compatibility with Version 1 of the multisensi package.
M. Lamboni, D. Makowski and H. Monod, 2009. Multivariate global sensitivity analysis for dynamic crop models. Field Crops Research, volume 113. pp. 312-320
M. Lamboni, D. Makowski and H. Monod, 2009. Multivariate sensitivity analysis to measure global contribution of input factors in dynamic models. Submitted to Reliability Engineering and System Safety.
# Test case : the Winter Wheat Dynamic Models (WWDM) # input factors design data(biomasseX) # input climate variable data(Climat) # output variables (precalculated to speed up the example) data(biomasseY) # GSI <- gsi(2, biomasseY, biomasseX, inertia=3, normalized=TRUE, cumul=FALSE, climdata=Climat) summary(GSI) print(GSI) plot(x=GSI, beside=FALSE) #plot(GSI, nb.plot=4) # the 'nb.plot' most influent factors # are represented in the plots #plot(GSI,nb.comp=2, xmax=1) # nb.comp = number of principal components #plot(GSI,nb.comp=3, graph=1) # graph=1 for first figure; 2 for 2nd one # and 3 for 3rd one; or 1:3 etc. #graph.bar(GSI,col=1, beside=F) # sensitivity bar plot on the first PC #graph.bar(GSI,col=2, xmax=1) #
# Test case : the Winter Wheat Dynamic Models (WWDM) # input factors design data(biomasseX) # input climate variable data(Climat) # output variables (precalculated to speed up the example) data(biomasseY) # GSI <- gsi(2, biomasseY, biomasseX, inertia=3, normalized=TRUE, cumul=FALSE, climdata=Climat) summary(GSI) print(GSI) plot(x=GSI, beside=FALSE) #plot(GSI, nb.plot=4) # the 'nb.plot' most influent factors # are represented in the plots #plot(GSI,nb.comp=2, xmax=1) # nb.comp = number of principal components #plot(GSI,nb.comp=3, graph=1) # graph=1 for first figure; 2 for 2nd one # and 3 for 3rd one; or 1:3 etc. #graph.bar(GSI,col=1, beside=F) # sensitivity bar plot on the first PC #graph.bar(GSI,col=2, xmax=1) #
The multisensi
function can conduct the different steps of a multivariate sensitivity analysis (design, simulation, dimension reduction, analysis, plots). It includes different options for each of these steps.
multisensi(design = expand.grid, model, reduction = basis.ACP, dimension = 0.95, center = TRUE, scale = TRUE, analysis = analysis.anoasg, cumul = FALSE, simulonly = FALSE, Name.File = NULL, design.args = list(), basis.args = list(), analysis.args = list(), ...)
multisensi(design = expand.grid, model, reduction = basis.ACP, dimension = 0.95, center = TRUE, scale = TRUE, analysis = analysis.anoasg, cumul = FALSE, simulonly = FALSE, Name.File = NULL, design.args = list(), basis.args = list(), analysis.args = list(), ...)
design |
EITHER a function such as expand.grid to generate the design OR a data.frame of size |
model |
EITHER a function to run the model simulations OR a data.frame of size |
reduction |
EITHER a function to decompose the multivariate output on a basis of smaller dimension OR |
dimension |
EITHER the number of variables to analyse, specified by an integer or by the minimal proportion of inertia (a scalar < 1) to keep in the output decomposition OR a vector specifying a subset of columns in the output data.frame OR NULL if all variables must be analysed. |
center |
logical value. If TRUE (default value) the output variables are centred. |
scale |
logical value. If TRUE (default value) the output variables are normalized before applying the reduction function. |
analysis |
a function to run the sensitivity analysis. Additional information can be given in the |
cumul |
logical value. If TRUE the output variables are replaced by their cumulative sums. |
simulonly |
logical value. If TRUE the program stops after the model simulations. |
Name.File |
Name of file containing the R-function model. |
design.args |
a list of arguments for the function possibly given in the |
basis.args |
a list of arguments for the function given in the |
analysis.args |
a list of arguments for the function possibly given in the |
... |
optional parameters of the function possibly given in the |
an object of class dynsi
if reduction=NULL
, otherwise an object of class gsi
. See the functions dynsi
and gsi
for more information.
## Test case : the Winter Wheat Dynamic Models (WWDM) # input factors design data(biomasseX) # input climate variable data(Climat) # output variables (precalculated to speed up the example) data(biomasseY) # to do dynsi process # argument reduction=NULL resD <- multisensi(design=biomasseX, model=biomasseY, reduction=NULL, dimension=NULL, analysis=analysis.anoasg, analysis.args=list(formula=2,keep.outputs = FALSE)) summary(resD) # to do gsi process #------------ # with dimension reduction by PCA # argument reduction=basis.ACP resG1 <- multisensi(design=biomasseX, model=biomasseY, reduction=basis.ACP, dimension=0.95, analysis=analysis.anoasg, analysis.args=list(formula=2,keep.outputs = FALSE)) summary(resG1) plot(x=resG1, beside=FALSE) #------------ # with dimension reduction by o-splines basis # arguments reduction=basis.osplines # and basis.args=list(knots= ... , mdegree= ... ) resG2 <- multisensi(design=biomasseX, model=biomasseY, reduction=basis.osplines, dimension=NULL, center=FALSE, scale=FALSE, basis.args=list(knots=11, mdegree=3), analysis=analysis.anoasg, analysis.args=list(formula=2,keep.outputs = FALSE)) summary(resG2) #------------ library(sensitivity) # to use fast99 # with dimension reduction by o-splines basis # and sensitivity analysis with sensitivity:fast99 resG3 <- multisensi(design=fast99, model=biomasse, analysis=analysis.sensitivity, design.args=list(factors = names(biomasseX), n = 100, q = "qunif", q.arg = list(list(min = 0.9, max = 2.8), list(min = 0.9, max = 0.99), list(min = 0.6, max = 0.8), list(min = 3, max = 12), list(min = 0.0035, max = 0.01), list(min = 0.0011, max = 0.0025), list(min = 700, max = 1100))), climdata=Climat, reduction=basis.osplines, basis.args=list(knots=7, mdegree=3), center=FALSE,scale=FALSE,dimension=NULL) summary(resG3)
## Test case : the Winter Wheat Dynamic Models (WWDM) # input factors design data(biomasseX) # input climate variable data(Climat) # output variables (precalculated to speed up the example) data(biomasseY) # to do dynsi process # argument reduction=NULL resD <- multisensi(design=biomasseX, model=biomasseY, reduction=NULL, dimension=NULL, analysis=analysis.anoasg, analysis.args=list(formula=2,keep.outputs = FALSE)) summary(resD) # to do gsi process #------------ # with dimension reduction by PCA # argument reduction=basis.ACP resG1 <- multisensi(design=biomasseX, model=biomasseY, reduction=basis.ACP, dimension=0.95, analysis=analysis.anoasg, analysis.args=list(formula=2,keep.outputs = FALSE)) summary(resG1) plot(x=resG1, beside=FALSE) #------------ # with dimension reduction by o-splines basis # arguments reduction=basis.osplines # and basis.args=list(knots= ... , mdegree= ... ) resG2 <- multisensi(design=biomasseX, model=biomasseY, reduction=basis.osplines, dimension=NULL, center=FALSE, scale=FALSE, basis.args=list(knots=11, mdegree=3), analysis=analysis.anoasg, analysis.args=list(formula=2,keep.outputs = FALSE)) summary(resG2) #------------ library(sensitivity) # to use fast99 # with dimension reduction by o-splines basis # and sensitivity analysis with sensitivity:fast99 resG3 <- multisensi(design=fast99, model=biomasse, analysis=analysis.sensitivity, design.args=list(factors = names(biomasseX), n = 100, q = "qunif", q.arg = list(list(min = 0.9, max = 2.8), list(min = 0.9, max = 0.99), list(min = 0.6, max = 0.8), list(min = 3, max = 12), list(min = 0.0035, max = 0.01), list(min = 0.0011, max = 0.0025), list(min = 700, max = 1100))), climdata=Climat, reduction=basis.osplines, basis.args=list(knots=7, mdegree=3), center=FALSE,scale=FALSE,dimension=NULL) summary(resG3)
The function multivar
applies a multivariate method
to decompose the output variables on a given basis.
multivar(simuls, dimension = NULL, reduction, centered = TRUE, scale = TRUE, basis.args = list())
multivar(simuls, dimension = NULL, reduction, centered = TRUE, scale = TRUE, basis.args = list())
simuls |
a data.frame of size |
dimension |
the number of variables to analyse, specified by an integer (for example 3) or by the minimal proportion of inertia (for example 0.95) to keep in the output decomposition |
reduction |
a function to decompose the multivariate output on a basis of smaller dimension |
centered |
logical value. If TRUE the output variables are centred. |
scale |
logical value. If TRUE the output variables are normalized. |
basis.args |
a list of arguments for the function given in the |
A list containing:
H |
a data.frame of size |
L |
a matrix of size |
sdev |
standard deviations of the columns of |
nbcomp |
number of components kept from the decomposition |
SStot |
total sums of squares of the simulations (after application of |
centering |
either 0 or the column averages of |
scaling |
either 1 or |
sdY |
standard deviations of the columns of |
cor |
correlation matrix (L*sdev), of size |
scale |
kept in case the option scale has been changed in the function |
importance |
cumulated percentage of SS_H (sdev^2) with respect to SStot |
call.info |
list with the element |
basis.ACP
, basis.bsplines
, basis.poly
, basis.osplines
data(biomasseY) res <- multivar(biomasseY, dimension=0.95, reduction=basis.ACP)
data(biomasseY) res <- multivar(biomasseY, dimension=0.95, reduction=basis.ACP)
Function that generates a complete factorial design in lexical order
planfact(nb.niv, make.factor = TRUE)
planfact(nb.niv, make.factor = TRUE)
nb.niv |
vector containing the number of each input levels |
make.factor |
logical value. If TRUE the columns of the output are of class factor |
plan |
data frame of the complete factorial design |
This is essentially an internal function for the multisensi package
Computation of a complete factorial design for model input factors.
planfact.as(input)
planfact.as(input)
input |
list of factor levels |
comp2 |
complete factorial design of model input |
This is essentially an internal function for the multisensi
package. It is almost equivalent to the function expand.grid
.
Plot method for dynamic sensitivity results of class dynsi
## S3 method for class 'dynsi' plot(x, normalized=FALSE, text.tuning = NULL, shade=FALSE, color=NULL, xtick=TRUE, total.plot=FALSE, gsi.plot=TRUE, ...)
## S3 method for class 'dynsi' plot(x, normalized=FALSE, text.tuning = NULL, shade=FALSE, color=NULL, xtick=TRUE, total.plot=FALSE, gsi.plot=TRUE, ...)
x |
a dynsi object. |
normalized |
logical value, FALSE => SI plotted within var(Y). |
text.tuning |
NULL or a small integer to improve the position of input factor labels. |
shade |
if TRUE, put different shadings to enhance the different factorial effects in the plot (long). |
color |
a palette of colors to enhance the different
factorial effects in the plot (for example |
xtick |
if TRUE, put column names of outputs (Y) as ticks for the x axis. |
total.plot |
logical value, TRUE => a new plot is produced with the total SI. |
gsi.plot |
logical value, TRUE => a new plot is produced for the Generalised Sensitivity Indice. |
... |
graphical parameters. |
For labels that would be partly positioned outside the plot frame, the argument
"text.tuning" may allow to get a better positioning. If it is equal to
, say, these labels are moved by
positions inside the
frame, where 1 position corresponds to 1 output variable on the x-axis.
Plot method for generalised sensitivity analysis of class gsi
## S3 method for class 'gsi' plot(x, nb.plot = 10, nb.comp = 3, graph = 1:3, xmax=NULL, beside=TRUE, cor.plot=FALSE, xtick=TRUE, type="l",...)
## S3 method for class 'gsi' plot(x, nb.plot = 10, nb.comp = 3, graph = 1:3, xmax=NULL, beside=TRUE, cor.plot=FALSE, xtick=TRUE, type="l",...)
x |
a gsi object. |
nb.plot |
number of input factors to be considered. |
nb.comp |
number of Principal Components to be plotted. |
graph |
figures number: 1 or 2 or 3. 1 is for plotting the PCs and their sensitivity indices, 2 is for plotting the Generalised Sensitivity Indice, 3 is for plotting the Rsquare. |
xmax |
a user-defined maximal |
beside |
if TRUE, the main and total sensitivity indices are represented by two bars; if FALSE, they are represented by the same bar. |
cor.plot |
if TRUE a correlation graph is made to represent the PCs ; if FALSE (default) a functionnal boxplot of the PCs is plotted. |
xtick |
if TRUE, put column names of outputs (Y) as ticks for the x axis. |
type |
what type of plot should be drawn for correlation graph ("l" for lines). |
... |
graphical parameters. |
gsi
, multisensi
, graph.bar
, graph.pc
The function predict.gsi
generates predicted multivariate output for user-specified combinations of levels of the input factors.
## S3 method for class 'gsi' predict(object, newdata, ...)
## S3 method for class 'gsi' predict(object, newdata, ...)
object |
Object of class gsi. |
newdata |
An optional data frame in which to look for variables with which to predict. If omitted, the fitted values are used. need to be same factors and levels as for obtained the gsi object. |
... |
others parameters |
Only available if the gsi
object was obtained with analysis.anoasg and analysis.args$keep.outputs=TRUE.
a data.frame of predicted values for newdata
gsi
, multisensi
, analysis.anoasg
data(biomasseX) data(biomasseY) x=multisensi(design=biomasseX,model=biomasseY,basis=basis.ACP, analysis=analysis.anoasg, analysis.args=list(formula=2, keep.outputs=TRUE)) newdata=as.data.frame(apply(biomasseX,2,unique)) predict(x,newdata)
data(biomasseX) data(biomasseY) x=multisensi(design=biomasseX,model=biomasseY,basis=basis.ACP, analysis=analysis.anoasg, analysis.args=list(formula=2, keep.outputs=TRUE)) newdata=as.data.frame(apply(biomasseX,2,unique)) predict(x,newdata)
A function to print DYNSI results
## S3 method for class 'dynsi' print(x, ...)
## S3 method for class 'dynsi' print(x, ...)
x |
a dynsi object |
... |
print parameters |
function to print GSI results
## S3 method for class 'gsi' print(x, ...)
## S3 method for class 'gsi' print(x, ...)
x |
a gsi object |
... |
print parameters |
Function that computes the sensitivity quality after making some assumptions about the number of PCs and the number of interactions
quality(echsimul, echsimul.app)
quality(echsimul, echsimul.app)
echsimul |
model outputs |
echsimul.app |
Predicted model output |
A list with the following components:
mean of the residuals
biais
R-square
This is essentially an internal function for the multisensi package
The sesBsplinesNORM
evaluates B-Splines basis functions at some points.
sesBsplinesNORM(x = seq(0, 1, len = 101), knots = 5, m = 2)
sesBsplinesNORM(x = seq(0, 1, len = 101), knots = 5, m = 2)
x |
vector, coordinates where to calculate the B-spline functions |
knots |
number of knots or vector of knots locations |
m |
integer, degree of the B-Splines |
x |
as input |
bsplines |
matrix, values in x of all B-spline basis functions of order m |
knots |
vector of knots locations |
projecteur |
inverse matrix of |
This is essentially an internal function for the multisensi package
The sesBsplinesORTHONORM
evaluates O-Splines basis functions at some points.
sesBsplinesORTHONORM(x = seq(0, 1, len = 101), knots = 5, m = 2)
sesBsplinesORTHONORM(x = seq(0, 1, len = 101), knots = 5, m = 2)
x |
vector, coordinates where to calculate the B-spline functions |
knots |
number of knots or vector of knots locations |
m |
integer, degree of the B-Splines |
x |
as input |
osplines |
matrix, values in x of all O-spline basis functions of order m |
knots |
vector of knots locations |
projecteur |
inverse matrix of |
This is essentially an internal function for the multisensi package
Function that simulates the model outputs
simulmodel(model, plan, nomFic = NULL, verbose = FALSE, ...)
simulmodel(model, plan, nomFic = NULL, verbose = FALSE, ...)
model |
name of R-function |
plan |
data frame of input design |
nomFic |
name of file that contains the model function |
verbose |
verbose |
... |
... |
possible fixed parameters of the R-function
The model function must be a R-function. Models defined as functions
will be called once with an expression of the form y <- f(X)
where X
is
a vector containing a combination of levels of the input factors, and y
is the output vector of length , where
is the number of output
variables
data frame of model outputs
This is essentially an internal function for the multisensi package
Function to summarize the dynamic sensitivity results
## S3 method for class 'dynsi' summary(object, ...)
## S3 method for class 'dynsi' summary(object, ...)
object |
a dynsi object |
... |
summary parameters |
function to summarize the GSI results
## S3 method for class 'gsi' summary(object, ...)
## S3 method for class 'gsi' summary(object, ...)
object |
a GSI object |
... |
summary parameters |
A function that predicts the model output after PCA and aov analyses
yapprox(multivar.obj, nbcomp = 2, aov.obj)
yapprox(multivar.obj, nbcomp = 2, aov.obj)
multivar.obj |
output of the multivar function |
nbcomp |
number of columns |
aov.obj |
aov object |
model output predictions
This is essentially an internal function for the multisensi package