Package 'crawl' reference manual

Title:	Fit Continuous-Time Correlated Random Walk Models to Animal Movement Data
Description:	Fit continuous-time correlated random walk models with time indexed covariates to animal telemetry data. The model is fit using the Kalman-filter on a state space version of the continuous-time stochastic movement process.
Authors:	Devin S. Johnson [aut, cre], Josh London [aut], Brett T. McClintock [ctb], Kenady Wilson [ctb]
Maintainer:	Devin S. Johnson <[email protected]>
License:	CC0
Version:	2.3.1
Built:	2024-11-02 05:43:14 UTC
Source:	https://github.com/NMML/crawl

Fit Continuous-Time Correlated Random Walk Models to Animal Movement Data

Description

The [C]orrelated [RA]ndom [W]alk [L]ibrary (I know it is not an R library, but, "crawp" did not sound as good) of R functions was designed for fitting continuous-time correlated random walk (CTCRW) models with time indexed covariates. The model is fit using the Kalman-Filter on a state space version of the continuous-time stochastic movement process.

Package:	crawl
Type:	Package
Version:	2.3.1
Date:	October 3, 2024
License:	CC0
LazyLoad:	yes

Note

This software package is developed and maintained by scientists at the NOAA Fisheries Alaska Fisheries Science Center and should be considered a fundamental research communication. The recommendations and conclusions presented here are those of the authors and this software should not be construed as official communication by NMFS, NOAA, or the U.S. Dept. of Commerce. In addition, reference to trade names does not imply endorsement by the National Marine Fisheries Service, NOAA. While the best efforts have been made to insure the highest quality, tools such as this are under constant development and are subject to change.

Author(s)

Josh London and Devin S. Johnson

Maintainer: Devin S. Johnson <[email protected]>

References

Johnson, D., J. London, M. -A. Lea, and J. Durban (2008) Continuous-time correlated random walk model for animal telemetry data. Ecology 89(5) 1208-1215.

Generic subset/bracket method for crwIS classes

Description

Generic subset/bracket method for crwIS classes

Usage

## S3 method for class 'crwIS'
x[i, ..., drop = TRUE]
## S3 method for class 'crwIS'
x[i, ..., drop = TRUE]

Arguments

`x`	crwIS object
`i`	elements to extract or replace. These are numeric or character or, empty or logical. Numeric values are coerced to integer as if by `as.integer`
`...`	other arguments
`drop`	logical. If TRUE the result is coerced to the lowest possible dimension.

Calculates AIC for all objects of class crwFit listed as arguments

Description

AIC, delta AIC, and Akaike weights for all models listed as arguments.

Usage

aic.crw(...)
aic.crw(...)

Arguments

...

a series of crwFit objects

Details

The function can either be executed with a series of 'crwFit' objects (see crwMLE) without the '.crwFit' suffix or the function can be called without any arguments and it will search out all 'crwFit' objects in the current workspace and produce the model selection table for all 'crwFit' objects in the workspace. Caution should be used when executing the function in this way. ALL 'crwFit' objects will be included whether or not the same locations are used! For all of the models listed as arguments (or in the workspace), AIC, delta AIC, and Akaike weights will be calculated.

Value

A table, sorted from lowest AIC value to highest.

Author(s)

Devin S. Johnson

Transform Argos diagnostic data to covariance matrix form

Description

Using this function the user can transform the Argos diagnostic data for location error into a form usable as a covariance matrix to approximate the location error with a bivariate Gaussian distribution. The resulting data.frame should be attached back to the data with cbind to use with the crwMLE function.

Usage

argosDiag2Cov(Major, Minor, Orientation)
argosDiag2Cov(Major, Minor, Orientation)

Arguments

`Major`	A vector containing the major axis information for each observation (na values are ok)
`Minor`	A vector containing the minor axis information for each observation (na values are ok)
`Orientation`	A vector containing the angle orientation of the Major axis from North (na values are ok)

Value

A data.frame with the following columns

`ln.sd.x`	The log standard deviation of the location error in the x coordinate
`ln.sd.y`	The log standard deviation of the location error in the x coordinate
`rho`	The correlation of the bivariate location error ellipse

Author(s)

Devin S. Johnson

'Flattening' a list-form crwPredict object into a data.frame

Description

“Flattens” a list form crwPredict object into a flat data.frame.

Usage

