crwMLE {crawl} | R Documentation |
The function uses the Kalman filter to estimate movement paramters 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(mov.model=~1, err.model, stop.model=NULL, drift.model=FALSE, data, coord=c("x", "y"), polar.coord=TRUE, Time.name, initial.state, theta, fixPar, method="L-BFGS-B", control=NULL, initialSANN=NULL, attempts=1)
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. |
stop.model |
formula object giving the covariate for the stopping portion of the model. |
drift.model |
logical indicating whether or not to include a random drift component. |
data |
data.frame object containg telemetry and covariate data. |
coord |
A 2-vector of character values giving the names of the
"X" and "Y" coordinates in data . |
polar.coord |
logical indicating location are in latitude and longitude. |
Time.name |
character indicating name of the location time column |
initial.state |
list object containg the inital state of the Kalman filter. |
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 optim . |
control |
Control list which is passed to optim . |
initialSANN |
Control list for optim when simulated
annealing is used for obtaining start values. See details |
attempts |
The number of times likelihood optimization will be attempted |
A full model specification involves 4 components: a movement model, a
stopping 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 “longitude” and one for “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. The inital.state
is a list with the following
elemets (with the exact names):
a1.y
A vector with initial state values for the
“latitude” coordinate. It have 2 elemets (location at time 1,
velocity at time 1) for non-drift models and 3 elemets for drift
models (location at time 1, velocity at time 1, drift velocity at time
1) for driftmodels,
P1.y
Covarince matrix for the state at time 1 (measure
of uncertainty for your inital state) a1.y
,
a1.x
Same as a1.y
, but in the “longitude”
coordinate,
P1.x
Same as P1.y
, but in the “longitude”
coordinate.
theta
and fixPar
are vectors with the appropriate number
or parameters. theta
contains only those paraemters 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 column
which is used as the time index for analysis. The column name is
specified by the Time.name
argument. Also, for stopping models,
the stopping covariate must be between 0 and 1 inclusive, with 1
representing complete stop of the animal (no true movement, however,
location error can still occur) and 0 represent unhindered
movement. The coordinate location should have NA
where no
location is recorded, but there is a change in the movment 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 optimaization 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.
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% confidance intervals for parameters |
Cmat |
Parameter covariance matrix |
loglik |
Maximized log-likelihood value |
aic |
Model AIC value |
initial.state |
Intial state provided to crwMLE for model
fitting |
coord |
Coordinate names provided for fitting |
fixPar |
Fixed parameter values provided |
convergence |
Indicator of convergence (0 = converged) |
message |
Meesages given by optim during parameter
optimization |
stop.model |
Model provided for stopping variable |
random.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 |
Character vector giving coordinate names in
data |
runTime |
Time used to fit model |
init |
Initial values for parameter optimization |
data |
Original data.frame used to fit the model |
Devin S. Johnson
northernFurSeal
for additional examples.
data(harborSeal) head(harborSeal) ## Calculate Log multipliers for Argos error argosClasses <- c("3", "2", "1", "0", "A", "B") ArgosMultFactors <- data.frame(Argos_loc_class=argosClasses, errX=log(c(1, 1.5, 4, 14, 5.21, 20.78)), errY=log(c(1, 1.5, 4, 14, 11.08, 31.03))) hsNew <- merge(harborSeal, ArgosMultFactors, by=c("Argos_loc_class"), all=TRUE) hsNew <- hsNew[order(hsNew$Time), ] head(hsNew) ## Initial state values initial.dry <- list( a1.x=c(harborSeal$longitude[1],0), a1.y=c(harborSeal$latitude[1],0), P1.x=diag(c(1,1)), P1.y=diag(c(1,1)) ) ##Fit model as given in Johnson et al. (2008) Ecology 89:1208-1215 fit1 <- crwMLE( mov.model=~1, err.model=list(x=~errX, y=~errY), stop.model=~DryTime, data=hsNew, coord=c("longitude","latitude"), Time.name="Time", initial.state=initial.dry, fixPar=c(NA, 1, NA, 1, NA, NA, NA), control=list(maxit=2000, trace=1, REPORT=1) ) fit1 str(fit1) ##Use simulated annealing to obtain start value fit2 <- crwMLE( mov.model=~1, err.model=list(x=~errX, y=~errY), stop.model=~DryTime, data=hsNew, coord=c("longitude","latitude"), Time.name="Time", initial.state=initial.dry, fixPar=c(NA, 1, NA, 1, NA, NA, NA), control=list(maxit=2000, trace=1, REPORT=1), initialSANN=list(maxit=100, temp=5, tmax=5, trace=1, REPORT=2) ) ##See simulated annealing start values fit2$init