fit_GAI: GAI model fitting

In calliste-fagard-jenkin/GAI: Generalised Abundance Index for Seasonal Invertibrates

GAI model fitting

Description

Fits the GAI model to a set of data, with a choice of normal, stopover or spline fits for the seasonal arrival times, as well as poisson, zero-inflated poisson, or negative binomially distribted count observations.

Usage

fit_GAI(
  start,
  DF,
  a_choice = "mixture",
  dist_choice = "P",
  options = list(),
  tol = 0.001,
  maxiter = 1000,
  verbose = F,
  hessian = F,
  bootstrap = NULL,
  method = "Nelder-Mead"
)

Arguments

start	The vector of start guesses for the parameters.
DF	The data.frame of observations. Should contain columns 'site', 'occasion' and 'count'. occasion and count should be integers, and missing entries in the count column are allowed to take the value NA. Any covariate which is referred to in a formula specified in the options argument should be present as a column in DF.
a_choice	Choice of flight path function, which describes the seasonal variation in counts over the monitoring period. Possible options are "mixture": A normal mixture, with as many components as desired, will be used to model the seasonal variation in counts. "stopover": The Matechou et al. (2014) stopver model for seasonal variation will be used. "splines": A general additive model, using splines, will model the seasonal variation. The degree and degrees of freedom of the splines can be specified in the 'options' argument.
dist_choice	The distribution for observed counts of individuals. "P" indicates a poisson distribution, "NB" a, negative binomial, and "ZIP", the zero-inflated poisson distribution.
options	A list containing different specifications, which vary depending on the model. For stopover and mixture models this contains B (the number of broods), shared_sigma (boolean denoting if the SDs are the same for each component), mu_formula (specifying a formula which describes a covariate dependency for the mean arrival times for each brood), and sd_formula (similar, for the SD of each brood). When splines are being used, options 'degree' and 'DF' can be included to specify the degree of the polynomial used by the splines, and the total degrees of freedom of the seasonal flight path model, respectively.
tol	The tolerance for the NB and ZIP iterative solvers. The solver stops when the difference between the negative log likelihood from one iteration to the next falls beneath this threshold.
maxiter	The maximum number of iterations to perform when iterating for the NB or ZIP likelihoods
verbose	If TRUE, the function will print various updates while it iterates for NB and for ZIP models.
hessian	if TRUE, refits the model one last time with hessian = TRUE in optim, usually so that this can be used to conduct a bootstrap
bootstrap	Always NULL for the user.. Internally, bootstraps use this argument to pass in sanitised precalculations to speed up the refitting process of 'refit-the-model' bootstraps
method	A character for the method which should be used to find MLEs. See optim documentation for options and further detail. SANN (simulated annealing) can be a good method of fine-tuning starting points, if one is afraid their MLEs are caught in a local maximum.

Value

The output of the 'fit_GAI' function is a list with a few important elements. The 'par' element gives named estimates of the MLEs for the model parameters, with 'value' giving the value of the negative log likelihood evaluated at the MLEs. 'counts', 'convergence', 'message' and 'hessian' are all standard outputs given by the 'optim' function with details on the numerical process of estimating the MLEs. 'spline_specs' contains the user-specified options for fitting splines, and will be an empty list for mixture and stopover models. 'dist_choice' and 'a_choice' contain the count distribution and flight path distributions, respectively. 'skeleton' contains the skeleton list of parameter values that the package uses to fit the model, with 'options' being the list of options passed to 'fit_GAI'. 'maxiter' refers to the maximum number of iterations used to estimate the MLEs of ZIP and NB models. 'A' and 'N' contain the matrix of estimated seasonal densities at each site and occasion, and the vector of estimated site totals, respectively. 'DMs' contains the list of design matrices used by the rGAI package to include the selected covariate formulas in the model. 'obs' contains the count observations in matrix form, with sites as rows and occasions as columns. This is the same format as for 'A'. 'DF' contains the original 'data.frame' supplied to 'fit_GAI', and finally, 'tol' specififies the stopping condition used for the model (an epsilon such that during an iterative process for fitting a ZIP or NB model, a difference of less than epsilon in the negative log likelihood between two iterations causes the process to terminate).

Examples

fit_GAI(rep(0, 3), example_data, a_choice = "stopover")
fit_GAI(rep(0, 6), example_data, a_choice = "mixture", options = list(B = 3))
fit_GAI(rep(0, 20), example_data, a_choice = "splines", options = list(df = 20, degree = 3))
fit_GAI(rep(0, 5), example_data, a_choice = "mixture", options = list(B = 2, shared_sigma = F))

calliste-fagard-jenkin/GAI documentation built on July 26, 2022, 11:20 a.m.