In RossDwyer/VTrack: A Collection of Tools for the Analysis of Passive Acoustic Telemetry Data

Background

Passive telemetry studies use detection patterns of a tagged animal within a fixed array to understand movement patterns, habitat use and activity space. Raw detection data are typically used to calculate metrics of detection (i.e. number of detections, number of days detected, number of receivers tag was detected on, index of residence), dispersal (e.g. distances and bearings between consecutive detections; step distances and turning angles, distances and bearings between each detection and release site) and activity space (e.g. Minimum Convex Polygon MCP area, Kernel Utilisation Distribution area), however the techniques and parameters used to calculate these metrics are often customised to each study making cross-study comparisons unreliable. Here we provide a tool to facilitate a standardised workflow to calculate these commonly used metrics.

knitr::include_graphics('images/Fig1b.png')

_{Figure 1. Visual summary of workflow to calculate standardised metrics using the Animal Tracking Toolbox.}

The Animal Tracking Toolbox (ATT) is a collection of functions created in the R statistical environment (R Development Core Team 2018) that calculates standardised metrics of dispersal and activity space from passive telemetry to enable direct comparisons between animals tracked within the same study and between studies or locations. The functions uses detection data alongside tag metadata and receiver station information to calculate a range of standardised movement and activity space metrics. This toolbox can be used to calculate and visualise standardised metrics of movement and activity space within and between species tracked at multiple locations.

knitr::include_graphics('images/Fig2.png')

_{Figure 2. Overall activity space metric plots for multiple species tagged at multiple locations (a) Yellowfin Bream (n=1), (b) Yellowtail Kingfish (n=1), (c) Grey Reef Shark (n=1) and (d) Bull Shark (n=1) output using the ATT. Coloured points represent Centres of Activity (60 min time steps) with darker shapes representing core activity space (50% contour of Brownian bridge kernel utilisation distribution; BBKUD) and lighter shapes representing the extent of activity space (95% contour of BBKUD). Black polygons represent overall Minimum Convex Polygons from detection data. Open circles represent locations of VR2W receivers deployed within the IMOS ATF infrastructure and associated research installations.}

The ATT was developed to preprocess and calculate standardised metrics of dispersal and activity space from large-scale detection data housed in the Integrated Marine Observing System’s Animal Tracking Facility (IMOS ATF) national data repository. The ATT accepts detection data exported from the IMOS ATF database (referred to as IMOSdata here, and can be accessed through the AODN portal). The ATT can also be used to analyse data exported from the VEMCO data management software VUE (refered to as VEMCOdata here). We are currently working on additional functionality for using the ATT with detection data exported from other passive telemetry networks.

This manual will outline the required data formats for input tag detection data (either IMOSdata or VEMCOdata), associated tag metadata (referred to as taginfo ) and receiver station information (statinfo). This manual will also demonstrate how to run the function for a single tag as well as running the function for a large number of tags.

Installation

The Animal Tracking Toolbox can be installed from the CRAN repository

install.packages("VTrack")

## The development version can be also be accessed from GitHub:
install.packages("devtools")
devtools::install_github("rossdwyer/VTrack")

Functions within the toolbox

The Animal Tracking Toolbox is comprised of five main functions that work in series:

setData() sets up data and produces a single list 'ATT' object so detection data, tag metadata and station information are all in one place. Initialises data for use with other functions in the toolbox.
detectionSummary() calculates standard detection metrics using an 'ATT' object. Produces a list with detection metrics calculated over the full tag life and within user-defined temporal subset (i.e. monthly and weekly metrics).
dispersalSummary() calculates standard dispersal metrics using an 'ATT' object. Produces a tibble dataframe with dispersal distance and bearing measurements between consecutive detections as well as between each detection and release location (if provided in 'taginfo').
COA() estimates short-term Centers of Activity using an 'ATT' object. Based on technique described in Simpfendorfer et al. 2002. Produces a 'COA' tibble dataframe object with centers of activity estimated within user-defined timesteps.
HRSummary() calculates standardised activity space metrics using a 'COA' object. Produces a list with activity space metrics calculated over the full tag life and within user-defined temporal subsets (i.e. monthly and weekly). Technique of calculating activity space metrics include minimum convex polygons (MCP), fixed kernel utilisation distributions (fKUD) or Brownian bridge kernel utilisation distributions (BBKUD). Cumulative metrics of activity space is also calculated with cumulative argument. Spatial polygons and raster objects for further plotting are also produced with storepoly argument.

