mstrust: Non-Linear Optimization, multi start
In dMod: Dynamic Modeling and Parameter Estimation in ODE Models

Description Usage Arguments Details Value Author(s) See Also

Wrapper around trust allowing for multiple fits from randomly chosen initial values.

mstrust(
  objfun,
  center,
  studyname,
  rinit = 0.1,
  rmax = 10,
  fits = 20,
  cores = 1,
  samplefun = "rnorm",
  resultPath = ".",
  stats = FALSE,
  output = FALSE,
  ...
)

`objfun`	Objective function, see `trust`.
`center`	Parameter values around which the initial values for each fit are randomly sampled. The initial values handed to trust are the sum of center and the output of samplefun, center + samplefun. See `trust`, parinit. `center` Can also be a parframe, then the parameter values are taken from the parframe. In this case, the `fits` argument is overwritten. To use a reproducible set of initial guesses, generate center with `msParframe`
`studyname`	The names of the study or fit. This name is used to determine filenames for interim and final results. See Details.
`rinit`	Starting trust region radius, see `trust`.
`rmax`	Maximum allowed trust region radius, see `trust`.
`fits`	Number of fits (jobs).
`cores`	Number of cores for job parallelization.
`samplefun`	Function to sample random initial values. It is assumed, that samplefun has a named parameter "n" which defines how many random numbers are to be returned, such as for `rnorm` or `runif`. By default `rnorm` is used. Parameteres for samplefun are simply appended as named parameters to the mstrust call and automatically handed to samplefun by matching parameter names.
`resultPath`	character indicating the folder where the results should be stored. Defaults to ".".
`stats`	If true, the same summary statistic as written to the logfile is printed to command line on mstrust completion.
`output`	logical. If true, writes output to the disc.
`...`	Additional parameters handed to trust(), samplefun(), or the objective function by matching parameter names. All unmatched parameters are handed to the objective function objfun(). The log file starts with a table telling which parameter was assigend to which function.

By running multiple fits starting at randomly chosen inital parameters, the chisquare landscape can be explored using a deterministic optimizer. Here, trust is used for optimization. The standard procedure to obtain random initial values is to sample random variables from a uniform distribution (rnorm) and adding these to center. It is, however, possible, to employ any other sampling strategy by handing the respective function to mstrust(), samplefun.

In case a special sampling is required, a customized sampling function can be used. If, e.g., inital values leading to a non-physical systems are to be discarded upfront, the objective function can be addapted accordingly.

All started fits either lead to an error or complete converged or unconverged. A statistics about the return status of fits can be shown by setting stats to TRUE.

Fit final and intermediat results are stored under studyname. For each run of mstrust for the same study name, a folder under studyname of the form "trial-x-date" is created. "x" is the number of the trial, date is the current time stamp. In this folder, the intermediate results are stored. These intermediate results can be loaded by load.parlist. These are removed on successfull completion of mstrust. In this case, the final list of fit parameters (parameterList.Rda) and the fit log (mstrust.log) are found instead.

A parlist holding errored and converged fits.

Wolfgang Mader, Wolfgang.Mader@fdm.uni-freiburg.de

1. trust, for the used optimizer, 2. rnorm, runif for two common sampling functions, 3. msParframe for passing a reproducible set of random initial guesses to mstrust, 4. as.parframe for formatting the output to a handy table