base.optim: Fit Parameters of a Model
In FAMoS: A Flexible Algorithm for Model Selection

Description Usage Arguments Details Value Examples

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

base.optim(
  binary,
  parms,
  fit.fn,
  homedir,
  use.optim = TRUE,
  optim.runs = 1,
  default.val = NULL,
  random.borders = 1,
  con.tol = 0.01,
  control.optim = list(maxit = 1000),
  parscale.pars = FALSE,
  scaling = NULL,
  verbose = FALSE,
  ...
)

`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 must return a selection criterion value (e.g. AICc or BIC). The binary vector containing the information which parameters are fitted, can also be used by taking `binary` as an additional function input argument.
`homedir`	A string giving the directory in which the result folders generated by `famos` are found.
`use.optim`	Logical. If true, the cost function `fit.fn` will be fitted via `optim`. If FALSE, the cost function will only be evaluated.
`optim.runs`	The number of times that each model will be optimised. Default to 1. Numbers larger than 1 use random initial conditions (see `random.borders`).
`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.
`verbose`	Logical. If TRUE, FAMoS will output all details about the current fitting procedure.
`...`	Additional parameters.

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.

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.

#setting data
true.p2 <- 3
true.p5 <- 2
sim.data <- cbind.data.frame(range = 1:10,
                             y = true.p2^2 * (1:10)^2 - exp(true.p5 * (1:10)))

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

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

    #calculate AICC
    nr.par <- length(which(binary == 1))
    nr.data <- nrow(data)
    AICC <- diff + 2*nr.par + 2*nr.par*(nr.par + 1)/(nr.data - nr.par -1)

    return(AICC)
  })
}

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

#optimise the model parameters
base.optim(binary = c(0,1,1,0,1),
           parms = inits,
           fit.fn = cost_function,
           homedir = tempdir(),
           data = sim.data)

#delete tempdir
unlink(paste0(tempdir(),"/FAMoS-Results"), recursive = TRUE)