In addition to these functions, there are additional functions to help plot detection summaries using an abacus plot (abacusPlot()). We are working on more functions to help visualise dispersal summaries and activity spaces calculated... Watch this space!!

Input data formats

Analysing passive telemetry data requires three sets of data: Tag detection data (refered to here as either IMOSdata or VEMCOdata, depending on data source); Tag metadata (taginfo); and Receiver metadata (statinfo). The ATT was developed to recognise field names from the IMOS ATF database and more generally from a VEMCO VUE database that is commonly used in the field of passive acoustic telemetry. These data formats are detailed below, and can be used as a guide to configure the tag detection data input if the VEMCO or IMOS ATF data formats are not used. The taginfo and statinfo data formats conforms to the metadata information stored on the IMOS ATF database, and similar formats should be used to store metadata information on animals tagged for analysing passive acoustic telemetry data.

Tag detection data formats

VEMCO input format (`VEMCOdata`)

IMOS ATF input format (`IMOSdata`)

Tag metadata input format (`taginfo`)

Tag metadata input format is based on IMOS ATF metadata structure

Receiver metadata input format (`statinfo`)

Receiver metadata input format is based on IMOS ATF metadata structure

Usage

Load the VTrack version >2.0 library

library(VTrack)
#library(sp)

Setup data for smooth functioning with other ATT functions

## Input example datasets
data(IMOSdata)  ## Detection data exported from IMOS data repository
data(VEMCOdata) ## Detection data exported from a VUE database
data(taginfo)
data(statinfo)

## Setup data for use with the Animal Tracking Toolbox
ATTdata <- setupData(Tag.Detections = IMOSdata, 
                     Tag.Metadata = taginfo, 
                     Station.Information = statinfo, 
                     source="IMOS",
                     tzone= "UTC")

Calculating detection metrics

## Calculate detecion metrics with monthly subsets chosen
detSum<-detectionSummary(ATTdata,  
                         sub = "%Y-%m")

detectionSummary() outputs a list object with two components, $Overall: detection metrics for the full period of the tag and $Subsetted: detection metrics for weekly or monthly temporal subsets depending on the sub argument.

head(detSum)

## Accessing metrics of detection for full tag life
detSum$Overall

## Accessing metrics of detection for each temporal subset
detSum$Subsetted

Create an abacus plot

abacusPlot(ATTdata)

knitr::include_graphics('images/Fig3.png')

## Create a facetted abacus plot for individuals 77523274 and 77523147
abacusPlot(ATTdata, 
           id=c("77523274","77523147"), 
           facet=TRUE)

knitr::include_graphics('images/Fig4.png')

Calculating dispersal metrics

## Calculate dispersal metrics
dispSum<-dispersalSummary(ATTdata)

## Calculate dispersal metrics
dispSum<-dispersalSummary(ATTdata)

dispersalSummary() outputs a tibble data frame object with step distances and step bearings calculated for each detection. The number of rows will be equal to the raw detection data, therefore it may take longer to process dispersal metrics for a large number of animals or for large datasets.

## Accessing metrics of dispersal
dispSum

Calculating activity space metrics

## First, estimate Short-term center of activities
COAdata<-COA(ATTdata, 
             timestep = 60, ## timestep bin used to estimate centers of activity (in minutes)
             split = TRUE)

COA() produces a single tibble data frame with centers of activity positions estimated for each timestep bin when split = FALSE; and a list object with centers of activity positions for each individual when split = TRUE.

COAdata[1:2]

If you need to access COA estimates for a single indiviual you can access them by specifying which 'Tag.ID' you are looking for, for example if we want the COA estimates for individual 77523307:

COAdata$`77523307`

Once COA estimates are estimated we can calculate activity space metrics:

## Define projected Coordinate Reference System 
# projected coordinate systems should signify distance in meters so the output area values are in sq meters
# (here epsg:3577 refers to the GDA94 Australian Albers projection)
library(raster)
proj<-CRS("+init=epsg:3577")

## HRSummary() requires calculation of COAs first
## Estimate 100% Maximum Convex Polygon (MCP) areas
mcp_est <- HRSummary(COAdata, 
                     projCRS=proj, 
                     type="MCP", 
                     cont=100,
                     sub = "%Y-%m")

