Fit a FIMS model (BETA)
Usage
fit_fims(
input,
get_sd = TRUE,
save_sd = TRUE,
number_of_loops = 3,
optimize = TRUE,
number_of_newton_steps = 0,
control = list(eval.max = 10000, iter.max = 10000, trace = 0),
filename = NULL,
getReportCovariance = FALSE
)Arguments
- input
Input list as returned by
initialize_fims(). An optionalmapentry is a named list of factors forp(fixed effects) and/orre(random effects), in the order of the correspondingparametersvector. Each factor must have one entry per parameter.NAholds a parameter at its starting value; repeated levels share one estimated value. Shared entries must have identical starting values; otherwise, the error lists each parameter's name, 1-based index inporre, and initial value. Factor levels determine the reduced parameter order; unused levels are dropped. Levels inpandreare independent; sharing across these vectors is not supported.- get_sd
A boolean specifying if the
TMB::sdreport()should be calculated? It is skipped when the maximum gradient is above 0.01 or not finite, because standard errors far from the optimum are not meaningful.- save_sd
A logical, with the default
TRUE, indicating whether the sdreport is returned in the output. IfFALSE, the slot for the report will be empty.- number_of_loops
A positive integer specifying the number of iterations of the optimizer that will be performed to improve the gradient. The default is three, leading to four total optimization steps.
- optimize
Optimize (TRUE, default) or (FALSE) build and return a list containing the obj and report slot.
- number_of_newton_steps
The number of Newton steps using the inverse Hessian to do after optimization. Not yet implemented.
- control
A list of optimizer settings passed to
stats::nlminb(). The the default is a list of length three witheval.max = 1000,iter.max = 10000, andtrace = 0.- filename
Character string giving a file name to save the fitted object as an RDS object. Defaults to 'fit.RDS', and a value of NULL indicates not to save it. If specified, it must end in .RDS. The file is written to folder given by
input[["path"]]. Not yet implemented.- getReportCovariance
A logical passed to
TMB::sdreport(), with the defaultFALSE. Standard errors of all parameters and derived quantities are calculated either way. IfTRUE, the full covariance matrix of the derived quantities is also calculated and stored ascovin thesdreport; it grows with the square of the number of derived quantities and can use several GB of memory. IfFALSE,covisNA.
Value
An object of class FIMSFit is returned, where the structure is the same
regardless if optimize = TRUE or not. Uncertainty information is only
included in the estimates slot if get_sd = TRUE. The result of each
convergence check is stored on the object and returned by
get_convergence().
Details
This function is a beta version still and subject to change
without warning.
Mapped parameters are expanded to their full FIMS vectors for reporting.
Shared parameters receive the same estimate and standard error in
get_estimates(). Mapped-off parameters retain their starting values and
have NA standard errors. Gradients describe reduced fixed-effect
optimization variables and are reported only on the first full parameter
in each shared level. Parameter counts describe the reduced vectors.
With no active fixed effects, TMB evaluates the random-effects model without
running an outer optimizer. If no parameters remain active, use
optimize = FALSE.
A fit with random effects can need several GB of memory for a long time
series. If FIMS was installed with TMB 1.9.18 or later, running
TMB::config(tmbad.sparse_hessian_compress = 1, DLL = "FIMS") after
loading FIMS and before fit_fims() uses less memory but takes longer.
With 60 years of data built from data_big, peak memory fell from 2.2 GB
to 0.6 GB and the fit took twice as long. At the same parameter values the
objective, gradient and standard errors are the same to about 1e-12, but
the optimizer can stop at a slightly different point, so the convergence
checks can change. The setting lasts for the R session and does not reach
parallel workers.
