sensit: Sensitivity analysis
In dkneis/diatools: Utilities for Diagenetic Modeling

Description Usage Arguments Value Note Author(s) Examples

Evaluates a function for multiple parameter sets, optionally using parallel processing.

1 2	sensit(p, fn, n = 1, passIndex = FALSE, silent = FALSE, logfile = "", ...)

`p`	A numeric matrix representing the parameter sets to be tested. Each row represents a parameter set. Column names are interpreted as the names of the parameters.
`fn`	Function of interest. It must accept as its first argument a named numeric vector of parameters. See `passIndex` for the meaning of a possible second argument. There are no restrictions with respect to the return value of `fn`.
`n`	A positive integer specifying the number of child processes. It is passed as the first argument to `makeCluster`.
`passIndex`	Logical. If `TRUE`, function `fn` must accept as its second argument an integer value representing the index of the currently processed parameter set.
`silent`	Logical. Use this to suppress diagnostic messages.
`logfile`	Name of a file to collect output messages of child processes. If this is an empty string (default) output messages are likely to appear on the screen.
`...`	Additional arguments passed to function `fn`.

A list with the following components.

nFailed : The number of 'failed' runs. These are runs where fn triggered a warning or an error.
whichOK : A vector of length nrow(p) minus nFailed holding the numeric indices of the successful runs. It can be used to remove the 'abnormal' parameter sets from the input matrix p, e.g. p[whichOK,].
fnOut : A list where each element holds the return value of fn for a single parameter set. For example, fnOut[i] is the output from fn(p[i,], i, ...). Elements where fn generated a warning or error are automatically dropped, thus, the list is of the same length as the vector whichOK. It will often be necessary to transform the list into a more handy data structure, e.g. using the simplifyList utility.
cpu : A numeric vector holding the times spent on the successfull evaluations of fn. The vector has the same length as whichOK.
msg : A vector of length nrow(p) holding error or warning messages issued by fn. For the successful runs, this vector contains empty strings.

The function of interest is called as fn(p[i,], ...) or fn(p[i,], i, ...), depending on the value of passIndex. In the latter case, the index of the currently processed set is available within fn. This information can be used, for example, for diagnostic messages of for creating file names which are unique for each (possibly parallel) instance of fn.

The output of plotting commands within function fn will usually not appear on screen but it is redirected to some file. In general, it is better to save the required data and create the plots afterwards.

In any case, fn is executed within a tryCatch block. The occurrence of any error or warning is considered an exception and the evaluation of fn is aborted. The respective message is registered in the msg vector (see above).

Any data or functions needed within fn need to be passed explicitly using the ... argument. This is necessary to make the data / functions available to all parallel threads.

David Kneis david.kneis@tu-dresden.de

# Analysis of a model's goodness-of-fit
model= function(p, x) {
  if (p["b"] < 0)
    stop("negative argument for 'sqrt'") # to demonstrate handling of errors
  p["a"] * sqrt(x * p["b"])
}
# Observations
obs= cbind(x=1:50, y=model(c(a=1, b=0.1), 1:50))
# Objective function
mse= function(p, model, obs) { mean((obs[,"y"] - model(p, obs[,"x"]))^2) }
# Parameter sets to try
nSets= 10
p= cbind(a= seq(0, 2, length.out=nSets), b= seq(-0.2, 0.5, length.out=nSets))
# Evaluate obj. function for all sets
x= suppressWarnings(
  sensit(p=p, fn=mse, n=2, model=model, obs=obs, logfile=""))
# Show parameter sets that 'worked' together with results
print(cbind(setIndex=x$whichOK, p[x$whichOK,], mse=simplifyList(x$fnOut)))