crwMLE | R Documentation |
The function uses the Kalman filter to estimate movement parameters in a state-space version of the continuous-time movement model. Separate models are specified for movement portion and the location error portion. Each model can depend on time indexed covariates. A “haul out” model where movement is allowed to completely stop, as well as, a random drift model can be fit with this function.
crwMLE(data, ...) ## Default S3 method: crwMLE( data, mov.model = ~1, err.model = NULL, activity = NULL, drift = FALSE, coord = c("x", "y"), proj = NULL, Time.name = "time", time.scale = NULL, theta = NULL, fixPar = NULL, method = "Nelder-Mead", control = NULL, constr = list(lower = -Inf, upper = Inf), prior = NULL, need.hess = TRUE, initialSANN = list(maxit = 200), attempts = 1, retrySD = 1, skip_check = FALSE, ... ) ## S3 method for class 'SpatialPoints' crwMLE( data, mov.model = ~1, err.model = NULL, activity = NULL, drift = FALSE, Time.name = "time", time.scale = NULL, theta = NULL, fixPar = NULL, method = "Nelder-Mead", control = NULL, constr = list(lower = -Inf, upper = Inf), prior = NULL, need.hess = TRUE, initialSANN = list(maxit = 200), attempts = 1, retrySD = 1, skip_check = FALSE, coord = NULL, ... ) ## S3 method for class 'sf' crwMLE( data, mov.model = ~1, err.model = NULL, activity = NULL, drift = FALSE, Time.name = "time", time.scale = NULL, theta = NULL, fixPar = NULL, method = "Nelder-Mead", control = NULL, constr = list(lower = -Inf, upper = Inf), prior = NULL, need.hess = TRUE, initialSANN = list(maxit = 200), attempts = 1, retrySD = 1, skip_check = FALSE, ... )
data |
a data set of location observations as a data.frame, tibble,
SpatialPointsDataFrame ('sp' package), or a data.frame of class 'sf' that
contains a geometry column of type |
... |
further arguments passed to or from other methods |
mov.model |
formula object specifying the time indexed covariates for movement parameters. |
err.model |
A 2-element list of formula objects specifying the time indexed covariates for location error parameters. |
activity |
formula object giving the covariate for the activity (i.e., stopped or fully moving) portion of the model. |
drift |
logical indicating whether or not to include a random
drift component. For most data this is usually not necessary. See |
coord |
A 2-vector of character values giving the names of the "X" and
"Y" coordinates in |
proj |
A valid epsg integer code or proj4string for |
Time.name |
character indicating name of the location time column. It is strongly preferred that this column be of type POSIXct and in UTC. |
time.scale |
character. Scale for conversion of POSIX time to numeric for modeling. Defaults to "hours" and most users will not need to change this. |
theta |
starting values for parameter optimization. |
fixPar |
Values of parameters which are held fixed to the given value. |
method |
Optimization method that is passed to |
control |
Control list which is passed to |
constr |
Named list with elements |
prior |
A function returning the log-density function of the parameter prior distribution. THIS MUST BE A FUNCTION OF ONLY THE FREE PARAMETERS. Any fixed parameters should not be included. |
need.hess |
A logical value which decides whether or not to evaluate the Hessian for parameter standard errors |
initialSANN |
Control list for |
attempts |
The number of times likelihood optimization will be attempted in cases where the fit does not converge or is otherwise non-valid |
retrySD |
optional user-provided standard deviation for adjusting starting values when attempts > 1. Default value is 1. |
skip_check |
Skip the likelihood optimization check and return the fitted values. Can be useful for debugging problem fits. |
A full model specification involves 4 components: a movement model, an
activity model, 2 location error models, and a drift indication. The
movement model (mov.model
) specifies how the movement parameters
should vary over time. This is a function of specified, time-indexed,
covariates. The movement parameters (sigma for velocity variation and beta
for velocity autocorrelation) are both modeled with a log link as par =
exp(eta), where eta is the linear predictor based on the covariates. The
err.model
specification is a list of 2 such models, one for
“X (longitude)” and one for “Y (latitude)” (in that order) location
error. If only one location error model is given, it is used for both
coordinates (parameter values as well). If drift.model
is set to
TRUE
, then, 2 additional parameters are estimated for the drift
process, a drift variance and a beta multiplier.
theta
and fixPar
are vectors with the appropriate number or
parameters. theta
contains only those parameters which are to be
estimated, while fixPar
contains all parameter values with NA
for parameters which are to be estimated.
The data set specified by data
must contain a numeric or POSIXct column which is
used as the time index for analysis. The column name is specified by the
Time.name
argument and it is strongly suggested that this column be of
POSIXct type and in UTC. If a POSIXct column is used it is internally converted to a
numeric vector with units of time.scale
. time.scale
defaults to
NULL and an appropriate option will be chosen ("seconds","minutes","days","weeks")
based on the median time interval. The user can override this by specifying one
of those time intervals directly. If a numeric time vector is used, then
the time.scale
is ignored and there
is no adjustment to the data. Also, for activity models, the
activity covariate must be between 0 and 1 inclusive, with 0 representing complete stop
of the animal (no true movement, however, location error can still occur) and 1
represent unhindered movement. The coordinate location should have NA
where no
location is recorded, but there is a change in the movement covariates.
The CTCRW models can be difficult to provide good initial values for
optimization. If initialSANN
is specified then simulated annealing is
used first to obtain starting values for the specified optimization method.
If simulated annealing is used first, then the returned init
list of
the crwFit object will be a list with the results of the simulated annealing
optimization.
The attempts
argument instructs crwMLE
to attempt a fit
multiple times. Each time, the fit is inspected for convergence, whether
the covariance matrix could be calculated, negative values in the diag
of the covariance matrix, or NA values in the standard errors. If, after
n attempts, the fit is still not valid a simpleError
object is
returned. Users should consider increasing the number of attempts OR
adjusting the standard deviation value for each attempt by setting
retrySD
. The default value for retrySD
is 1, but users may
need to increase or decrease to find a valid fit. Adjusting other
model parameters may also be required.
A list with the following elements:
par |
Parameter maximum likelihood estimates (including fixed parameters) |
estPar |
MLE without fixed parameters |
se |
Standard error of MLE |
ci |
95% confidence intervals for parameters |
Cmat |
Parameter covariance matrix |
loglik |
Maximized log-likelihood value |
aic |
Model AIC value |
coord |
Coordinate names provided for fitting |
fixPar |
Fixed parameter values provided |
convergence |
Indicator of convergence (0 = converged) |
message |
Messages given by |
activity |
Model provided for stopping variable |
drift |
Logical value indicating random drift model |
mov.model |
Model description for movement component |
err.model |
Model description for location error component |
n.par |
number of parameters |
nms |
parameter names |
n.mov |
number of movement parameters |
n.errX |
number or location error parameters for “longitude” error model |
n.errY |
number or location error parameters for “latitude” error model |
stop.mf |
covariate for stop indication in stopping models |
polar.coord |
Logical indicating coordinates are polar latitude and longitude |
init |
Initial values for parameter optimization |
data |
Original data.frame used to fit the model |
lower |
The lower parameter bounds |
upper |
The upper parameter bounds |
need.hess |
Logical value |
runTime |
Time used to fit model |
Devin S. Johnson, Josh M. London
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.