V-Track, R and the analysis and visualisation of acoustic telemetry data


Dear workshop attendee,

This course was designed, not to comprehensively cover all the spatio-temporal tools for analysing acoustic telemetry data in R (there are far too many to cover in one course), but to teach you skills for getting started in analysis of your acoustic tracking dataset. You can build on the basics I teach you today to perform a wide variety of analyses. Every new project comes with its own problems and questions and I have found having some knowledge of spatial tools in R allows us to develop new tools and analyses as they are needed.

The course documents will provide an overview on processing underwater acoustic telemetry data in R. We include both raw acoustic detection data exported from the AATAMS database (“blue_groper_detections_GG.csv”) AND VPS-estimated locations (“wobbegong_VPS_GG.csv”). These datasets were provided by Kate Lee and Rob Harcourt (Macquarie University, Sydney) and falls under their copyright. Their permission is required if you want to redistribute or build on these datasets outside this workshop.

By the end of this course you should be familiar with the R environment, our V-Track software and a selection of other spatial packages for R. This includes how to import, manipulate and export acoustic detection data, residence and movement events, and spatial data using R.

R can make the processing of your acoustic telemetry data much quicker and easier than using standard spreadsheet or GIS software. As R is open source, the more people we can get helping out on the R spatial mailing lists and contributing their own spatial packages to the wider community, the more powerful R becomes.

I provide most of the code for completing the tasks in the workshop below. However, I encourage you to type the code out from the notes as this will help you learn and understand the tasks.

Getting started

Obtaining R

If you do not currently have R installed on your machine, R can be downloaded from http://cran.r-project.org/. Using a script editor, such as R Studio, can make the writing and editing of code much more enjoyable and far less challenging. If you do not currently have R Studio installed on your machine, it can be downloaded from http://www.rstudio.com/.

Starting R

First open the R Studio program on your computer. You will find the interface is divided into several panels (clockwise from top left):

  1. the source code (supporting tabs)
  2. the currently active objects/history
  3. a file browser/plot window/package install window/R help window (tabbed)
  4. the R console

If there is only 3 windows open, click the “new document” icon located immediately below the File menu in the top left of your screen. Select new “R Script”.

The source code editor in the top left window is where you type, edit and save your R code. The editor supports text highlighting, auto completes common functions and parentheses, and allows the user to select R code and run it in the R console (bottom right) with a keyboard shortcut (Ctrl R).

When coding in R, make sure you type your commands (shown as Courier New font) in this source code window. This is where your code can be saved. If you type directly into the console, you cannot save your work, run sections of code or trace through the history of your R code.

Exercise 1: Introduction to V-Track

What is V-Track?

V-Track is a collection of functions created by researchers at the University of Queensland to enable the analysis and visualisation of detection data from the VEMCO suite of receivers and transmitters. It was written within the R programming language and is free and open source software. V-Track is available as an R package for use in Windows, Mac OS or Linux.

What can you do with V-Track?

The routine steps for the processing of the acoustic detection data in V-Track are:

  1. Archiving the detection database into a more manageable format
  2. Creation of sub-archives based upon study parameters
  3. Creation of a distance matrix using direct or circuitous distances between receivers
  4. Identification of animal behavioural events within the detection sub-archives
  5. Organisation behavioural events by temporal conditions
  6. Create animations to visualise animal movement in Google Earth

V-Track will assimilate acoustic transmissions derived from the VEMCO suite of continuous and coded tags and detected by the VR2 and VR2-W receivers. Data formats which can be read include Default and 1.0 formats from VUE or archived acoustic data stored within the AATAMS database.

How do find out more about V-Track?

More information about the software can be found at our website http://www.uq.edu.au/eco-lab/v-track.

Or in our publication in Marine and Freshwater Research;

Campbell, H.A., Watts, M.E., Dwyer, R.G., Franklin, C.E. 2012. V-Track: software for analyzing and visualising animal movement from acoustic telemetry detections. Marine and Freshwater Research, 63:815–820 DOI:10.1071/MF12194 http://www.publish.csiro.au/?paper=MF12194

Loading packages

Once the packages have been installed, you will then need to load the package from your local R library

If R tells you that a package is missing when attempting this library() command, chances are that you have either not installed it using the install.packages() command, or you have spelt the package name incorrectly.

Getting more information about these packages

#For the package:

?VTrack  (Note: This does not work for all R packages)

#For a specific function:

When writing R scripts, I would strongly advise you to put # comments # throughout your R scripts, you will thank yourself when you go back to the analysis later!

Importing data into R