as.flat(predObj)
as.flat(predObj)

Arguments

predObj

A crwPredict object

Value

a data.frame version of a crwPredict list with columns for the state standard errors

Author(s)

Devin S. Johnson

Bearded Seal Location Data

Description

Bearded Seal Location Data

Format

A data frame with 27,548 observations on 3 bearded seals in Alaska:

deployid: Unique animal ID
ptt: Hardware ID
instr: Hardware type
date_time: Time of location
type: Location type
quality: Argos location quality
latitude: Observed latitude
longitude: Observed longitude
error_radius: Argos error radius
error_semimajor_axis: Argos error ellipse major axis length
error_semiminor_axis: Argos error ellipse minor axis length
error_ellipse_orientation: Argos error ellipse degree orientation

Source

Marine Mammal Laboratory, Alaska Fisheries Science Center, National Marine Fisheries Service, NOAA 7600 Sand Point Way NE Seattle, WA 98115

Coerce to sf/sfc object

Description

Provides reliable conversion of "crwIS" and "crwPredict" objects into simple features objects supported in the "sf" package. Both "sf" objects with "POINT" geometry and "sfc_LINESTRING" objects are created. Coercion of "crwPredict" objects to "sfc_LINESTRING" has an option "group" argument when the "crwPredict" object includes predictions from multiple deployments. The grouping column will be used and a tibble of multiple "sf_LINESTRING" objects will be returned

Usage

crw_as_sf(data, ftype, locType, group)

## S3 method for class 'crwIS'
crw_as_sf(data, ftype, locType = c("p", "o", "f"), group = NULL, ...)

## S3 method for class 'crwPredict'
crw_as_sf(data, ftype, locType = c("p", "o", "f"), group = NULL, ...)

## S3 method for class 'list'
crw_as_sf(data, ftype, locType = c("p", "o", "f"), ...)
crw_as_sf(data, ftype, locType, group)

## S3 method for class 'crwIS'
crw_as_sf(data, ftype, locType = c("p", "o", "f"), group = NULL, ...)

## S3 method for class 'crwPredict'
crw_as_sf(data, ftype, locType = c("p", "o", "f"), group = NULL, ...)

## S3 method for class 'list'
crw_as_sf(data, ftype, locType = c("p", "o", "f"), ...)

Arguments

`data`	an object of class `"crwIS"` or `"crwPredict"`
`ftype`	character of either "POINT" or "LINESTRING" specifying the feature type
`locType`	character vector of location points to include ("p","o")
`group`	(optional) character specifying the column to group by for multiple LINESTRING features
`...`	Additional arguments that are ignored

Methods (by class)

crw_as_sf(crwIS): coerce crwIS object to sf (POINT or LINESTRING geometry)
crw_as_sf(crwPredict): coerce crwPredict object to sf (POINT or LINESTRING geometry)
crw_as_sf(list): coerce list of crwIS objects to sf (LINESTRING or MULTILINESTRING geometry)

Coerce crawl objects (crwIS and crwPredict) to tibbles

Description

Coerce crawl objects (crwIS and crwPredict) to tibbles

Usage

crw_as_tibble(crw_object, ...)

## S3 method for class 'crwIS'
crw_as_tibble(crw_object, ...)

## S3 method for class 'crwPredict'
crw_as_tibble(crw_object, ...)

## S3 method for class 'tbl'
crw_as_tibble(crw_object, ...)
crw_as_tibble(crw_object, ...)

## S3 method for class 'crwIS'
crw_as_tibble(crw_object, ...)

## S3 method for class 'crwPredict'
crw_as_tibble(crw_object, ...)

## S3 method for class 'tbl'
crw_as_tibble(crw_object, ...)

Arguments

`crw_object`	an object of class `"crwIS"` or `"crwPredict"`
`...`	Additional arguments that are ignored

Methods (by class)

crw_as_tibble(crwIS): coerce crwIS object to tibble
crw_as_tibble(crwPredict): coerce crwPredict object to tibble
crw_as_tibble(tbl):

Author(s)

Josh M. London

Fit Continuous-Time Correlated Random Walk Models to Animal Telemetry Data

Description

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.

Usage

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,
  ...
)
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,
  ...
)

Arguments

