| Title: | Bayesian State-Space Models for Animal Movement |
|---|---|
| Description: | Tools to fit Bayesian state-space models to animal tracking data. Models are provided for location filtering, location filtering and behavioural state estimation, and their hierarchical versions. The models are primarily intended for fitting to ARGOS satellite tracking data but options exist to fit to other tracking data types. For Global Positioning System data, consider the 'moveHMM' package. Simplified Markov Chain Monte Carlo convergence diagnostic plotting is provided but users are encouraged to explore tools available in packages such as 'coda' and 'boa'. |
| Authors: | Ian Jonsen [aut, cre], Sophie Bestley [ctb], Simon Wotherspoon [ctb], Michael Sumner [ctb], Joanna Mills Flemming [ctb] |
| Maintainer: | Ian Jonsen <[email protected]> |
| License: | GPL-2 |
| Version: | 1.1.3 |
| Built: | 2024-11-03 06:27:48 UTC |
| Source: | CRAN |
Models provided are DCRW (for location filtering), DCRWS (for
location filtering and behavioural state estimation), and their hierarchical
versions (hDCRW, hDCRWS) to estimate parameters jointly across multiple
individual tracking datasets. The models are fit in JAGS using Markov chain
Monte Carlo simulation methods. The models are intended to be fit to Argos
satellite tracking data but options exist to allow fits to other tracking
data types (type ?fit_ssm for details).
| Package: | bsam |
| Type: | Package |
| Version: | 1.1.2 |
| Date: | 2017-07-01 |
| License: | GPL-2 |
| LazyLoad: | yes |
Fit Bayesian state-space models to Argos satellite tracking data. Models provided are DCRW - for location filtering; DCRWS - for location filtering and behavioural state estimation with 2 behavioural states; hDCRW and hDCRWS - hierarchical models for location filtering only, and location filtering with behavioural state estimation, respectively, across multiple animals.
The hierarchical models may provide improved location and/or behavioural state estimates compared to fitting DCRW/DCRWS to individual datasets.
Ian Jonsen
Maintainer: Ian Jonsen <[email protected]>
Jonsen ID, Mills Flemming J, Myers RA (2005) Robust state-space modeling of animal movement data. Ecology 86:2874-2880
Jonsen ID (2016) Joint estimation over multiple individuals improves behavioural state inference from animal movement data. Scientific Reports 6:20625
fit_ssm
## Not run: # Fit DCRW model for state filtering and regularization - # using trivial adapt & samples values for speed data(ellie1) fit <- fit_ssm(ellie1, model = "DCRW", tstep = 1, adapt = 10, samples = 100, thin = 1, span = 0.2) diag_ssm(fit) map_ssm(fit) plot_fit(fit) ## End(Not run)## Not run: # Fit DCRW model for state filtering and regularization - # using trivial adapt & samples values for speed data(ellie1) fit <- fit_ssm(ellie1, model = "DCRW", tstep = 1, adapt = 10, samples = 100, thin = 1, span = 0.2) diag_ssm(fit) map_ssm(fit) plot_fit(fit) ## End(Not run)
Format track data for filtering
dat4jags(d, tstep = 1, tpar = tpar())dat4jags(d, tstep = 1, tpar = tpar())
d |
a data frame of observations (see details) |
tstep |
the time step to predict to (in days) |
tpar |
generalised t-distribution parameters for ARGOS location classes. By
default dat4jags uses the parameters estimated in Jonsen et al (2005) Ecology 86:2874-2880
but users may specify other ARGOS error parameter values via the |
This is an internal function used by fit_ssm to format track
data for JAGS.
The input track is given as a dataframe where each row is an observed location and columns
individual animal identifier,
observation time (POSIXct,GMT),
ARGOS location class,
observed longitude,
observed latitude.
Location classes can include Z, F, and G; where the latter two
are used to designate fixed (known) locations (e.g. GPS locations)
and "generic" locations (e.g. geolocation data) where the user
supplies the error standard deviations, either via the
tpar function or as two extra columns in the input data.
From this dat4jags calculates interpolation indices idx and
weights ws such that if x is the matrix of predicted
states, the fitted locations are ws*x[idx+1,] +
(1-ws)*x[idx+2,].
A list with components
id |
the unique identifier for each dataset |
y |
a 2 column matrix of the lon,lat observations |
itau2 |
a 2 column matrix of the ARGOS precision (1/scale) parameters |
nu |
a 2 column matrix of the ARGOS df parameters |
idx |
a vector of interpolation indices |
ws |
a vector of interpolation weights |
ts |
the times at which states are predicted (POSIXct,GMT) |
obs |
the input observed data frame |
tstep |
the time step specified in the |
Jonsen ID, Mills Flemming J, Myers RA (2005) Robust state-space modeling of animal movement data. Ecology 86:2874-2880 (Appendix A)
Takes a fitted fit_ssm object and uses standard McMC convergence diagnostic plots to
aid assessment of lack of convergence.
diag_ssm(fit)diag_ssm(fit)
fit |
an output object from |
Uses plotting functions from Martyn Plummer's coda package to help
diagnose lack of convergence for the core model parameters. The traceplot shows the time
series for both McMC chains; the density plot shows the density estimate for each parameter;
the autocorrelation plots show the within-chain sample autocorrelation for each parameter;
the G-B-R shrink factor plot shows the evolution of Gelman and Rubin's shrink factor for
increasing number of iterations. See the coda package for further details.
Brooks SP, Gelman A (1998) General methods for monitoring convergence of iterative simulations. Journal of Computational and Graphical Statistics 7:434-455
Example elephant seal Argos tracking data. Data were sourced from the Integrated Marine Observing System (IMOS) - IMOS is supported by the Australian Government through the National Collaborative Research Infrastructure Strategy and the Super Science Initiative.
.RData
Example elephant seal Argos tracking data. Data were sourced from the Integrated Marine Observing System (IMOS) - IMOS is supported by the Australian Government through the National Collaborative Research Infrastructure Strategy and the Super Science Initiative.
.RData
Fits state-space models to animal tracking data. User can choose between a first difference correlated random walk (DCRW) model, a switching model (DCRWS) for estimating location and behavioural states, and their hierarchical versions (hDCRW, hDCRWS). The models are structured for Argos satellite data but options exist for fitting to other tracking data types.
fit_ssm( data, model = "DCRW", tstep = 1, adapt = 10000, samples = 5000, thin = 5, span = 0.2 )fit_ssm( data, model = "DCRW", tstep = 1, adapt = 10000, samples = 5000, thin = 5, span = 0.2 )
data |
A data frame containing the following columns, "id","date", "lc", "lon", "lat". "id" is a unique identifier for the tracking dataset. "date" is the GMT date-time of each observation with the following format "2001-11-13 07:59:59". "lc" is the Argos location quality class of each observation, values in ascending order of quality are "Z", "B", "A", "0", "1", "2", "3". "lon" is the observed longitude in decimal degrees. "lat" is the observed latitude in decimal degrees. The Z-class locations are assumed to have the same error distributions as B-class locations. Optionally, the input data.frame can specify the error standard deviations
for longitude and latitude (in units of degrees) in the last 2 columns,
named "lonerr" and "laterr", respectively. These errors are assumed to be
normally distributed. When specifying errors in the input data, all "lc"
values must be equal to "G". This approach allows the models to be fit to
data types other than Argos satellite data, e.g. geolocation data. See
WARNING: there is no guarantee that invoking these options will yield sensible results!
For GPS data, similar models can be fit via the |
model |
name of state-space model to be fit to data. This can be one of "DCRW", "DCRWS", "hDCRW", or "hDCRWS" |
tstep |
time step as fraction of a day, default is 1 (24 hours). |
adapt |
number of samples during the adaptation and update (burn-in) phase, adaptation and updates are fixed at adapt/2 |
samples |
number of posterior samples to generate after burn-in |
thin |
amount of thinning of to be applied to the posterior samples to minimize within-chain sample autocorrelation |
span |
parameter that controls the degree of smoothing by |
The models are fit using JAGS 4.2.0 (Just Another Gibbs Sampler, created and
maintained by Martyn Plummer; http://martynplummer.wordpress.com/;
http://mcmc-jags.sourceforge.net). fit_ssm is a wrapper that first
calls dat4jags, which prepares the input data, then calls ssm
or hssm, which fit the specified state-space model to the data,
returning a list of results.
For DCRW and DCRWS models, a list is returned with each outer list elements corresponding to each unique individual id in the input data Within these outer elements are a "summary" data.frame of posterior mean and median state estimates (locations or locations and behavioural states), the name of the "model" fit, the "timestep" used, the input location "data", the number of location state estimates ("N"), and the full set of "mcmc" samples. For the hDCRW and hDCRWS models, a list is returned where results, etc are combined amongst the individuals
Ian Jonsen
Jonsen ID, Mills Flemming J, Myers RA (2005) Robust state-space modeling of animal movement data. Ecology 86:2874-2880
Block et al. (2011) Tracking apex marine predator movements in a dynamic ocean. Nature 475:86-90
Jonsen et al. (2013) State-space models for biologgers: a methodological road map. Deep Sea Research II DOI: 10.1016/j.dsr2.2012.07.008
Jonsen (2016) Joint estimation over multiple individuals improves behavioural state inference from animal movement data. Scientific Reports 6:20625
# Fit DCRW model for state filtering and regularization - # using trivial adapt & samples values for speed data(ellie1) fit <- fit_ssm(ellie1, model = "DCRW", tstep = 4, adapt = 10, samples = 100, thin = 1, span = 0.2) # Fit DCRWS model for state filtering, regularization and behavioural state estimation - # using trivial adapt & samples values for speed fit.s <- fit_ssm(ellie1, model = "DCRWS", tstep = 2, adapt = 10, samples = 100, thin = 1, span = 0.2) diag_ssm(fit.s) map_ssm(fit.s) plot_fit(fit.s) result.s <- get_summary(fit.s) # fit hDCRWS model to > 1 tracks simultaneously # this may provide better parameter and behavioural state estimation # by borrowing strength across multiple track datasets - # using trivial adapt & samples values for speed data(ellie2) hfit.s <- fit_ssm(ellie2, model = "hDCRWS", tstep = 2, adapt = 10, samples = 100, thin = 1, span = 0.2) diag_ssm(hfit.s) map_ssm(hfit.s) plot_fit(hfit.s) result.hs <- get_summary(hfit.s)# Fit DCRW model for state filtering and regularization - # using trivial adapt & samples values for speed data(ellie1) fit <- fit_ssm(ellie1, model = "DCRW", tstep = 4, adapt = 10, samples = 100, thin = 1, span = 0.2) # Fit DCRWS model for state filtering, regularization and behavioural state estimation - # using trivial adapt & samples values for speed fit.s <- fit_ssm(ellie1, model = "DCRWS", tstep = 2, adapt = 10, samples = 100, thin = 1, span = 0.2) diag_ssm(fit.s) map_ssm(fit.s) plot_fit(fit.s) result.s <- get_summary(fit.s) # fit hDCRWS model to > 1 tracks simultaneously # this may provide better parameter and behavioural state estimation # by borrowing strength across multiple track datasets - # using trivial adapt & samples values for speed data(ellie2) hfit.s <- fit_ssm(ellie2, model = "hDCRWS", tstep = 2, adapt = 10, samples = 100, thin = 1, span = 0.2) diag_ssm(hfit.s) map_ssm(hfit.s) plot_fit(hfit.s) result.hs <- get_summary(hfit.s)
fitSSM, diagSSM, and plotSSM, have been deprecated. Instead use
fit_ssm, diag_ssm and map_ssm.
fitSSM(...) diagSSM(...) plotSSM(...)fitSSM(...) diagSSM(...) plotSSM(...)
... |
ignored |
Takes a fitted fit_ssm object and extracts the summary data.frame, which includes
the animal ids, POSIXct date/time (at increments specified by tstep in the fit_ssm call),
posterior mean longitude and latitude, and the 2.5, 50, and 97.5
longitude and latitude. For the DCRWS and hDCRWS models, the posterior mean and median behavioural
states corresponding to each estimated location are also provided.
get_summary(x, file = " ")get_summary(x, file = " ")
x |
an output object from |
file |
a character string naming a file. " " indicates output to the console (default) |
a summary data.frame printed either to the console (default) or written as .csv to a specified file.
Takes output from dat4jags, sets up initial values, calls JAGS, and
aggregates results. Intended for internal use, called by fit_ssm.
hssm(d, model = "hDCRWS", adapt, samples, thin, chains, span)hssm(d, model = "hDCRWS", adapt, samples, thin, chains, span)
d |
structured data from |
model |
the state-space model to be fit: hDCRW or hDCRWS |
adapt |
number of samples in adaptation/burnin phase |
samples |
number of posterior samples |
thin |
thinning factor to reduce posterior sample autocorrelation |
chains |
number of parallel McMC chains to run |
span |
span |
Returns a list of McMC samples from marginal posteriors and a
summary data.frame of mean and median position estimates.
Function to be called by fit_ssm.
Takes a fitted fit_ssm object and plots the observed (data) and estimated
locations on a map. For the behavioural models (DCRWS, hDCRWS), the estimated
locations are coloured according to the posterior mean behavioural state estimates.
map_ssm(fit, onemap = TRUE)map_ssm(fit, onemap = TRUE)
fit |
an output object from |
onemap |
If TRUE (default) then all estimated tracks are plotted on a single, combined map, if FALSE then tracks are plotted on separate maps. |
Observed locations are plotted as '+' symbols and estimated locations as filled
circles. Individual track id's (for DCRW and DCRWS models) are displayed at the top of
each plot, but only when onemap = FALSE. The model specified in fit_ssm is
also displayed at the top. Takes advantage of ggplot2 plotting functions.
Currently, results from the hierarchical models (hDCRW, hDCRWS) can only be plotted on a combined map.
## Not run: data(ellie) fit.s <- fitSSM(ellie, model = "DCRWS", tstep = 1, adapt = 100, samples = 100, thin = 1, span = 0.1) map_ssm(fit.s, onemap = TRUE) hfit.s <- fit_ssm(ellie, model = "hDCRWS", tstep = 1, adapt = 100, samples = 100, thin = 1, span = 0.1) map_ssm(hfit.s) ## End(Not run)## Not run: data(ellie) fit.s <- fitSSM(ellie, model = "DCRWS", tstep = 1, adapt = 100, samples = 100, thin = 1, span = 0.1) map_ssm(fit.s, onemap = TRUE) hfit.s <- fit_ssm(ellie, model = "hDCRWS", tstep = 1, adapt = 100, samples = 100, thin = 1, span = 0.1) map_ssm(hfit.s) ## End(Not run)
Takes a fitted fit_ssm object and plots the observed (data), estimated
location and behavioural states (posterior means) as 1-D time-series. Each
individual dataset is plotted separately.
plot_fit(fit)plot_fit(fit)
fit |
an output object from |
Observed locations are plotted as filled circles and estimated locations as blue
lines with the 95% credible interval as a ribbon. Uses ggplot2 plotting functions.
For testing bsam models
simulate( Nt = 100, gamma = 0.8, Sigma = matrix(c(0.01, 0, 0, 0.01), 2, 2), amf = tpar() )simulate( Nt = 100, gamma = 0.8, Sigma = matrix(c(0.01, 0, 0, 0.01), 2, 2), amf = tpar() )
Nt |
number of time steps to simulate |
gamma |
move persistence parameter |
Sigma |
variance-covariance matrix for movement process |
amf |
Argos error data, defined by default via the |
a data_frame of true locations and locations with Argos error
Takes output from dat4jags, sets up initial values, calls JAGS, and
aggregates results. Intended for internal use, called by fit_ssm.
ssm(d, model = "DCRW", adapt, samples, thin, chains, span)ssm(d, model = "DCRW", adapt, samples, thin, chains, span)
d |
structured data from |
model |
the state-space model to be fit: DCRW or DCRWS |
adapt |
number of samples in adaptation/burnin phase |
samples |
number of posterior samples |
thin |
thinning factor to reduce posterior sample autocorrelation |
chains |
number of parallel McMC chains to run |
span |
span |
Returns a list of McMC samples from marginal posteriors and a
summary data.frame of mean and median position estimates.
Function to be called by fit_ssm.
ARGOS Error Fixed Parameters for Location Classes
tpar()tpar()
This is an internal function used by dat4jags to specify measurement
error parameters.
These are the fixed parameters (t-distribution scale & df) for ARGOS error classes, from Jonsen et al (2005) Ecology 86:2874-2880.
A dataframe with columns
lc |
ARGOS location class as an ordered factor |
itau2.lon |
precision parameters for longitude in degrees |
itau2.lat |
precision parameters for latitude in degrees |
nu.lon |
df parameters for longitude |
nu.lat |
df parameters for latitude |