A simple Anabat file reader

For more years than I care to mention, I have been tinkering with code to read data files produced by Anbat bat call detectors. Unfortunately, I don't have access to that bidy of work anymore and so I recently truned my attention to reinventing that wheel.

These days I do most of my data analysis using the R statistical environment and so I chose this paltform to develop a small but (I hope) perfectly formed set of functions to read and display Anabat files.

For those readers not familiar with the Anabat system, they are zero-crossing ultrasonic call detectors. (For background see this webpage.) Anabat was developed in the late 1980s and early 1990s by Chris Corben but for many years it has been a fully conmmercial product from Titley Electronics.

Chris Corben provides very detailed technical notes, and a C++ code fragment, on his website showing the basic methods for unpacking an Anabat data file. I used the C++ code as a framework for the R functions which are the subject of this post.

There are two main functions, readAnabat() and plot.Anabat(). The first has only one parameter, a string giving the path to an Anabat data file to be read. readAnabat can interpet all 4 file types described by Chris Corben on his website, i.e. types 129, 130, 131 and 132. The function returns a simple S3 object with the unpacked frequency and time data, plus associated parameters. That means the basic data is accessible to users wishing to perform further analysis.

The function plot.Anabat() produces a basic frequency-time plot familiar to anyone who has used the Windows-only tool AnalookW supplied with Anabat detectors (and freely downloadable from the Titley website). Some of us are old enough to recall that the basic plot has not changed from the MSDOS days! plot.Anabat provides several parameters (all with default values) to allow the user to:

• turn frequency guidelines on or off, and specify their line style and colour;
• change the colour, size and plot symbol used;
• give a cut-off frequency to turn off dots below that frequency thus giving a very crude frequency filter that is nevertheless quite useful for cleaning up noisy plots;
• specify the upper and lower frequencies to be plotted; and,
• specify a start and end time for the plot (effectively providing a stretching of the time axis for a selected block of dots).

The concept behind these simple functions is to allow casual R users to make use of them without needing to do additional scripting. More advanced users have all the data available in the S3 object.

Here are some examples of function usage to make these ideas concrete and illustrate how useful even these simple functions can be. As example data, I used a call file from the NSW Bat Call Library downloadable from this site.

First, here is a call to produce the default, full call sequence plot:

source("~/R-scripts/Anabat_reader/AnabatTools.R")

## Loading required package: stringr
## Loading required package: bitops

chirp <- readAnabat("~/Bioacoustics/NSW Bat Call Library/calls/Sydney/Chalgoul/Chgo-syd.01#")
plot.Anabat(chirp)

There is no point in plotting frequencies above 80 kHz for this data, so set maxFreq = 80000 and we get the following plot:

plot.Anabat(chirp, maxFreq = 80000)

Now, here is the same data, but focussing on a time block from 5.5 seconds to 6.2 seconds:

plot.Anabat(chirp, maxFreq = 80000, startTime = 5.5, endTime = 6.2)

There is some noise below about 30 kHz, so let's set cleanBelow = 30000 and make things much neater:

plot.Anabat(chirp, maxFreq = 80000, startTime = 5.5, endTime = 6.2, cleanBelow = 30000)

I hope you find these functions useful. Please note that AnabatTools depends on the R-packages stringr and bitops which you will need to install from the CRAN repositories. You can download the source code for AnabatTools from this location. Your browser should display the R-script file like text. Use your browser's “Save page as…” option to save it to a folder.