Fit Continuous-Time State-Space and Latent Variable Models for Quality Control of Argos Satellite (and Other) Telemetry Data and for Estimating Movement Behaviour

Fits continuous-time random walk and correlated random walk state-space models for quality control animal tracking data ('Argos', processed light-level 'geolocation', 'GPS'). Template Model Builder ('TMB') is used for fast estimation. The 'Argos' data can be: (older) least squares-based locations; (newer) Kalman filter-based locations with error ellipse information; or a mixture of both. The models estimate two sets of location states corresponding to: 1) each observation, which are (usually) irregularly timed; and 2) user-specified time intervals (regular or irregular). Latent variable models are provided to estimate move persistence along tracks as an index of behaviour. Track simulation functions are provided. 'Jonsen I', 'McMahon CR', 'Patterson TA', 'Auger-Méthé M', 'Harcourt R', 'Hindell MA', 'Bestley S' (2019) Movement responses to environment: fast inference of variation among southern elephant seals with a mixed effects model. Ecology 100:e02566 .

foieGras - fit latent variable movement models to animal tracking data for location quality control and behavioural inference

master branch:

dev branch:

foieGras is an R package that fits a continuous-time model (RW or CRW) in state-space form to filter Argos (or GLS) satellite location data. Template Model Builder (TMB) is used for fast estimation. Argos data can be either (older) Least Squares-based locations, (newer) Kalman Filter-based locations with error ellipse information, or a mixture of the two. The state-space model estimates two sets of location states: 1) corresponding to each observation, which are usually irregularly timed (fitted states); and 2) corresponding to (usually) regular time intervals specified by the user (predicted states). Locations are returned as both LongLat and on the Mercator projection (units=km). Additional models are provided to infer movement behaviour along the SSM-estimated most-probable track.

Installation

First, ensure you have R version >= 3.6.0 installed (preferably R 4.0.0 or higher):

R.Version()

From CRAN

foieGras is on CRAN and can be downloaded within R, in the usual way install.packages("foieGras") or, more completely: install.packages("foieGras", depedencies = c("Imports","LinkingTo","Suggests"))

From GitHub (source)

On PC’s running Windows, ensure you have installed Rtools

On Mac’s, ensure you have installed the Command Line Tools for Xcode by executing xcode-select --install in the terminal; or you can download the latest version from the URL (free developer registration may be required). A full Xcode install uses up a lot of disk space and is not required.

To get the very latest foieGras stable version, you can install from GitHub:

remotes::install_github("ianjonsen/foieGras")

Note: there can be issues getting compilers to work properly, especially on a Mac with OS X 10.13.x or higher. If you encounter install and compile issues, I recommend you consult the excellent information on the glmmTMB GitHub.

Basic example

foieGras is intended to be as easy to use as possible. Here’s an example showing how to quality-control Argos tracking data, and infer a behavioural index along the estimated animal tracks:

library(tidyverse)
library(foieGras)

fit <- fit_ssm(sese, vmax= 4, model = "crw", time.step = 24, control = ssm_control(verbose = 0, se = FALSE))

fmp <- fit_mpm(fit, what = "predicted", model = "jmpm", control = mpm_control(verbose = 0))

plot(fmp, pages = 1, ncol = 3, pal = "Zissou1", rev = TRUE)

fmap(fit, fmp, what = "predicted", pal = "Cividis")

What to do if you encounter a problem

If you are convinced you have encountered a bug or unexpected/inconsistent behaviour when using foieGras, you can post an issue here. First, have a read through the posted issues to see if others have encountered the same problem and whether a solution has been offered. You can reply to an existing issue if you have the same problem and have more details to share or you can submit a new issue. To submit an issue, you will need to clearly describe the unexpected behaviour, include a reproducible example with a small dataset, clearly describe what you expected to happen (but didn’t), and (ideally) post a few screenshots/images that nicely illustrate the problem.

How to Contribute

Contributions from anyone in the Movement Ecology/Bio-Logging communities are welcome. Consider submitting a feature request here to start a discussion. Alternatively, if your idea is well-developed then you can submit a pull request for evaluation here. Unsure about what all this means but still want to discuss your idea? then have a look through the GitHub pages of community-built R packages like tidyverse/dplyr for examples.

Code of Conduct

Please note that the foieGras project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.