R can read data in a number of formats. In this course we will cover how to 1. import excel tables (.csv) into R and 2. how to import ESRI Shape files into R

Set your working directory

Before you start, you will need to set the working directory. This is where all your data will be stored and saved. You will need to specify a different working directory to the one below.

setwd("C:/Users/rdwyer/Desktop/Genes to Geosciences")

Note: it’s worth thinking about the structuring of your working directory. In the course documents I have supplied the files within separate folders of a working directory (i.e. R code, Data, Images, Shp files). This way, it becomes much more straightforward to locate data rather than having files stored across multiple project folders, or cluttered within a single folder.

Import raw acoustic detection data into R

In this exercise you will load an excel table containing the raw acoustic detections of 21 eastern blue gropers (Achoerodus viridis) monitored for two months around the Bronte-Coogee Aquatic Reserve (BCAR). BCAR is a small MPA (0.43 km^2) in the Sydney metropolitan area. The reserve was initially implemented to protection for invertebrates, but community pressure resulted in part of the reserve being designated a ‘no-take’ area for the iconic eastern blue groper. More information on this study can be found in

Kate A. Lee, Charlie Huveneers, Tracy MacDonald and Rob G. Harcourt (2014) Size isn’t everything: movements, home range, and habitat preferences of eastern blue gropers (Achoerodus viridis) demonstrate the efficacy of a small marine reserve. Aquatic Conserv: Mar. Freshw. Ecosyst.

This data set was kindly provided by Kate Lee and Rob Harcourt as an example data set in the Genes to Geosciences workshop. Please contact them directly if you would like to know more about the study.

This file contains the raw acoustic detection of 21 acoustic-tagged blue groper and was exported from the AATAMS database. The file contains the following column names:

"timestamp",  "station.name", "latitude", "longitude", "receiver.ID" ,"tag.ID"        
 "species" ,  "uploader",  "transmitter.ID", "organisation",   "sensor.value",   "sensor.unit". 

Let’s upload the data set into R and have a look at the data.

groper.df <- read.csv("Data/blue_groper_detections_GG.csv")
head(groper.df) # Returns the first 6 rows of data
##             timestamp   station.name  latitude longitude receiver.ID
## 1 2010-03-03 08:10:00         BCAR 2 -33.91009  151.2727 VR2W-105861
## 2 2010-02-11 19:00:00         BCAR 2 -33.91009  151.2727 VR2W-105861
## 3 2010-03-04 04:25:00         BCAR 4 -33.91709  151.2730 VR2W-101689
## 4 2010-01-22 01:02:00         BCAR 2 -33.91009  151.2727 VR2W-105861
## 5 2010-01-02 04:56:00         BCAR 2 -33.91009  151.2727 VR2W-105861
## 6 2010-03-25 07:54:00 CTBAR Headland -33.79785  151.2962 VR2W-101758
##           tag.ID                                             species
## 1 A69-1303-59400 37384043 - Achoerodus viridis (Eastern Blue Groper)
## 2 A69-1303-59398 37384043 - Achoerodus viridis (Eastern Blue Groper)
## 3 A69-1303-59409 37384043 - Achoerodus viridis (Eastern Blue Groper)
## 4 A69-1303-59400 37384043 - Achoerodus viridis (Eastern Blue Groper)
## 5 A69-1303-59399 37384043 - Achoerodus viridis (Eastern Blue Groper)
## 6 A69-1303-59419 37384043 - Achoerodus viridis (Eastern Blue Groper)
##   uploader transmitter.ID organisation sensor.value sensor.unit
## 1 Kate Lee A69-1303-59400  AATAMS-IMOS           NA          NA
## 2 Kate Lee A69-1303-59398  AATAMS-IMOS           NA          NA
## 3 Kate Lee A69-1303-59409  AATAMS-IMOS           NA          NA
## 4 Kate Lee A69-1303-59400  AATAMS-IMOS           NA          NA
## 5 Kate Lee A69-1303-59399  AATAMS-IMOS           NA          NA
## 6 Kate Lee A69-1303-59419  AATAMS-IMOS           NA          NA
class(groper.df)# Note the dataset is of class data.frame
## [1] "data.frame"
# Access data in the data frame 
# Columns
groper.df[,4] # return data in fourth column
groper.df[,"longitude"] # same as above but using name
groper.df$longitude # same as above but using a dollar sign

# Rows
groper.df[3,] # return data in third row

# Cells
groper.df[3,3] # return data in cell in third row and in third 

Next we query the dimensions of the raw AATAMS data set using the dim() function in R

# How big is the dataset
## [1] 42760    12

