Learn R Programming

bayesmove

Introduction

The goal of bayesmove is to analyze animal movement using a non-parametric Bayesian framework, which addresses a number of limitations of existing segmentation methods and state-space models. This package currently offers two different model frameworks on which to make behavioral inference from animal telemetry data: 1) the mixed-membership method for movement (M4) that provides segment-level behavioral state estimation, and 2) observation-level behavioral state estimation.

The M4 model is a two-stage framework that first partitions individual tracks into segments (via reversible-jump Markov chain Monte Carlo) and subsequently clusters these segments into latent behavioral states (via non-parametric Latent Dirichlet Allocation). This framework allows the analysis of multiple telemetry and biologging data streams, which must first be discretized into a set of bins before they can be analyzed. The model that makes behavioral inference at the observation-level also requires that data streams are first discretized, but then directly clusters these observations together into behavioral states within a single step (via a non-parametric mixture model). While the outcome is similar to that from state-space and hidden Markov models, this observation-level model does not assume an underlying Markov property or use a mechanistic process (e.g., correlated random walk). Additional details about the M4 method can be found in Cullen et al. (2021) doi:10.1111/2041-210X.13745.

This package also includes features to check model convergence based on the log-likelihood for each MCMC iteration. Model output are often returned in a format that is tidyverse-friendly, which allows for easy visualization using ggplot2. Additionally, a Shiny app can be launched to dynamically and interactively explore animal movement data, including options to filter and export data from the app.

Installation

You can install the latest CRAN release with:

install.packages("bayesmove", dependencies = c("Imports","LinkingTo","Suggests"))

which will ensure that all packages needed to run the Shiny app are installed.

You can install the latest stable version of the package from GitHub with:

# install.packages("remotes")
remotes::install_github("joshcullen/bayesmove")

or latest development (unstable) version with:

# install.packages("remotes")
remotes::install_github("joshcullen/bayesmove@dev")

If installing from GitHub, ensure that you have a tool installed for compiling C++ code:

  • For PC’s running Windows, install Rtools if you have not already done so.

  • For Mac’s, install 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.

Support

If you are receiving errors from the model output that you believe to be bugs, please report them as issues in the GitHub repo. Additionally, if there are any other features you would like added to this package, please submit them to the issue tracker.

Copy Link

Version

Install

install.packages('bayesmove')

Monthly Downloads

259

Version

0.2.1

License

GPL-3

Issues

Pull Requests

Stars

Forks

Maintainer

Joshua Cullen

Last Published

October 22nd, 2021

Functions in bayesmove (0.2.1)

CumSumInv

Internal function that calculates the inverted cumsum
assign_behavior

Assign behavior estimates to observations
behav_gibbs_sampler

Internal function that runs RJMCMC on a single animal ID
cluster_obs

Cluster observations into behavioral states
behav_seg_image

Internal function that transforms a vector of bin numbers to a presence-absence matrix
assign_tseg

Add segment numbers to observations
SampleZAgg

Internal function that samples z1 aggregate
assign_tseg_internal

Internal function that adds segment numbers to observations
StoreZ

This function helps store z from all iterations after burn in
SummarizeDat

Internal function that generates nmat matrix to help with multinomial draws
cluster_segments

Cluster time segments into behavioral states
insert_NAs

Insert NA gaps to regularize a time series
log_marg_likel

Internal function that calculates the log marginal likelihood of each model being compared
expand_behavior

Expand behavior estimates from track segments to observations
discrete_move_var

Discretize movement variables
get_behav_hist

Extract bin estimates from Latent Dirichlet Allocation or mixture model
get.theta

Internal function to calculate theta parameter
rmultinom2

Internal function that samples z's from a multinomial distribution
get_MAP_internal

Internal function to find the maximum a posteriori (MAP) estimate of the MCMC chain
get_MAP

Find the maximum a posteriori (MAP) estimate of the MCMC chain
df_to_list

Convert data frame to a list by animal ID
extract_prop

Extract behavior proportion estimates for each track segment
find_breaks

Find changes for integer variable
get_summary_stats

Internal function that calculates the sufficient statistics for the segmentation model
round_track_time

Round time to nearest interval
sample.phi

Internal function to sample bin estimates for each movement variable
prep_data

Calculate step lengths, turning angles, net-squared displacement, and time steps
get_breakpts

Extract breakpoints for each animal ID
tracks.seg

Segmented tracks for all IDs.
sample.phi.mixmod

Internal function to sample bin estimates for each movement variable
plot_breakpoints_behav

Internal function for plotting breakpoints over each of the data streams
get.llk.mixmod

Internal function to calculate the log-likelihood for iteration of mixture model
tracks.list

Tracks discretized and prepared for segmentation.
filter_time

Filter observations for time interval of interest
%>%

Pipe operator
sample.v.mixmod

Internal function to sample parameter for truncated stick-breaking prior
shiny_tracks

Dynamically explore tracks within Shiny app
sample.v

Internal function to sample parameter for truncated stick-breaking prior
segment_behavior

Segmentation model to estimate breakpoints
samp_move

Internal function for the Gibbs sampler within the reversible-jump MCMC algorithm
sample.gamma.mixmod

Internal function to sample the gamma hyperparameter
summarize_tsegs

Summarize observations within bins per track segment
summarize1

Internal function that summarizes bin distributions of track segments
tracks

Simulated set of three tracks.
traceplot

View trace-plots of output from Bayesian segmentation model
prep_data_internal

Internal function to calculate step lengths, turning angles, and time steps
sample.z

Internal function to sample latent clusters
plot_breakpoints

Plot breakpoints over a time series of each movement variable
rmultinom1

Internal function that samples z's from a categorical distribution
sample.z.mixmod

Internal function to sample latent clusters (for observations)