`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 `sfc_POINT`
`...`	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 `northernFurSeal` for an example using a drift model.
`coord`	A 2-vector of character values giving the names of the "X" and "Y" coordinates in `data`. Ignored if `data` inherits class 'sf' or 'sp'.
`proj`	A valid epsg integer code or proj4string for `data` that does not inherit either 'sf' or 'sp'. A valid 'crs' list is also accepted. Otherwise, ignored.
`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 `optim`.
`control`	Control list which is passed to `optim`.
`constr`	Named list with elements `lower` and `upper` that are vectors the same length as theta giving the box constraints for the parameters
`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 `optim` when simulated annealing is used for obtaining start values. See details
`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.

Details

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.

Value

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 `optim` during parameter optimization
`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

Author(s)

Devin S. Johnson, Josh M. London

-2 * log-likelihood for CTCRW models

Description

This function is designed for primary use within the crwMLE model fitting function. But, it can be accessed for advanced R and crawl users. Uses the state-space parameterization and Kalman filter method presented in Johnson et al. (2008).

Usage

crwN2ll(
  theta,
  fixPar,
  y,
  noObs,
  delta,
  mov.mf,
  err.mfX,
  err.mfY,
  rho = NULL,
  activity = NULL,
  n.errX,
  n.errY,
  n.mov,
  driftMod,
  prior,
  need.hess,
  constr = list(lower = -Inf, upper = Inf)
)
crwN2ll(
  theta,
  fixPar,
  y,
  noObs,
  delta,
  mov.mf,
  err.mfX,
  err.mfY,
  rho = NULL,
  activity = NULL,
  n.errX,
  n.errY,
  n.mov,
  driftMod,
  prior,
  need.hess,
  constr = list(lower = -Inf, upper = Inf)
)

Arguments

`theta`	parameter values.
`fixPar`	values of parameters held fixed (contains `NA` for `theta` values).
`y`	N by 2 matrix of coordinates with the longitude coordinate in the first column.
`noObs`	vector with 1 for unobserved locations, and 0 for observed locations.
`delta`	time difference to next location.
`mov.mf`	Movement covariate data.
`err.mfX`	longitude error covariate data.
`err.mfY`	latitude error covariate data.
`rho`	A vector of known correlation coefficients for the error model, typically used for modern ARGOS data.
`activity`	Stopping covariate (= 0 if animal is not moving).
`n.errX`	number or longitude error parameters.
`n.errY`	number of latitude error parameters.
`n.mov`	number or movement parameters.
`driftMod`	Logical. indicates whether a drift model is specified.
`prior`	Function of theta that returns the log-density of the prior
`need.hess`	Whether or not the Hessian will need to be calculated from this call
`constr`	Named list giving the parameter constraints

Details

This function calls compiled C++ code which can be viewed in the src directory of the crawl source package.

Value

-2 * log-likelihood value for specified CTCRW model.

Author(s)

Devin S. Johnson

References

Johnson, D., J. London, M. -A. Lea, and J. Durban. 2008. Continuous-time model for animal telemetry data. Ecology 89:1208-1215.

Simulate a value from the posterior distribution of a CTCRW model

Description

The crwPostIS draws a set of states from the posterior distribution of a fitted CTCRW model. The draw is either conditioned on the fitted parameter values or "full" posterior draw with approximated parameter posterior

Usage

crwPostIS(object.sim, fullPost = TRUE, df = Inf, scale = 1, thetaSamp = NULL)
crwPostIS(object.sim, fullPost = TRUE, df = Inf, scale = 1, thetaSamp = NULL)

Arguments

`object.sim`	A crwSimulator object from `crwSimulator`.
`fullPost`	logical. Draw parameter values as well to simulate full posterior
`df`	degrees of freedom for multivariate t distribution approximation to parameter posterior
`scale`	Extra scaling factor for t distribution approximation
`thetaSamp`	If multiple parameter samples are available in object.sim, setting `thetaSamp=n` will use the nth sample. Defaults to the last.

Details

The crwPostIS draws a posterior sample of the track state matrices. If fullPost was set to TRUE when the object.sim was build in crwSimulator then a pseudo-posterior draw will be made by first sampling a parameter value from a multivariate t distribution which approximates the marginal posterior distribution of the parameters. The covariance matrix from the fitted model object is used to scale the MVt approximation. In addition, the factor "scale" can be used to further adjust the approximation. Further, the parameter simulations are centered on the fitted values.

To correct for the MVt approximation, the importance sampling weight is also supplied. When calculating averages of track functions for Bayes estimates one should use the importance sampling weights to calculate a weighted average (normalizing first, so the weights sum to 1).

Value

List with the following elements:

`alpha.sim.y`	A matrix a simulated latitude state values
`alpha.sim.x`	Matrix of simulated longitude state values
`locType`	Indicates prediction types with a "p" or observation times with an "o"
`Time`	Initial state covariance for latitude
`loglik`	log likelihood of simulated parameter
`par`	Simulated parameter value
`log.isw`	non normalized log importance sampling weight

Author(s)

Devin S. Johnson

Predict animal locations and velocities using a fitted CTCRW model and calculate measurement error fit statistics

Description

The crwMEfilter function uses a fitted model object from crwMLE to predict animal locations (with estimated uncertainty) at times in the original data set and supplemented by times in predTime. If speedEst is set to TRUE, then animal log-speed is also estimated. In addition, the measurement error shock detection filter of de Jong and Penzer (1998) is also calculated to provide a measure for outlier detection.

Usage

crwPredict(object.crwFit, predTime = NULL, return.type = "minimal", ...)
crwPredict(object.crwFit, predTime = NULL, return.type = "minimal", ...)

Arguments

`object.crwFit`	A model object from `crwMLE`.
`predTime`	vector of desired prediction times (numeric or POSIXct). Alternatively, a character vector specifying a time interval (see Details).
`return.type`	character. Should be one of `"minimal","flat","list"` (see Details).
`...`	Additional arguments for testing new features

Details

The requirements for data are the same as those for fitting the model in crwMLE.

predTime can be either passed as a separate vector of POSIXct or numeric values for all prediction times expected in the returned object. Note, previous versions of crwPredict would return both times specified via predTime as well as each original observed time. This is no longer the default (see return.type). If the original data were provided as a POSIXct type, then crwPredict can derive a sequence of regularly spaced prediction times from the original data. This is specified by providing a character string that corresponds to the by argument of the seq.POSIXt function (e.g. '1 hour', '30 mins'). crwPredict will round the first observed time up to the nearest unit (e.g. '1 hour' will round up to the nearest hour, '30 mins' will round up to the nearest minute) and start the sequence from there. The last observation time is truncated down to the nearest unit to specify the end time.

Value

There are three possible return types specified with return.type:

`minimal`	a data.frame with a minimal set of columns: `date_time,mu.x,mu.y,se.mu.x,se.mu.y`
`flat`	a data set is returned with the columns of the original data plus the state estimates, standard errors (se), and speed estimates
`list`	List with the following elements:
`originalData`	A data.frame with `data` merged with `predTime`.
`alpha.hat`	Predicted state
`Var.hat`	array where `Var.hat[,,i]` is the prediction covariance matrix for `alpha.hat[,i]`.

Author(s)

Devin S. Johnson

References

de Jong, P. and Penzer, J. (1998) Diagnosing shocks in time series. Journal of the American Statistical Association 93:796-806.

Plot CRW predicted object

Description

Creates 2 types of plots of a crwPredict object: a plot of both coordinate axes with prediction intervals and a plot of just observed locations and predicted locations.

Usage

crwPredictPlot(object, plotType = "ll", ...)
crwPredictPlot(object, plotType = "ll", ...)

Arguments

`object`	`crwPredict` object.
`plotType`	type of plot has to be one of the following: “map” or “ll” (default).
`...`	Further arguments passed to plotting commands.

Value

A plot.

Author(s)

Devin S. Johnson and Sebastian Luque

Create a weighted importance sample for posterior predictive track simulation.

Description

The crwSamplePar function uses a fitted model object from crwMLE and a set of prediction times to construct a list from which crwPostIS will draw a sample from either the posterior distribution of the state vectors conditional on fitted parameters or a full posterior draw from an importance sample of the parameters.

Usage

crwSamplePar(
  object.sim,
  method = "IS",
  size = 1000,
  df = Inf,
  grid.eps = 1,
  crit = 2.5,
  scale = 1,
  quad.ask = T,
  force.quad
)
crwSamplePar(
  object.sim,
  method = "IS",
  size = 1000,
  df = Inf,
  grid.eps = 1,
  crit = 2.5,
  scale = 1,
  quad.ask = T,
  force.quad
)

Arguments

`object.sim`	A simulation object from `crwSimulator`.
`method`	Method for obtaining weights for movement parameter samples
`size`	Size of the parameter importance sample
`df`	Degrees of freedom for the t approximation to the parameter posterior
`grid.eps`	Grid size for `method="quadrature"`
`crit`	Criterion for deciding "significance" of quadrature points (difference in log-likelihood)
`scale`	Scale multiplier for the covariance matrix of the t approximation
`quad.ask`	Logical, for method='quadrature'. Whether or not the sampler should ask if quadrature sampling should take place. It is used to stop the sampling if the number of likelihood evaluations would be extreme.
`force.quad`	A logical indicating whether or not to force the execution of the quadrature method for large parameter vectors.

Details

The crwSamplePar function uses the information in a crwSimulator object to create a set of weights for importance sample-resampling of parameters in a full posterior sample of parameters and locations using crwPostIS. This function is usually called from crwPostIS. The average user should have no need to call this function directly.

Value

List with the following elements:

`x`	Longitude coordinate with NA at prediction times
`y`	Similar to above for latitude
`locType`	Indicates prediction types with a "p" or observation times with an "o"
`P1.y`	Initial state covariance for latitude
`P1.x`	Initial state covariance for longitude
`a1.y`	Initial latitude state
`a1.x`	Initial longitude state
`n.errX`	number of longitude error model parameters
`n.errY`	number of latitude error model parameters
`delta`	vector of time differences
`driftMod`	Logical. indicates random drift model
`stopMod`	Logical. Indicated stop model fitted
`stop.mf`	stop model design matrix
`err.mfX`	Longitude error model design matrix
`err.mfY`	Latitude error model design matrix
`mov.mf`	Movement model design matrix
`fixPar`	Fixed values for parameters in model fitting
`Cmat`	Covariance matrix for parameter sampling distribution
`Lmat`	Cholesky decomposition of Cmat
`par`	fitted parameter values
`N`	Total number of locations
`loglik`	log likelihood of the fitted model
`Time`	vector of observation times
`coord`	names of coordinate vectors in original data
`Time.name`	Name of the observation times vector in the original data
`thetaSampList`	A list containing a data frame of parameter vectors and their associated probabilities for a resample

Author(s)

Devin S. Johnson

Construct a posterior simulation object for the CTCRW state vectors

Description

The crwSimulator function uses a fitted model object from crwMLE and a set of prediction times to construct a list from which crwPostIS will draw a sample from either the posterior distribution of the state vectors conditional on fitted parameters or a full posterior draw from an importance sample of the parameters.

Usage

crwSimulator(
  object.crwFit,
  predTime = NULL,
  method = "IS",
  parIS = 1000,
  df = Inf,
  grid.eps = 1,
  crit = 2.5,
  scale = 1,
  quad.ask = TRUE,
  force.quad
)
crwSimulator(
  object.crwFit,
  predTime = NULL,
  method = "IS",
  parIS = 1000,
  df = Inf,
  grid.eps = 1,
  crit = 2.5,
  scale = 1,
  quad.ask = TRUE,
  force.quad
)

Arguments

`object.crwFit`	A model object from `crwMLE`.
`predTime`	vector of additional prediction times.
`method`	Method for obtaining weights for movement parameter samples
`parIS`	Size of the parameter importance sample
`df`	Degrees of freedom for the t approximation to the parameter posterior
`grid.eps`	Grid size for `method="quadrature"`
`crit`	Criterion for deciding "significance" of quadrature points (difference in log-likelihood)
`scale`	Scale multiplier for the covariance matrix of the t approximation
`quad.ask`	Logical, for method='quadrature'. Whether or not the sampler should ask if quadrature sampling should take place. It is used to stop the sampling if the number of likelihood evaluations would be extreme.
`force.quad`	A logical indicating whether or not to force the execution of the quadrature method for large parameter vectors.

Details

The crwSimulator function produces a list and preprocesses the necessary components for repeated track simulation from a fitted CTCRW model from crwMLE. The method argument can be one of "IS" or "quadrature". If method="IS" is chosen standard importance sampling will be used to calculate the appropriate weights via t proposal with df degrees of freedom. If df=Inf (default) then a multivariate normal distribution is used to approximate the parameter posterior. If method="quadrature", then a regular grid over the posterior is used to calculate the weights. The argument grid.eps controls the quadrature grid. The arguments are approximately the upper and lower limit in terms of standard deviations of the posterior. The default is grid.eps, in units of 1sd. If object.crwFit was fitted with crwArgoFilter, then the returned list will also include p.out, which is the approximate probability that the observation is an outlier.

Value

List with the following elements:

`x`	Longitude coordinate with NA at prediction times
`y`	Similar to above for latitude
`locType`	Indicates prediction types with a "p" or observation times with an "o"
`P1.y`	Initial state covariance for latitude
`P1.x`	Initial state covariance for longitude
`a1.y`	Initial latitude state
`a1.x`	Initial longitude state
`n.errX`	number of longitude error model parameters
`n.errY`	number of latitude error model parameters
`delta`	vector of time differences
`driftMod`	Logical. indicates random drift model
`stopMod`	Logical. Indicated stop model fitted
`stop.mf`	stop model design matrix
`err.mfX`	Longitude error model design matrix
`err.mfY`	Latitude error model design matrix
`mov.mf`	Movement model design matrix
`fixPar`	Fixed values for parameters in model fitting
`Cmat`	Covaraince matrix for parameter sampling distribution
`Lmat`	Cholesky decomposition of Cmat
`par`	fitted parameter values
`N`	Total number of locations
`loglik`	log likelihood of the fitted model
`Time`	vector of observation times
`coord`	names of coordinate vectors in original data
`Time.name`	Name of the observation times vector in the original data
`thetaSampList`	A list containing a data frame of parameter vectors and their associated probabilities for a resample

Author(s)

Devin S. Johnson

Detect appropriate time scale for movement analysis

Description

This function examines the time vector and evaluates the median time interval. With this, we determine what the best time scale for the movement model is likely to be.

Usage

detect_timescale(time_vector)
detect_timescale(time_vector)

Arguments

time_vector

a vector of class POSIXct

Value

character of either "seconds","minutes","hours","days","weeks"

Display the order of parameters along with fixed values and starting values

Description

This function takes the model specification arguments to the crwMLE function and displays a table with the parameter names in the order that crwMLE will use during model fitting. This is useful for specifying values for the fixPar or theta (starting values for free parameters) arguments.

Usage

displayPar(
  mov.model = ~1,
  err.model = NULL,
  activity = NULL,
  drift = FALSE,
  data,
  Time.name,
  theta,
  fixPar,
  ...
)
displayPar(
  mov.model = ~1,
  err.model = NULL,
  activity = NULL,
  drift = FALSE,
  data,
  Time.name,
  theta,
  fixPar,
  ...
)

Arguments

`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 stopping portion of the model.
`drift`	logical indicating whether or not to include a random drift component.
`data`	data.frame object containing telemetry and covariate data. A `SpatialPointsDataFrame` object from the package 'sp' will also be accepted.
`Time.name`	character indicating name of the location time column
`theta`	starting values for parameter optimization.
`fixPar`	Values of parameters which are held fixed to the given value.
`...`	Additional arguments (probably for testing new features.)

