mackerman44 / telemetyr

An R package for processing telemetry observation data.

telemetyr

telemetyr is an R package to ease the burden of processing and interpreting oodles of telemetry observation data. More specifically, telemetyr aims to provide tools to simplify reading, cleaning, reduction, analysis, and visualization of telemetry observational data. The package is initially being developed as part of a radio telemetry project to characterize the distribution, movement, and survival of juvenile Chinook salmon emigrants in the Lemhi and Salmon rivers, Idaho, USA, during winter months. Currently, the package is written specific to radio telemetry data downloaded from NOAA receivers and using the Tracker software; however, the long-term goal is that functions and tools within telemetyr be developed further to accommodate any type of telemetry data (e.g. acoustic, radio, etc.) including from any type of receiver make or model.

At the writing of this README file, the package includes functionality to import, clean, and compress telemetry observations in preparation for analysis. Cleaned observations can then easily be turned into long- or wide-form capture histories which can then be used for data analysis and visualization. Some functions and documentation are also included to help the user run a Cormack-Jolly-Seber model in a Bayesian framework. We also include functions that can be used for perform simple telemetry site "diagnostics" including evaluations of site operation times, site "noise", and the like. Finally, functions are available to summarise and visualize movement, spatially and temporally, along a river network.

The authors hope to continue to develop telemetyr in the long-term and so any feedback on bugs, additional desired functionality, or similar are always appreciated. To report a bug, request features, report errors in documentation, etc. please visit the Issues page for the telemetyr package here and start a "New issue".

Getting Started

telemetyr requires the JAGS software (Just Another Gibbs Sampler). This can be downloaded here:

https://sourceforge.net/projects/mcmc-jags/files/

Please download version >= 4.0.0. You'll need to install JAGS before installing telemetyr.

To install the current working version of this package to your computer, you can use Hadley Wickham's devtools package. To install and load devtools (or any package for that matter) use:

install.packages("devtools")
library(devtools)

Once devtools is successfully installed, use the following to install telemetyr:

devtools::install_github("BiomarkABS/telemetyr", build_vignettes = TRUE)

Be sure to include the build_vignettes = TRUE argument, as this will ensure that vignettes included with the package will be built and made available.

Vignettes

Because the R packages rmarkdown and knitr are used to build this vignette to HTML output, you are required to have these installed to view vignettes available from this package. Both of these packages can be installed and loaded using the directions above for devtools. Vignettes can then be accessed using:

browseVignettes("telemetyr")

Alternatively, vignettes can be viewed in the Help menu using, for example:

vignette("Data_Prep", package = "telemetyr")

telemetyr currently includes the following vignettes:

*Data_Prep: Describes the importing, cleaning, and compression of telemetry observation data including instructions on how to generate capture histories in preparation for data analysis and visualization.

*Diagnostics: A vignette to describe how to perform various study "diagnostics" including evaluations of site/receiver operation times, site noise, tag battery life, and the like.

*CJS: Instructions on how to perform a Bayesian CJS model using wide form capture histories that can be build using the telemetyr package or otherwise.

postpack

A quick shout out to the postpack R package available here. The telemetyr package invokes postpack for working with the mcmc.list object resulting from the CJS model performed using JAGS. postpack should be installed with the telemetyr package, but can also be installed using:

devtools::install_github("bstaton1/postpack")

Developers Note

To use devtools you may also have to download and install Rtools. The latest version of Rtools can be found here.

Making Contributions

If you are interested in making contributions to telemetyr, consider getting a GitHub account, fork this repository, clone to a local directory, modify, and send me a pull request. The authors can then review any changes and merge.

Questions?

Please feel free to post an issue to this repository for requested features, bug fixes, errors in documentation, etc.

Licenses

Text and figures : CC-BY-4.0

Code : See the DESCRIPTION file

Data : CC-0 attribution requested in reuse

Cheers!

telemetyr's Issues

tag_data argument in summarise_test_data()

I'd like to add the ability for the tag_data argument in the summarise_test_data() function to accommodate either an object (e.g., the tag_releases) data or a file path (e.g., the file path to tag release metadata).

