sens: Simple local sensitivity analysis
In dkneis/mcu: Model calibration utilities

Description Usage Arguments Value Note Author(s) Examples

Performs a simplistic local sensitivity analysis. Allows for a vector-valued objective function, that is, the sensitivity of multiple criteria with respect to parameters can be tested. See details below.

1	sens(fn, p, sort = TRUE, silent = TRUE, ...)

`fn`	Objective function. This function must accept as its first argument a named numeric vector of parameters. It must return a named numeric vector (which can be of length 1).
`p`	Data frame specifying the parameters' default values as well as the test values. There must be four columns: 'name', 'default', 'min', and 'max'.
`sort`	If `TRUE`, the result data frames are sorted to show the most sensitive parameters at the top.
`silent`	If `TRUE`, diagnostic messages are suppressed.
`...`	Additional arguments passed to function `fn`.

A list of data frames. The list length and the element names are determined by the return vector of fn. In the common case where fn returns a (named) scalar, the list is of length 1. The data frame at position i has the following columns:

name: Name of the parameter whose influence is being tested.
pmin: Lower test value of the parameter.
pmax: Upper test value of the parameter.
pdef: Default value of the parameter.
fmin: i'th element of the return value of fn, when called with the lower test value of the particular parameter.
fmax: i'th element of the return value of fn, when called with the upper test value of the particular parameter.
fdef: i'th element of the return value of fn, when called with the parameter's default. The result is identical in all rows.
rsMax: Maximum relative sensitivity. For each parameter, this is max(abs(fmax-fdef)/fdef, abs(fmin-fdef)/fdef).
mono: Logical. TRUE indicates that the value of fn's i'th element increases or decreases monotonocally, when the parameter is set to the lower, the default, and the upper limit. Hence, the lowest and highest function values occurs at/beyond the limits of the parameter ranges. FALSE indicates missing monotonicity, i.e. the lowest or highest function value is supposed to occur within the tested parameter range.

For a each parameter in p, function fn is called twice. In the two calls, the particular parameter is set to its lower and upper test value, respectively. All other parameters are fixed at their defaults. This procedure is applied to every parameter. In total, the sensitivity test requires 2 * nrow(p) + 1 evaluations of fn. The one additional evaluation is necessary to compute fn with default values for all parameters ('base scenario').

Lower and upper test values of the parameters can be constructed, for example, by multiplying the defaults with, say, 0.9 and 1.1. For this to work a parameter's default must not be zero.

David Kneis david.kneis@tu-dresden.de

# Sensitivity of parameters of a linear model
obs= data.frame(x=c(1,2), y=c(1,2))
model= function(p, x) { p["slope"] * x + p["intercept"] }
objfun= function(p, obs) { c(sse= sum((obs$y - model(p, obs$x))^2)) }
p= data.frame(
  name=c("slope","intercept"),
  default= c(1, 0),
  min= c(0.5, -1),
  max= c(2, 1)
)
sens(fn=objfun, p=p, obs=obs)

# Like above but for a vector-valued objective function
objfun= function(p, obs) { c(sse= sum((obs$y - model(p, obs$x))^2),
  mae= sum(abs(obs$y - model(p, obs$x)))) }
sens(fn=objfun, p=p, obs=obs)