Value

A data frame with the following columns

`ParNames`	The names of the parameters specified by the arguments.
`fixPar`	The values specified by the `fixPar` argument for fixed values of the parameters. In model fitting, these values will remain fixed and will not be estimated.
`thetaIndex`	This column provides the index of each element of the theta argument and to which parameter it corresponds.
`thetaStart`	If a value is given for the `theta` argument it will be placed in this column and its elements will correspond to the `thetaIdx` column.

Author(s)

Devin S. Johnson

Expand a time indexed data set with additional prediction times

Description

Expands a covariate data frame (or vector) that has a separate time index by inserting prediction times and duplicating the covariate values for all prediction time between subsequent data times.

Usage

expandPred(x, Time = "Time", predTime, time.col = FALSE)
expandPred(x, Time = "Time", predTime, time.col = FALSE)

Arguments

`x`	Data to be expanded.
`Time`	Either a character naming the column which contains original time values, or a numeric vector of original times
`predTime`	prediction times to expand data
`time.col`	Logical value indicating whether to attach the new times to the expanded data

Value

data.frame expanded by predTime

Author(s)

Devin S. Johnson

Examples


#library(crawl)
origTime <- c(1:10)
x <- cbind(rnorm(10), c(21:30))
predTime <- seq(1,10, by=0.25)
expandPred(x, Time=origTime, predTime, time.col=TRUE)

