sensPlotMatrix: Plot sensitivity info as a matrix
In dkneis/mcu: Model calibration utilities

Description Usage Arguments Value Note Author(s) Examples

Plots the results of a sensitivity analysis carried out using sens as a matrix of symbols. The output can facilitate manual model calibration (see details below).

1	sensPlotMatrix(sout, thr = 0.9, xpars = TRUE)

`sout`	A list of data frames returned from a call to `sens`.
`thr`	A number in range 0 < thr < 1. This is used to pragmatically distinguish between highly sensitive and less sensitive parameters. `thr` specifies the minimum relative decrease in the value of the objective function to consider a particular varied parameter as highly sensitive. A value of, say, 0.9 means that a parameter is consired as highly sensitive if ftst/fdef <= 0.9, where ftst and fdef denote the output of the objective function for a test value and the default value of a parameter, respectively. Reasonable values are probably between 0.8 and 0.95.
`xpars`	Logical. Controls the plot's layout. If `TRUE`, the parameter names appear as column headers and the objective function(s) as row headers(s). If `FALSE`, the result matrix is transposed.

NULL.

Symbols in the created graphics have the following meaning:

Triangles pointing up: Parameter should be increased to/beyond the tested upper limit in order to reduce the value of the objective function. Filled/non-filled: Relative sensitivity is high/low.
Triangles pointing down: Parameter should be decreased to/beyond the tested lower limit in order to reduce the value of the objective function. Filled/non-filled: Relative sensitivity is high/low.
Diamond: Lowest value of the objective function does not (exclusively) occur at a boundary of the tested parameter range. Hence, the optimum parameter values may be inside that range. Filled/non-filled: Relative sensitivity is high/low.
Circle: Objective function is not sensitive to the parameter.
Cross: No information due to non-finite return values of the objective function.

Note that the analysis does not account for possible parameter interactions such as compensation effects. For the example (see below), the created plot suggests that the intercept should be decreased (although the true optimum value is 0). This is due to the fact that all test values for the slope are actually too high (true optimum at 1).

In cases with long names of parameters/functions, it will be necessary to adjust the plot margings accordingly (see example).

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),
  mae= sum(abs(obs$y - model(p, obs$x)))) }
p= data.frame(
  name=c("slope","intercept"),
  default= c(1.5, 0.1),
  min= c(1.1, -1),
  max= c(2, 1)
)
s= sens(fn=objfun, p=p, obs=obs)
omar= par("mar")
par(mar=c(0.5,6,10,0.5))
sensPlotMatrix(sout=s, thr=0.75, xpars=TRUE)
par(mar=omar)