Document QA/QC procedure

From @KevinSee : I added csv files of the raw and compressed data to the NAS for each year. We should define a QA/QC procedure to ensure this data is ready to go. Might involve several different things to check and clean up. Hopefully Nick can help write a document describing this.

Summarise Sentinel Data

Lower priority. Do we want to add functions to summarise data from so-called "sentinel" tags i.e. tags deployed in the field to simulate a fish for evaluations of read range, detection probability, and the like?

Survival Models

Some of this could perhaps, at some point, be moved to KevinSee/LemhiRT.

From @KevinSee :
On April 22, 2020 -
Things to look into:

Simple CJS model using batch_1 tags and RT detections only

Bring in detections from batch_2 and batch_3 tags, starting them in the reach with their first detection.

Kaplan-Meier known-fates model

CJS models for right censored data (when batteries die)

Other ideas?

On May 5, 2020 -
Completed CJS models using:

PIT tag observations only.
RT observations only, including bringing in batch 2 and batch 3 tags, based on first observation of them (batch 2/3 tags that are never detected are not included in the model. Does this bias results?)

On May 29, 2020 -
Note that Kaplan-Meier and other known-fate models usually have data about when (or where) at least some individuals die. Right censored data in that context are individuals that have survived up to some point and then no further data is collected (e.g. the study ends, the radio tag dies). With this study, such models are probably not appropriate, since we never know when a fish actually dies, we just stop detecting it.

Missing Dates

This one seems more related to data QA/QC for the Lemhi RT project. Consider moving to KevinSee/LemhiRT?

From @KevinSee Apr 22, 2020:
Even after updating several functions, there are still a number of rows with missing "start" and "end" date/times in the compressed dataframe. We'll need to track down which raw files these correspond to, and figure out what's going on.

2018-2019: 95 rows, all from receiver DC1, across multiple tag IDs
2019-2020: 370,451 rows, all from receivers TT1 and TT2

Import TidBit Temperature Data

Whether here or in the LemhiRT package we need to import, clean, and summarize the TidBit temperature data at some point. Putting this here to remind myself.

Package may be incompatible with R 4.0.2

From @ntfuch1:

I was not able to successfully install this package running R 4.0.2. The issue has since been resolved only after uninstalling R, Rstudio, and Rtools. Only after re-installing R version 3.6 did the package install properly.

Four date/time columns preserved after clean_raw_data()

This one has perhaps been resolved. Maybe we just need to re-run clean_raw_data() and determine if it functions as intended, now.

@mackerman44 April 13, 2020:
When running the clean_raw_data() function on the "raw" data, multiple date and/or time columns are generated and afterwards we end up with 4 columns (orig_date, date, time, and date_time). Those columns are also preserved through round_tag_codes().

Are those columns duplicative i.e. can we only bring the date_time column through clean_raw_data()? Or is there a reason for keeping additional columns?

@KevinSee April 14, 2020:
The org_date was left to identify which rows had an original date-stamp of "00/00/00", for QA/QC purposes, or in case we realized that assigning a date for those observations based on the file name was not a good idea. If we're settled on how that works, we could remove orig_date, date and time columns from the data when it's run through clean_raw_data().

@mackerman44 April 14, 2020:
That makes sense to me. But maybe leave the orig_date, date, and time columns for now until we're further along in the build process? But also keep this issue open to remind ourselves later to remove?

Package Installation Fail

Today, I attempted to install telemetyr on my new machine.

library(devtools)
install_github("BiomarkABS/telemetyr", build_vignettes = T)

Unfortunately, the first attempt failed because rjags was not installed. Then, after installing rjags the second attempt failed with:

E> The rjags package is just an interface to the JAGS library
E> Make sure you have installed JAGS-4.x.y.exe (for any x >=0, y>=0) from
E> http://www.sourceforge.net/projects/mcmc-jags/files

After downloading and installing JAGS the install worked fine.

Is this the intended or expected response? I need to remind myself, but wasn't jagsUI added (or something to that effect) to remove the need for JAGS. Not high priority, just ran into this when getting telemetyr on the new machine.