#library(crawl)
origTime <- c(1:10)
x <- cbind(rnorm(10), c(21:30))
predTime <- seq(1,10, by=0.25)
expandPred(x, Time=origTime, predTime, time.col=TRUE)

Fill missing values in data set (or matrix) columns for which there is a single unique value

Description

Looks for columns in a data set that have a single unique non-missing value and fills in all NA with that value

Usage

fillCols(data)
fillCols(data)

Arguments

data

data.frame

Value

data.frame

Author(s)

Devin S. Johnson

Examples


#library(crawl)
data1 <- data.frame(constVals=rep(c(1,NA),5), vals=1:10)
data1[5,2] <- NA
data1
data2 <- fillCols(data1)
data2

mat1 <- matrix(c(rep(c(1,NA),5), 1:10), ncol=2)
mat1[5,2] <- NA
mat1
mat2 <- fillCols(mat1)
mat2
#library(crawl)
data1 <- data.frame(constVals=rep(c(1,NA),5), vals=1:10)
data1[5,2] <- NA
data1
data2 <- fillCols(data1)
data2

mat1 <- matrix(c(rep(c(1,NA),5), 1:10), ncol=2)
mat1[5,2] <- NA
mat1
mat2 <- fillCols(mat1)
mat2

fix_path function id depreciated.

