Refits a previously fitted WHAM model a number of times with different initial parameter values
jitter_wham(
fit_RDS = NULL,
n_jitter = 10,
initial_vals = NULL,
which_rows = NULL,
do_parallel = TRUE,
n_cores = NULL,
res_dir = NULL,
wham_location = NULL,
test_dir = NULL
)(required) location of RDS file with fitted WHAM model.
the number of different starting locations on the likelihood surface to refit the model from. Default = 10.
(optional) matrix (n_jitter x n parameters) of starting values to use for jittering.
(optional) which rows of intial_vals to use for jittering. Useful if doing jitter fits in stages.
T/F whether to do jitter fits in parallel. Requires snowfall and parallel packages to be installed. Default = TRUE.
(optional) the number of cores to use for parallel fitting.
directory where to save individual files for each jitter refit. Useful if jittering for some reason crashes R. If not provided, no files will be saved.
(optional) location of WHAM package. Useful if not using the WHAM installation in the standard library location.
(optional) directory for package repository. To be used when the function is being called during package testing rather than an installed version of WHAM.
a list of two elements. First is the results which is a list (length = n_jitter) of lists with 3 elements: minimized negative log-likelihood, jitter MLEs, and gradient. Second element is the matrix of initial values for the jitters.
Because the likelihood surface of a specific model may not be monotone, optimization may result in a local maximum which can be dependent on the parameter
values used to start the optimization. It is considered good practice to check whether the optimization is consistent for a range of starting values.
There does not appear to be an approach that is both best and computationally efficient to do this check so, this function allows the user to provide the
alternative starting values for all fixed effects parameters to use in the jittering. When initial_vals is not provided, a default method is used
where n_jitter random draws from a MVN distribution with mean equal to the MLE from the fitted model and covariance matrix equal to that estimated for the
the MLEs.