optim_apsimx: Optimize parameters in an APSIM Next Generation simulation
In apsimx: Inspect, Read, Edit and Run 'APSIM' "Next Generation" and 'APSIM' Classic

optim_apsimx

R Documentation

Optimize parameters in an APSIM Next Generation simulation

Description

It is a wrapper for running APSIM-X and optimizing parameters using optim

Usage

optim_apsimx(
  file,
  src.dir = ".",
  parm.paths,
  data,
  type = c("optim", "nloptr", "mcmc", "ucminf", "grid"),
  weights,
  index = "Date",
  parm.vector.index,
  replacement,
  root,
  initial.values,
  grid,
  ...
)

Arguments

`file`	file name to be run (the extension .apsimx is optional)
`src.dir`	directory containing the .apsimx file to be run (defaults to the current directory)
`parm.paths`	absolute or relative paths of the coefficients to be optimized. It is recommended that you use `inspect_apsimx` for this
`data`	data frame with the observed data. By default is assumes there is a 'Date' column for the index.
`type`	Type of optimization. For now, `optim`, and, if available, `nloptr` or ‘mcmc’ through `runMCMC`. Option ‘ucminf’ uses the `ucminf` function. If ‘type’ is ‘grid’, then a grid can be passed and no optimization will be performed.
`weights`	Weighting method or values for computing the residual sum of squares.
`index`	Index for filtering APSIM output. Typically, “Date”, but it can be c(“report”, “Date”) for multiple simulations
`parm.vector.index`	Index to optimize a specific element of a parameter vector. At the moment it is possible to only edit one element at a time. This is because there is a conflict when generating multiple elements in the candidate vector for the same parameter.
`replacement`	TRUE or FALSE for each parameter. Indicating whether it is part of the ‘replacement’ component. Its length should be equal to the length or ‘parm.paths’.
`root`	root argument for `edit_apsimx_replacement`
`initial.values`	(required) supply the initial values of the parameters. (Working on fixing this...). If the parameters to be optimized correspond to a single value, then a simple numeric vector can be supplied. If one or more of the parameters represent a vector in APSIM, then the initial values should be passed as a list. At the moment, it is not possible to check if these are appropriate (correct name and length).
`grid`	grid used when ‘type = grid’. Columns should be parameters and rows different values for those parameters.
`...`	additional arguments to be passed to the optimization algorithm. See `optim`

Details

Simple optimization for APSIM Next Generation

* At the moment it is required to provide starting values for the parameters of interest.

* It is suggested that you keep a backup of the original file. This function will edit and overwrite the file during the optimization.

* When you use the parm.vector.index you cannot edit two separate elements of a vector at the same time. This should be used to target a single element of a vector only. (I can add this feature in the future if it is justified.)

* Internally, the optimization is done around the scaled value of the initial parameter values. A value of 1 would correspond to the inital value of the parameter. The ‘lower’ and ‘upper’ (or ‘ub’ and ‘lb’) are also scaled to the initial values of the parameters. So, for example, if your initial value is 20 and you provide an upper bound of 5, it means that the actual upper value that you are allowing for is 100.

* I have tested other optimizers and packages, but I think these are enough for most purposes. I tried function stats::nlm (but it does not support bounds and it can fail), package 'optimx' is a bit messy and it does not provide sufficient additional functionality. Package 'ucminf' seems like a good alternative, but it did not perform better than the other ones.

Value

object of class ‘optim_apsim’, but really just a list with results from optim and additional information.

Note

When computing the objective function (residual sum-of-squares) different variables are combined. It is common to weight them since they are in different units. If the argument weights is not supplied no weighting is applied. It can be 'mean', 'variance' or a numeric vector of appropriate length.