-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.Rmd
124 lines (85 loc) · 5.13 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
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](https://github.com/) with:
``` r
# 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](https://cran.r-project.org/web/packages/rjags/rjags.pdf) 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.
```{r data}
library(detrange)
head(detrange::range_obs)
```
### Analysis
Fit a model
```{r}
# 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`.
```{r}
# model summary
glance(fit)
```
```{r}
# parameter estimates
tidy(fit, conf_level = 0.89)
```
```{r}
# original data with corrected distance
head(augment(fit))
```
Plot predicted detection range
```{r}
autoplot(fit)
```
Predict distance(s) at target levels of detection efficiency
```{r}
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 from`rjags::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](https://github.com/poissonconsulting/mcmcr) and [mcmcderive](https://github.com/poissonconsulting/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](https://github.com/cran/coda) R package.
## Code of Conduct
Please note that the detrange project is released with a [Contributor Code of Conduct](https://contributor-covenant.org/version/2/0/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms.