Skip to contents

Tools for processing and visualising high-throughput animal tracking data, developed for WATLAS (Wadden Sea Advanced Tracking and Localization of Animals in real-life Systems). For background on the WATLAS system and the associated research, see the research and publications page. Visit the WATLAS project page for the latest project news, and follow tracked birds in real time on the WATLAS live map.

Why tools4watlas?

tools4watlas was developed to:

  • Provide a consistent, reproducible workflow for analysing WATLAS tracking data.
  • Simplify the basic workflow of atlastools (Gupte et al. 2021) to make handling of large data sets faster and more memory-efficient. See Differences from atlastools for details.
  • Link tracking data to environmental data, such as water level, bathymetry, sun and moon, or any other raster layer.
  • Plot and animate data with easy to use base maps, functions and tutorials.

Who is it for and how to use it?

tools4watlas is mainly developed for anyone working with WATLAS data. However, Most functions only need coordinates (x, y), a timestamp (datetime) and a tag ID, so the package can also be used with other tracking data. The most likely user groups are:

  • Internal WATLAS data users: All functions and workflows can be used, and the local files can be accessed via the network. See Setup section for details and file paths.
  • External WATLAS data users: Shared WATLAS data may already be pre-processed. Besides this, all functions can be used and we are happy to share environmental datasets on request.
  • Users of other ATLAS systems: All basic functions can be used, but some are system-specific and may not be useful, such as the tidal and bathymetry data and the basemap function. For best results, we recommend forking the repository and adapting it to your system requirements. Basemap data can be replaced by following Extract basemap data, and atl_add_raster_data() works with any raster data.
  • GPS users: The basic processing functions also work with GPS data. However, we recommend following the standard processing procedures of packages specialised in GPS data, such as move2 or amt. The plotting and animation tutorials can still be useful, and for data from the Wadden Sea, the functions that link tracks to local environmental data can be useful as well.

Feel free to reach out by e-mail for questions or collaborations if you would like to work with WATLAS data.

Documentation

The tools4watlas package is thoroughly documented on the official package website. See Get started for a complete overview of all articles. In short: The package articles outline the basic workflow for working with WATLAS data, while extended workflows guide through more specialized analyses. Additionally, we provide visualization tutorials that demonstrate various methods for plotting and animating the movement data. The package development section offers insights into package maintenance and how to contribute to the tools4watlas package.

Installation

You can install the latest version of tools4watlas from GitHub with:

library(remotes)
install_github("allertbijleveld/tools4watlas")

# additional installs packages used in articles, but not needed by the package
install_github("allertbijleveld/tools4watlas", dependencies = TRUE)

Example data

library(tools4watlas)
library(ggplot2)

# Load example data
data <- data_example

# Create base map
bm <- atl_create_bm(data, buffer = 800)

# Plot points and tracks
bm +
  geom_path(
    data = data, aes(x, y, colour = species),
    linewidth = 0.5, alpha = 0.5, show.legend = FALSE
  ) +
  geom_point(
    data = data, aes(x, y, color = species),
    size = 0.5, alpha = 0.5, show.legend = TRUE
  ) +
  scale_color_manual(
    values = atl_spec_cols(),
    labels = atl_spec_labs("multiline"),
    name = ""
  ) +
  guides(colour = guide_legend(
    nrow = 1, override.aes = list(size = 7, pch = 16, alpha = 1)
  )) +
  theme(
    legend.position = "top",
    legend.justification = "center",
    legend.key = element_blank(),
    legend.background = element_rect(fill = "transparent")
  )
Example tracks with one individual by species for two tide cycles

Example tracks with one individual by species for two tide cycles

Contribute

If you want to contribute to tools4watlas fork the repository on GitHub and then submit a pull request. Besides clear bug fixes, it is best to discuss potential changes or additions with Allert Bijleveld. Check the article Contributing to tools4watlas for more details.

Acknowledgements

We thank Pratik Gupte for earlier code development, and Christine Beardsworth, Jet Carabain, Antsje van der Leij Freddie Mckendrick and Hans Linssen for testing and providing valuable feedback to tools4watlas. Many people and organisations are involved in developing and maintaining WATLAS. We thank Sivan Toledo and Ran Nathan for the initial development of ATLAS, and Frank van Maarseveen and Bas Denissen for the initial development of the Wadden Sea ATLAS (WATLAS). Additionally, we thank Remko de Haan, Aris van der Vis, Yetzo de Hoo, Marten Tacoma, and NMF colleagues for further developments, assemblage and support. Anne Dekinga is crucial for logistical solutions, and with Kasper van Kraaij for field deployment, maintenance and support. We thank our colleagues from COS for help catching birds, especially Job ten Horn, Anne Dekinga, and Luc de Monte. Also, we thank all partners and stakeholders for hosting equipment and for access to their sites. Lastly, we thank the crews of the RV Wim Wolff and Wim-Jan Boon of the RV Adriaen Coenen for their help in the field and the many other NIOZ staff, students and volunteers that facilitated this work.

nioz website