FishDiveR

What it does

Tags such as pop-up satellite archival tags record depth every few seconds or minutes for months at a time. Most studies still summarise those records as time-at-depth histograms, which lose the timing and rhythm of how an animal moves through the water column.

FishDiveR keeps that information. It splits a depth record into 24-hour days and describes each day in two ways: depth statistics, such as mean depth, vertical speed and day–night differences, and wavelet analysis, which picks out repeating patterns from five-minute cycles up to the daily cycle. Principal component analysis condenses the wavelet results, and k-means clustering then groups days with similar behaviour.

The result is a set of behaviour clusters, such as diel vertical migration, reverse diel migration, bounce diving or near-surface activity, with every day of the record assigned to one, ready for plotting and further analysis.

How it works, in four steps

Each 24-hour day, midnight to midnight in local time, becomes one row of data.

1. Continuous wavelet transform. Finds how strongly the depth record oscillates at each period, from minutes to a day, at every point in time. Unlike a Fourier transform, it copes with behaviour that changes through the record.
2. Daily statistics. Summarises the wavelet for each day and period, and calculates depth statistics from the record itself: mean and maximum depth, vertical speed, time near the surface and, optionally, differences between day and night.
3. Principal component analysis. Condenses the many, closely related wavelet statistics into a few components.
4. K-means clustering. Groups the days into behaviour clusters using the components and depth statistics together. Elbow and silhouette plots help choose the number of clusters.

The tutorial runs every step on the example tag that comes with the package, with the code and real output.

Documentation

Tutorial: from tag archive to behaviour clusters

The full workflow in R, step by step, with how to choose each setting and a reference list of every function.

The point-and-click app

Run the whole analysis in your browser without writing code. Your data stay on your computer.

Large, high-frequency records

Estimating memory, thinning 1-second records without aliasing, and plotting millions of points fast.

Function reference

Every function and argument, on the package’s documentation site.

Install

# From CRAN
install.packages("FishDiveR")

# Development version from GitHub, with the app and the latest features
# install.packages("remotes")
remotes::install_github("calvinsbeale/FishDiveR")

Please report problems on GitHub.

Common questions

How to cite FishDiveR

If you use FishDiveR in published work, please cite the methods paper:

Beale, C. S., Hounslow, J. L., Beer, A. J. E., Braccini, M., Erdmann, M. V., Harry, A., Loneragan, N. R., Meekan, M., Newman, S. J., Righton, D., Runtuboy, F., Travers, M. J., Wright, S., & Gleiss, A. C. (2026). FishDiveR: wavelet analyses and machine learning provide robust classification of animal behaviour from time-depth data. Movement Ecology, 14, 8. doi.org/10.1186/s40462-025-00622-w

BibTeX:

@article{Beale2026FishDiveR,
  title   = {{FishDiveR}: wavelet analyses and machine learning provide robust
             classification of animal behaviour from time-depth data},
  author  = {Beale, Calvin S. and Hounslow, Jenna L. and Beer, Angela J. E. and
             Braccini, Matias and Erdmann, Mark V. and Harry, Alastair and
             Loneragan, Neil R. and Meekan, Mark and Newman, Stephen J. and
             Righton, David and Runtuboy, Ferawati and Travers, Michael J. and
             Wright, Serena and Gleiss, Adrian C.},
  journal = {Movement Ecology},
  year    = {2026},
  volume  = {14},
  number  = {1},
  pages   = {8},
  doi     = {10.1186/s40462-025-00622-w}
}

Links

• Methods paper in Movement Ecology (open access)
• FishDiveR on CRAN
• Package documentation site
• Source code on GitHub