Description

fix_path function id depreciated.

Usage

fix_path(...)
fix_path(...)

Arguments

...

Any arguments are ignored.

'Flattening' a list-form crwPredict object into a data.frame

Description

“Flattens” a list form crwPredict object into a flat data.frame.

Usage

flatten(predObj)
flatten(predObj)

Arguments

predObj

A crwPredict object

Value

a data.frame version of a crwPredict list with columns for the state standard errors

Author(s)

Devin S. Johnson

Harbor seal location data set used in Johnson et al. (2008)

Description

Harbor seal location data set used in Johnson et al. (2008)

Format

A data frame with 7059 observations on the following 5 variables.

Time: a numeric vector.
latitude: a numeric vector.
longitude: a numeric vector.
DryTime: a numeric vector.
Argos_loc_class: a factor with levels 0 1 2 3 A B

Author(s)

Devin S. Johnson

Source

Marine Mammal Laboratory, Alaska Fisheries Science Center, National Marine Fisheries Service, NOAA 7600 Sand Point Way NE Seattle, WA 98115

References

Johnson, D., J. London, M. -A. Lea, and J. Durban (2008) Continuous-time random walk model for animal telemetry data. Ecology 89:1208-1215.

Harbor seal location data updated since Johnson et al. (2008)

Description

