In Freshwater-Fish-Ecology-Laboratory/detrange: Estimate Detection Range from Passive Acoustic Telemetry

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-"
)

detrange

Please note that this package is still experimental. The API may change in the future. Feel free to drop some issues with questions/bugs/ideas/feedback!

Installation

To use detrange, you must have JAGS installed on your system. Go to http://mcmc-jags.sourceforge.net for instructions. On a mac, you can also install JAGS from homebrew with brew install jags.

Once JAGS is installed, install the development version of detrange from GitHub with:

# install.packages("devtools")
devtools::install_github("Freshwater-Fish-Ecology-Laboratory/detrange")

Introduction

Detection Range and Detection Efficiency

detrange estimates detection range (DR) from multiple stations within a passive acoustic telemetry array using range testing data collected in the field. DR is defined by Kessel et al. (2014) as

"... the relationship between detection probability and the distance between the receiver and tag...presented graphically in the form of a logistic curve of detection probability."

Given a modeled DR, it is possible to estimate the distance at which a target detection efficiency (DE) occurs. DE is defined by Brownscombe et al (2019) as

"[t]he number of acoustic transmitter detections effectively logged by an acoustic receiver in a given time period, expressed as a percentage (or proportion) of total potential detections based on transmission rate."

Following recommendations from Brownscombe et al (2019) and Huveneers et al. (2016), it can be useful to estimate the distance at which a target level of DE occurs (i.e. midpoint of DR at 50% DE), e.g. to place sentinel tags at a sample of receivers to measure variation in DE over time.

The modelling approach

Under the hood, detrange uses JAGS software and the rjags R package to implement a Bayesian generalized linear model with logit link and binomial response distribution. The user may choose to fit a generalized linear mixed-effects model with random slope and/or random intercept for each Station. Otherwise, Station is treated as a fixed effect.

A benefit of using a Bayesian approach is that uncertainty can be quantified for estimates of the distance at which a specified DE occurs. Another benefit is the ability to incorporate prior information. By default, the priors used in the model are non-informative. However, the user may set custom priors, e.g., if prior information about realistic detection range in a given system is known or if data are limited.

Demonstration

Data

detrange expects data typical of detection range testing.

Mandatory columns include:

• station (character or factor)
• distance (positive numeric)
• detects (whole numeric)
• pings (whole numeric)

Optional columns include:

• depth_receiver (positive numeric)
• depth_tag (postive numeric)

pings is the expected number of detections and detects is the observed number of detections over the duration of the range testing time period at a given distance. If depth_receiver and depth_tag are provided, distance is corrected to account for depth.

An example dataset range_test is included for reference.

library(detrange)
head(detrange::range_obs)

Analysis

Fit a model

# adjust the `nthin` argument to improve convergence.
fit <- dr_fit(detrange::range_obs)

A number of generic methods are defined for the output object of dr_fit(), including autoplot glance, tidy, coef, augment, summary, estimates, and predict.

# model summary
glance(fit)

# parameter estimates
tidy(fit, conf_level = 0.89)

# original data with corrected distance
head(augment(fit))

Plot predicted detection range

autoplot(fit)

Predict distance(s) at target levels of detection efficiency

predicted_dist <- dr_predict_distance(fit, de = c(0.5, 0.8))
head(predicted_dist)

How to do more

The output of dr_fit() is a list with 3 elements:
1. fit$model - the model object of class jags created by rjags::jags.model()
1. fit$samples - the MCMC samples generated fromrjags::jags.samples() converted to mcmcr class
1. fit$data - the detection range data provided

These are the raw materials for any further exploration or analysis. For example, view trace and density plots with plot(fit$samples).

See mcmcr and mcmcderive for working with mcmcr objects, or convert samples to an object of class mcmc.list, e,g, with coda::as.mcmc.list for working with the coda R package.

Code of Conduct

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

Freshwater-Fish-Ecology-Laboratory/detrange documentation built on Oct. 30, 2024, 1:10 p.m.