HRSummary() outputs a list object with two components, $Overall: activity space metrics for the full period of the tag and $Subsetted: activity space metrics for weekly or monthly temporal subsets depending on the sub argument.

mcp_est

Other types of activity space metrics can also be calculated (e.g. fixed KUD using type = "fKUD" and Brownian Bridge KUD using type = "BBKUD". Cumulative activity space metrics across temporal subsets can also be calculated using the cumulative = TRUE argument.

##*** Warning: the following might take a little while to run! ***##
## Estimate 50% and 95% fixed Kernel Utilisation Distribution ('fKUD') contour areas with cumulative metrics calculated
fkud_est<-HRSummary(COAdata, 
                   projCRS=proj, 
                   type="fKUD",
                   cont=c(50,95),
                   cumulative=TRUE)

Storing spatial data associated with activity space metrics

MCP polygons and probability distributions associated with fKUD and BBKUDs can be stored when storepoly = TRUE. This outputs a list object with the two components, $Overall: a tibble data frame with activity space metrics for the full period of the tag and $Subsetted: a tibble data frame with activity space metrics for weekly or monthly temporal subsets depending on the sub argument, but also includes an additional $Spatial.Objects list that stores polygons (if calculating MCPs) or probability distribution raster (if calculating fKUD or BBKUD) for full tag life and temporal subsets.

## Estimate 20%, 50% and 95% Brownian Bridge Kernel Utilisation Distribution ('BBKUD') contour areas and store polygons
BBkud_est<-HRSummary(COAdata, 
                   projCRS=proj, 
                   type="BBKUD", 
                   cont=c(20,50,95), 
                   storepoly=TRUE)

summary(BBkud_est)

The $Spatial.Objects list object in itself consists of a nested list. The example object above, BBkud_est is structured in this way:

`BBkud_est`
    |---> `$Overall`    : tibble data frame with activity space metrics for full tag life
    |---> `$Subsetted`  : tibble data frame with activity space metrics for each temporal subset
    |---> `$Spatial.Objects` : list object with as many components as unique Tag.IDs in the data
                |---> `51448633`
                |---> `77523307`
                          |----> `$BBKUD_full` : a raster object with the BBKUD for the full tag life
                          |----> `$BBKUD_sub`  : a raster stack object with the BBKUD for each temporal subset
                                      |-----> `$X2013.05` : raster object for subset '2013-05' (May 2013)
                                      |-----> `$X2013.06` : raster object for subset '2013-06' (June 2013)
                                      |-----> `$X2013.07` : raster object for subset '2013-07' (July 2013)

Map activity space

## Base plots using raster
# Activity space for full tag life

library(raster)
library(viridis) ## access more color palettes!

## Select rasters of full KUDs for each individual into a single list
fullstack <-
  unlist(BBkud_est$Spatial.Objects)[grep("*_full", names(unlist(BBkud_est$Spatial.Objects)))]

names(fullstack) <-
  unlist(lapply(strsplit(names(fullstack), "[.]"), `[[`, 1))

## Lets plot the overall BBKUD for Tag.ID `77523307`
fulltag <- fullstack$`77523307`
values(fulltag)[values(fulltag) > 96] <- NA
plot(fulltag, col = viridis(100), zlim = c(0, 100),
     xlim=c(151.9, 152.1), ylim=c(-23.55, -23.4))
points(station_latitude ~ station_longitude, statinfo, col = 2, cex=0.7)
points(Latitude.coa ~ Longitude.coa,
       data = COAdata$`77523307`,
       pch = 20,
       col = 4,
       cex = 0.5)
contour(fulltag, add = TRUE, levels = c(50, 95))

knitr::include_graphics('images/Fig5.png')

# Monthly activity space for `77523307`
## Select rasters of subsetted KUDs for each individual into a single list
substack <-
  unlist(BBkud_est$Spatial.Objects)[grep("*_sub", names(unlist(BBkud_est$Spatial.Objects)))]

tag_subset <-
  disaggregate(substack$`77523307.BBKUD_sub`,
  fact = 3,
  method = 'bilinear')

values(tag_subset)[values(tag_subset) > 96] <- NA
names(tag_subset) <- 
  format(ymd(paste0(substring(
  names(tag_subset), 2
  ), ".01")), "%B %Y")

tag.det<-
  COAdata$`77523307` %>%
  mutate(sub = format(TimeStep.coa, "%B.%Y"))

coa.dat<-
  ungroup(tag.det) %>%
  dplyr::select(Longitude.coa,Latitude.coa,sub) %>%
  split(.$sub)

## Plot monthly KUD for tag `77523307`
library(rasterVis)

rasterVis::levelplot(tag_subset,
          names.attr = sub("[.]", " ", names(tag_subset)),
          xlim=c(151.85, 152.15), ylim=c(-23.55, -23.4),
          par.settings=viridisTheme,
          panel = function(..., at, contour = FALSE){
            panel.levelplot(..., at = at, contour = contour)
            panel.contourplot(..., at = c(50, 95), contour = TRUE, lty=1, col.regions="transparent")
            panel.points(coa.dat[[panel.number()]],
                         pch = 20,
                         cex = 0.2,
                         col = 4)
            }
          )

knitr::include_graphics('images/Fig6.png')

Interactive maps with leaflet

library(leaflet)

## Full KUD for all tagged animals
fullmap <- leaflet() %>%
  addProviderTiles(providers$Esri.WorldImagery)

for (i in 1:length(fullstack)) {
  tempras<-disaggregate(fullstack[[i]], fact=3, method='bilinear')
  values(tempras)[values(tempras) >95] <-NA
  fullmap <- 
    fullmap %>% 
    addRasterImage(tempras, opacity = 0.5, group = names(fullstack)[i])
}

coa.detections<-
  do.call(rbind, COAdata) %>%
  filter(Tag.ID %in% names(fullstack))

fullmap <- 
  fullmap %>%
  addCircleMarkers(lng = coa.detections$Longitude.coa, lat = coa.detections$Latitude.coa,
                   color = "red", radius = 1, weight=1, group = coa.detections$Tag.ID) %>%
  addCircleMarkers(lng = statinfo$station_longitude, lat = statinfo$station_latitude,
                   fill = F, color = "white", radius = 4, weight = 2, group = "Receiver Stations") %>%
  addMeasure(position = "bottomleft",
             primaryLengthUnit = "meters",
             primaryAreaUnit = "sqmeters") %>%
  addLayersControl(
    baseGroups = coa.detections$Tag.ID,
    overlayGroups = "Receiver Stations",
    options = layersControlOptions(collapsed = FALSE)
  )

fullmap

knitr::include_graphics('images/Fig7.png')

## Monthly KUD for tag `77523307`
submap<- 
  leaflet() %>%
  addProviderTiles(providers$Esri.WorldImagery)

for (i in 1:length(names(tag_subset))) {
  submap <- 
    submap %>% 
    addRasterImage(tag_subset[[i]], opacity = 0.5, group = gsub("[.]", " ", names(tag_subset)[i]))
} 

submap<- 
  submap %>%
  addCircleMarkers(lng = tag.det$Longitude.coa, lat = tag.det$Latitude.coa,
                   color = "red", radius = 1, weight=1, group = gsub("[.]", " ", tag.det$sub)) %>%
  addCircleMarkers(lng = statinfo$station_longitude, lat = statinfo$station_latitude,
                   fill = F, color = "white", radius = 4, weight=2, group = "Receiver Stations") %>%
  addLayersControl(
    baseGroups = gsub("[.]", " ", names(tag_subset)),
    overlayGroups = "Receiver Stations",
    options = layersControlOptions(collapsed = FALSE)
  )

submap

knitr::include_graphics('images/Fig8.png')

Plotting and exploring monthly KUD values using `plotly`

## ------------------------------------
## Monthly breakdown of KUDs
## Summary plots of KUDs over time

library(plotly)
library(lubridate)
## Interactive plotly
datly<- 
  BBkud_est$Subsetted %>%
  filter(Tag.ID %in% names(fullstack)) %>%
  mutate(Date = lubridate::ymd(paste0(subset,"-01")),
         ActivitySpace_km2 = BBKUD.95/(10^6))

p <- plot_ly(
  type = 'scatter',
  mode = "lines+markers",
  x = filter(datly, Tag.ID %in% unique(datly$Tag.ID)[1])$Date,
  y = filter(datly, Tag.ID %in% unique(datly$Tag.ID)[1])$ActivitySpace_km2,
  name = unique(datly$Tag.ID)[1])

for (id in unique(datly$Tag.ID)[-1]) {
  p <- p %>% 
    add_trace(x = filter(datly, Tag.ID %in% id)$Date,
              y = filter(datly, Tag.ID %in% id)$ActivitySpace_km2,
              name = id, mode="lines+markers", visible = FALSE)}

p <- p %>%
  layout(
    title = "Monthly extent of activity Space",
    xaxis = list(title = "Date"),
    yaxis = list(title = "Extent of Activity Space (km2)", rangemode = "tozero"),
    updatemenus = list(
      list(
        type="dropdown",
        y = 1,
        ## Add all buttons at once
        buttons = lapply(unique(datly$Tag.ID), FUN=function(id) {
          list(method="restyle", 
               args = list("visible", unique(datly$Tag.ID) == id),
               label = id)}))))
p

knitr::include_graphics('images/Fig9.png')

More functions to visualise standardised metrics coming soon!!

Citation

If you use these functions for publications the authors ask to please cite the use of the VTrack package using the following citation:

Campbell HA, Watts ME, Dwyer RG, Franklin CE (2012) V-Track: software for analysing and visualising animal movement from acoustic telemetry detections, Marine and Freshwater Research 63(9):815-820. doi: 10.1071/MF12194

The new Animal Tracking Toolbox operations can also be cited in publications using the following citation:

Udyawer V, Dwyer RG, Hoenner X, Babcock RC, Brodie S, Campbell HA, Harcourt RG, Huveneers C, Jaine FRA, Simpfendorfer CA, Taylor MD, Heupel MR (2018) A standardised framework for analysing animal detections from automated tracking arrays. Animal Biotelemetry 6(1):17. doi: 10.1186/s40317-018-0162-2

Authors

Vinay Udyawer
v.udyawer@aims.gov.au
Australian Institute of Marine Science

Ross Dwyer
ross.dwyer@uq.edu.au
University of Queensland

Xavier Hoenner
xavier.hoenner@utas.edu.au
Australian Ocean Data Network

Vignette version 1.0.3 (19 Dec 2018)

RossDwyer/VTrack documentation built on Feb. 23, 2024, 10:40 p.m.

rdrr.io home R language documentation Run R code online

CRAN packages Bioconductor packages R-Forge packages GitHub packages

Note that we can't provide technical support on individual packages. You should contact the package authors for that.

RossDwyer/VTrack
A Collection of Tools for the Analysis of Passive Acoustic Telemetry Data

In RossDwyer/VTrack: A Collection of Tools for the Analysis of Passive Acoustic Telemetry Data

Background

Installation

Functions within the toolbox

Input data formats

Tag detection data formats

VEMCO input format (`VEMCOdata`)

IMOS ATF input format (`IMOSdata`)

Tag metadata input format (`taginfo`)

Receiver metadata input format (`statinfo`)

Usage

Load the VTrack version >2.0 library

Setup data for smooth functioning with other ATT functions

Calculating detection metrics

Create an abacus plot

Calculating dispersal metrics

Calculating activity space metrics

Storing spatial data associated with activity space metrics

Map activity space

Interactive maps with leaflet

Plotting and exploring monthly KUD values using `plotly`

Citation

Authors

R Package Documentation

Browse R Packages

We want your feedback!

RossDwyer/VTrack A Collection of Tools for the Analysis of Passive Acoustic Telemetry Data

In RossDwyer/VTrack: A Collection of Tools for the Analysis of Passive Acoustic Telemetry Data

Background

Installation

Functions within the toolbox

Input data formats

Tag detection data formats

VEMCO input format (VEMCOdata)

IMOS ATF input format (IMOSdata)

Tag metadata input format (taginfo)

Receiver metadata input format (statinfo)

Usage

Load the VTrack version >2.0 library

Setup data for smooth functioning with other ATT functions

Calculating detection metrics

Create an abacus plot

Calculating dispersal metrics

Calculating activity space metrics

Storing spatial data associated with activity space metrics

Map activity space

Interactive maps with leaflet

Plotting and exploring monthly KUD values using plotly

Citation

Authors

R Package Documentation

Browse R Packages

We want your feedback!

RossDwyer/VTrack
A Collection of Tools for the Analysis of Passive Acoustic Telemetry Data

VEMCO input format (`VEMCOdata`)

IMOS ATF input format (`IMOSdata`)

Tag metadata input format (`taginfo`)

Receiver metadata input format (`statinfo`)

Plotting and exploring monthly KUD values using `plotly`