The original location data used in Johnson et al. (2008) was geographic (latitude/longitude) (but not explicitly documented) and provided as a simple data frame. This data updates the data to a Simple Feature Collection (as part of the sf package) with the CRS explicitly set.

Format

A Simple Feature Collection with 7059 features and 3 fields.

Time: a numeric vector.
DryTime: a numeric vector.
Argos_loc_class: a factor with levels 0 1 2 3 A B.
geometry: a list column with geometry data; CRS = EPSG:4326

Author(s)

Josh M. London

Source

Marine Mammal Laboratory, Alaska Fisheries Science Center, National Marine Fisheries Service, NOAA 7600 Sand Point Way NE Seattle, WA 98115

References

Johnson, D., J. London, M. -A. Lea, and J. Durban (2008) Continuous-time random walk model for animal telemetry data. Ecology 89:1208-1215.

Reverse as.numeric command that is performed on a vector of type POSIXct

Description

Takes integer value produced by as.numeric(x), where x is a POSIXct vector and returns it to a POSIXct vector

Usage

intToPOSIX(timeVector, tz = "GMT")
intToPOSIX(timeVector, tz = "GMT")

Arguments

`timeVector`	A vector of integers produced by as.numeric applied to a PSIXct vector
`tz`	Time zone of the vector (see `as.POSIXct`).

Value

POSIXct vector

Note

There is no check that as.numeric applied to a POSIX vector produced timeVector. So, caution is required in using this function. It was included simply because I have found it useful

Author(s)

Devin S. Johnson

Examples


#library(crawl)
timeVector <- as.numeric(Sys.time())
timeVector
intToPOSIX(timeVector, tz="")
#library(crawl)
timeVector <- as.numeric(Sys.time())
timeVector
intToPOSIX(timeVector, tz="")

