FAMoS (version 0.1.0)

base.optim: Fit Parameters of a Model

Description

Given a specific model, base.optim fits the corresponding parameters and saves the output.

Usage

base.optim(binary, parms, fit.fn, nr.of.data, homedir, optim.runs = 5,
  information.criterion = "AICc", default.val = NULL,
  random.borders = 1, con.tol = 0.01, control.optim = list(maxit =
  1000), parscale.pars = FALSE, scaling = NULL, ...)

Arguments

binary

A vector containing zeroes and ones. Zero indicates that the corresponding parameter is not fitted.

parms

A named vector containing the initial values for optim. Must be in the same order as binary.

fit.fn

A cost function. Has to take the complete parameter vector as an input argument (needs to be named parms) and must return the corresponding negative log-likelihood (-2LL, see Burnham and Anderson 2002). The binary vector containing the information which parameters are fitted, can also be used by taking binary as an additional function input argument.

nr.of.data

The number of data points used for fitting.

homedir

A string giving the directory in which the result folders generated by famos are found.

optim.runs

The number of times that each model will be fitted by optim. Default to 5.

information.criterion

The information criterion the model selection will be based on. Options are "AICc", "AIC" and "BIC". Default to "AICc".

default.val

A named list containing the values that the non-fitted parameters should take. If NULL, all non-fitted parameters will be set to zero. Default values can be either given by a numeric value or by the name of the corresponding parameter the value should be inherited from (NOTE: In this case the corresponding parameter entry has to contain a numeric value). Default to NULL.

random.borders

The ranges from which the random initial parameter conditions for all optim.runs > 1 are sampled. Can be either given as a vector containing the relative deviations for all parameters or as a matrix containing in its first column the lower and in its second column the upper border values. Parameters are uniformly sampled based on runif. Default to 1 (100% deviation of all parameters). Alternatively, functions such as rnorm, rchisq, etc. can be used if the additional arguments are passed along as well.

con.tol

The relative convergence tolerance. famos will rerun optim until the relative improvement between the current and the last fit is less than con.tol. Default is set to 0.01, meaning the fitting will terminate if the improvement is less than 1% of the previous value.

control.optim

Control parameters passed along to optim. For more details, see optim.

parscale.pars

Logical. If TRUE (default), the parscale option will be used when fitting with optim. This is helpful, if the parameter values are on different scales.

scaling

Numeric vector determining how newly added model parameters are scaled. Only needed if parscale.pars is TRUE.

...

Additional parameters.

Value

Saves the results obtained from fitting the corresponding model parameters in the respective files, from which they can be accessed by the main function famos.

Details

The fitting routine of base.optim is based on the function optim. The number of fitting runs can be specified by the optim.runs parameter in the famos function. Here, the first fitting run takes the parameters supplied in parms as a starting condition, while all following fitting runs sample new initial sets according to a uniform distribution based on the intervals [parms - abs(parms), parms + abs(parms)]. Additionally, each fitting run is based on a while-loop that compares the outcome of the previous and the current fit. Each fitting run is terminated when the specified convergence tolerance con.tol is reached.

Examples

# NOT RUN {
future::plan(future::sequential)

#setting data
x.values <- 1:7
y.values <-  3^2 * x.values^2 - exp(2 * x.values)

#define initial parameter values and corresponding test function
inits <- c(p1 = 3, p2 = 4, p3 = -2, p4 = 2, p5 = 0)

cost_function <- function(parms, x.vals, y.vals){
 if(max(abs(parms)) > 5){
   return(NA)
 }
 with(as.list(c(parms)), {
   res <- p1*4 + p2^2*x.vals^2 + p3*sin(x.vals) + p4*x.vals - exp(p5*x.vals)
   diff <- sum((res - y.vals)^2)
 })
}

#create directories if needed
make.directories(getwd())

#optimise the model parameters
base.optim(binary = c(0,1,1,0,1),
           parms = inits,
           fit.fn = cost_function,
           nr.of.data = length(x.values),
           homedir = getwd(),
           x.vals = x.values,
           y.vals = y.values)
# }