Convert a AATAMS data file into a V-Track archive

As there are a number of potential formats that raw acoustic detection data could be in (e.g. VUE Default, VUE 1.0, AATAMS), we use the ReadInputData function in V-Track to reformat and standardise the data frame. In the below line of code we tell the function that the groper detection data file is in the AATAMS format and also specify the format of the date time string. This code then converts the data frame into the V-Track archive format and removes any duplicate detections. Reducing the number of columns also speeds up the subsequent data manipulation processes and analyses in R.

# Convert data into the VTrack archive format
Vgroper <- ReadInputData(infile=groper.df,
                         dateformat = "%Y-%m-%d %H:%M:%S") 

head(Vgroper) # Show the first six lines of the new data frame
## 15417 2009-12-31 13:19:00 A69-1303-59398                VR2W-105861
## 16477 2009-12-31 13:36:00 A69-1303-59398                VR2W-105861
## 4179  2009-12-31 14:34:00 A69-1303-59399                VR2W-105861
## 32633 2009-12-31 14:38:00 A69-1303-59398                VR2W-105861
## 6375  2009-12-31 14:41:00 A69-1303-59399                VR2W-105861
## 8041  2009-12-31 14:46:00 A69-1303-59399                VR2W-105861
## 15417      BCAR 2
## 16477      BCAR 2
## 4179       BCAR 2
## 32633      BCAR 2
## 6375       BCAR 2
## 8041       BCAR 2
dim(Vgroper) # Notice the reduction in columns
## [1] 39875     6
# More information on the functions can be found using the “?” 
# command

V-Track doesn’t like spaces between the Station Names, so let’s replace these spaces in with decimal points

Vgroper$STATIONNAME <- gsub(" ",".",Vgroper$STATIONNAME)

# Let’s also remove the code space to leave the transmitter 
# number to make our lives simpler
Vgroper$TRANSMITTERID <- do.call(rbind,strsplit(as.character(Vgroper$TRANSMITTERID), split="-"))[,3]

## 15417 2009-12-31 13:19:00         59398                VR2W-105861
## 16477 2009-12-31 13:36:00         59398                VR2W-105861
## 4179  2009-12-31 14:34:00         59399                VR2W-105861
## 32633 2009-12-31 14:38:00         59398                VR2W-105861
## 6375  2009-12-31 14:41:00         59399                VR2W-105861
## 8041  2009-12-31 14:46:00         59399                VR2W-105861
## 15417      BCAR.2
## 16477      BCAR.2
## 4179       BCAR.2
## 32633      BCAR.2
## 6375       BCAR.2
## 8041       BCAR.2

Notice how the tag code space has now been removed from the TRANSMITTERID column.

You can save this data frame as a .csv file using the write.csv() command in R. This will allow you to view the file in Microsoft Excel and other spreadsheet programs.


Generate the V-Track POINTS file and Distance Matrix from a Raw AATAMS data file

To assist with plotting the receiver array on a map and to generate our distance matrix between our stations using V-Track, let’s generate a V-Track points file from the AATAMS exported data.

VR2Array <- unique(groper.df[,c("station.name","latitude","longitude")]) 

# Change the column names match those expected by V-Track
# At this stage we don’t know what the receiver detection 
# radii are so let’s set this to zero
VR2Array$RADIUS <- 0

# Let’s make sure our station names are the same as our 
# V-Track archive file by replacing the space with a decimal 
VR2Array$LOCATION <- gsub(" ",".",VR2Array$LOCATION)

# Now reset our row names and print the first 6 rows of data
row.names(VR2Array) <- NULL
## 1         BCAR.2 -33.91009  151.2727      0
## 2         BCAR.4 -33.91709  151.2730      0
## 3 CTBAR.Headland -33.79785  151.2962      0
## 4         BCAR.5 -33.91809  151.2678      0
## 5         BCAR.3 -33.91357  151.2734      0
## 6         BCAR.7 -33.92162  151.2621      0
# plot the array

Mapping your spatial class objects on Google’s Baselayers

Thanks to the people at Google, there are free and relatively high resolution maps available online and accessible within R.

Once you have loaded the dismo R package, it is very simple to retrieve a ‘Google Map’ that can be used as a background for plotting points and other spatial data.

You should check the terms of service before you use these maps: http://code.google.com/apis/maps/terms.html

g <- gmap('Australia',type='terrain')

You can also use an extent to plot the data of interest, or a spatial* class object which we will discuss in the next section

g <- gmap(extent(151.259, 151.299, -33.94104,-33.79785),  type='satellite',lonlat=TRUE)