Merge a location data set with a dry time (or other stopping) covariate

Description

The function merges a location data set with a stopping variable data set.

Usage

mergeTrackStop(
  data,
  stopData,
  Time.name = "Time",
  interp = c("zeros", "ma0"),
  win = 2,
  constCol
)
mergeTrackStop(
  data,
  stopData,
  Time.name = "Time",
  interp = c("zeros", "ma0"),
  win = 2,
  constCol
)

Arguments

`data`	Location data.
`stopData`	stopping variable data set.
`Time.name`	character naming time index variable in both data sets
`interp`	method of interpolation.
`win`	window for "ma0" interpolation method.
`constCol`	columns in `data` for which the user would like to be constant, such as id or sex.

Details

Simply merges the data frames and interpolates based on the chosen method. Both data frames have to use the same name for the time variable. Also contains stopType which = "o" if observed or "p" for interpolated.

The merged data is truncated to the first and last time in the location data set. Missing values in the stopping variable data set can be interpolated by replacing them with zeros (full movement) or first replacing with zeros then using a moving average to smooth the data. Only the missing values are then replace with this smoothed data. This allows a smooth transition to full movement.

Value

Merged data.frame with new column from stopData. Missing values in the stopping variable will be interpolated

Author(s)

Devin S. Johnson

Examples



track <- data.frame(TimeVar=sort(runif(20,0,20)), x=1:20, y=20:1)
track
stopData <- data.frame(TimeVar=0:29, stopVar=round(runif(30)))
stopData
mergeTrackStop(track, stopData, Time.name="TimeVar")

track <- data.frame(TimeVar=sort(runif(20,0,20)), x=1:20, y=20:1)
track
stopData <- data.frame(TimeVar=0:29, stopVar=round(runif(30)))
stopData
mergeTrackStop(track, stopData, Time.name="TimeVar")

Northern fur seal pup relocation data set used in Johnson et al. (2008)

Description

Northern fur seal pup relocation data set used in Johnson et al. (2008)

Format

A data frame with 795 observations on the following 4 variables:

GMT: A POSIX time vector
loc_class: a factor with levels 3 2 1 0 A.
lat: a numeric vector. Latitude for the locations
long: a numeric vector. Longitude for the locations

Source

Marine Mammal Laboratory, Alaska Fisheries Science Center, National Marine Fisheries Service, NOAA 7600 Sand Point Way NE Seattle, WA 98115

References

Johnson, D., J. London, M. -A. Lea, and J. Durban (2008) Continuous-time random walk model for animal telemetry data. Ecology 89:1208-1215.

tidy-like method for crwFit object

Description

this function mimics the approach taken by broom::tidy to present model output parameters in a tidy, data frame structure.

Usage

tidy_crwFit(fit)
tidy_crwFit(fit)

Arguments

fit

crwFit object from crawl::crwMLE

Package 'crawl'

Help Index

Fit Continuous-Time Correlated Random Walk Models to Animal Movement Data

Description

Note

Author(s)

References

See Also

Generic subset/bracket method for crwIS classes

Description

Usage

Arguments

Calculates AIC for all objects of class crwFit listed as arguments

Description

Usage

Arguments

Details

Value

Author(s)

Transform Argos diagnostic data to covariance matrix form

Description

Usage

Arguments

Value

Author(s)

'Flattening' a list-form crwPredict object into a data.frame

Description

Usage

Arguments

Value

Author(s)

See Also

Bearded Seal Location Data

Description

Format

Source

Coerce to sf/sfc object

Description

Usage

Arguments

Methods (by class)

Coerce crawl objects (crwIS and crwPredict) to tibbles

Description

Usage

Arguments

Methods (by class)

Author(s)

Fit Continuous-Time Correlated Random Walk Models to Animal Telemetry Data

Description

Usage

Arguments

Details

Value

Author(s)

-2 * log-likelihood for CTCRW models

Description

Usage

Arguments

Details

Value

Author(s)

References

See Also

Simulate a value from the posterior distribution of a CTCRW model

Description

Usage

Arguments

Details

Value

Author(s)

See Also

Predict animal locations and velocities using a fitted CTCRW model and calculate measurement error fit statistics

Description

Usage

Arguments

Details

Value

Author(s)

References

Plot CRW predicted object