ODEmorris.ODEnetwork {ODEsensitivity}

Morris Screening for Objects of Class ODEnetwork

Description

ODEmorris.ODEnetwork performs a sensitivity analysis for objects of class ODEnetwork using the Morris screening method. Package ODEnetwork is required for this function to work.

Usage

## S3 method for class 'ODEnetwork'
ODEmorris(mod, pars, times, binf = 0, bsup = 1,
  r = 500, design = list(type = "oat", levels = 10, grid.jump = 1),
  scale = TRUE, ode_method = "lsoda", parallel_eval = FALSE,
  parallel_eval_ncores = NA, ...)

Arguments

mod

[ODEnetwork]
list of class ODEnetwork.

pars

[character(k)]
names of the parameters to be included as input variables in Morris screening. All parameter names must be contained in names(ODEnetwork::createParamVec(mod)) and must not be derivable from other parameters supplied (e.g. "k.2.1" can be derived from "k.1.2", so supplying "k.1.2" suffices).

times

[numeric]
points of time at which the sensitivity analysis should be executed (vector of arbitrary length). The first point of time must be greater than zero.

binf

[character(1 or k)]
vector of lower borders of possible values for the k input parameters. If they are all equal, a single value can be set.

bsup

[character(1 or k)]
vector of upper borders of possible values for the k input parameters. If they are all equal, a single value can be set.

r

[integer(1)]
if of length 1, the number of repetitions of the design. If of length 2, a space-filling optimization of the sampling design is used, see morris. However, this space-filling optimization might lead to long runtimes, so length 1 is recommended for r. Defaults to 500.

design

[list]
a list specifying the design type and its parameters, cf. morris.

scale

[logical(1)]
if TRUE, scaling is done for the input design of experiments after building the design and before calculating the elementary effects, cf. morris. Defaults to TRUE, which is highly recommended if the factors have different orders of magnitude, see morris.

ode_method

[character(1)]
method to be used for solving the ODEs in situations where the solution has to be determined numerically, see ode for details. Defaults to "lsoda".

parallel_eval

[logical(1)]
logical indicating if the evaluation of the ODE model shall be performed parallelized.

parallel_eval_ncores

[integer(1)]
number of processor cores to be used for parallelization. Only applies if parallel_eval = TRUE. If set to NA (as per default) and parallel_eval = TRUE, 1 processor core is used.

...

further arguments passed to or from other methods.

Details

If the object of class ODEnetwork supplied for mod doesn't include any events, the solution of the ODE network is determined analytically using simuNetwork. In the presence of events, simuNetwork uses ode to solve the ODE network numerically.

The sensitivity analysis is done for all state variables and all timepoints simultaneously using morris from the package sensitivity.

For non-ODE models, values for r are typically between 10 and 50. However, much higher values are recommended for ODE models (the default is r = 500).

Value

List of class ODEmorris of length 2 * nrow(mod$state) containing in each element a matrix for one state variable (all components of the 2 state variables are analyzed independently). The matrices themselves contain the Morris screening results for all timepoints (rows: mu, mu.star and sigma for every parameter; columns: timepoints).

Note

In situations where the solution of the ODE model has to be determined numerically, it might be helpful to try another ODE-solver if the evaluation of the model function takes too long, (argument ode_method). The ode_methods "vode", "bdf", "bdf_d", "adams", "impAdams" and "impAdams_d" might be faster than the default "lsoda".

If morris throws a warning message stating "In ... keeping ... repetitions out of ...", try using a bigger number of levels in the design argument (only possible for OAT design).

Author(s)

Frank Weber

See Also

morris, plot.ODEmorris

Examples

##### A network of 4 mechanical oscillators connected in a circle #####
# Definition of the network using the package "ODEnetwork":
M_mat <- rep(2, 4)
K_mat <- diag(rep(2 * (2*pi*0.17)^2, 4))
K_mat[1, 2] <- K_mat[2, 3] <- 
  K_mat[3, 4] <- K_mat[1, 4] <- 2 * (2*pi*0.17)^2 / 10
D_mat <- diag(rep(0.05, 4))
library("ODEnetwork")
lfonet <- ODEnetwork(masses = M_mat, dampers = D_mat, springs = K_mat)
# The parameters to be included in the sensitivity analysis and their lower
# and upper boundaries:
LFOpars <- c("k.1", "k.2", "k.3", "k.4",
             "d.1", "d.2", "d.3", "d.4")
LFObinf <- c(rep(0.2, 4), rep(0.01, 4))
LFObsup <- c(rep(20, 4), rep(0.1, 4))
# Setting of the initial values of the state variables:
lfonet <- setState(lfonet, state1 = rep(2, 4), state2 = rep(0, 4))
# The timepoints of interest:
LFOtimes <- seq(25, 150, by = 2.5)
# Morris screening:
set.seed(283)
# Warning: The following code might take very long!

LFOres_morris <- ODEmorris(mod = lfonet,
                           pars = LFOpars,
                           times = LFOtimes,
                           binf = LFObinf,
                           bsup = LFObsup,
                           r = 500,
                           design = list(type = "oat", 
                                         levels = 10, grid.jump = 1),
                           scale = TRUE,
                           parallel_eval = TRUE,
                           parallel_eval_ncores = 2)