ABISSMAL: Automated Behavioral tracking by Integrating Sensors that Survey Movements Around a target Location

Developers:
Tania Molina: tanismo@lastralab.com
Grace Smith-Vidaurre, PhD: gsvidaurre[at]gmail.com

Documentation
Project Wiki

Tracking System Overview

ABISSMAL is a hardware and software platform for automated behavioral tracking with built-in system monitoring and error logging. ABISSMAL also provides the capacity to make behavioral inferences by integrating data across multiple types of movement sensors. We tested the tracking system by tracking parental care behaviors with captive zebra finches that raised young birds over 50 days. See the accompanying methods manuscript for more detailed information about ABISSMAL. Our Wiki page has detailed information about how to set up and build hardware, as well as software installation and troubleshooting.

Pre-requisites

Please refer to our Wiki page Set up Raspberry Pi and tracking system before proceeding. There are a few pre-requisites to consider before running the installation script.

Installing ABISSMAL

           ____ _____  _____ _____ __  __          _      
     /\   |  _ \_   _|/ ____/ ____|  \/  |   /\   | |     
    /  \  | |_) || | | (___| (___ | \  / |  /  \  | |     
   / /\ \ |  _ < | |  \___ \\___ \| |\/| | / /\ \ | |     
  / ____ \| |_) || |_ ____) |___) | |  | |/ ____ \| |____ 
 /_/    \_\____/_____|_____/_____/|_|  |_/_/    \_\______|

1. Clone this repository to the Pi by running

   git clone https://github.com/lastralab/Abissmal.git

2. From the root directory `/path/to/Abissmal/` run the following commands to install and run the ABISSMAL tracking system:
1. Initiate the installation script, which will prompt you to enter information

   sudo bash run_install.sh

2. Enter your Pi password (we strongly recommend setting a password for your Raspberry Pi)
3. When prompted, insert the additional ABISSMAL setup information accordingly
4. The Pi will restart automatically to apply changes
5. If you are using an ssh connection to connect to the Pi, then you will need to mount the external hard drive
3. Run command to initiate ABISSMAL and start collecting data (wihout sudo)

   bash Main.sh

1. Follow instructions to setup the system accordingly

File Structure Overview

This repository holds the following directories and files. See the README files in each directory below for more detailed information:

3D

A directory that holds 3D-printing designs for customized hardware in .stl format. Some of these files were used in earlier versions of ABISSMAL (RFID antenna holder) and are not currently used.

Modules

A directory that holds software modules in Python 3 and the bash shell for automated data collection and system monitoring, as well as software for error logging.

R

A directory that contains a series of computational analyses as R functions, as well as code for unit-testing these functions.

Video Concatenation

A directory that holds scripts for video concatenation with ffmpeg. This code was originally written to merge pre- and post-motion detection videos but is currently not used in ABISSMAL.

Main.sh

The main script that initiates the ABISSMAL tracking system. See the Wiki page for more information.

cron.sh

A script for task scheduling through cron jobs. This script is automatically used by ABISSMAL for data collection, system monitoring, and error logging to run continuously over time.

run_install.sh

A script for automated installation of software dependencies, setting up cron jobs, and setting up automated text alerts through Twilio (optional, and users will need to create their own Twilio account). See the Wiki page for more information.

Issue templates and other files

The directory .github/ISSUE_TEMPLATE contains templates for different types of issues. The file .gitignore contains information about which files should be ignored (not tracked) by Git. The LICENSE file holds information about the open-access license for this repository. The README.md file holds this documentation for the main repository.

Additional Documentation

The Issues tab holds open issues (bugs, new features, documentation update requests) that are in progress. You can also check out issues that were closed over time. The Projects tab has a Kanban-board style timeline that we are using for project management. The Wiki tab has 5 major sections with detailed documentation:

1. Project Management
2. Setting up Raspberry Pi computers and ABISSMAL software
3. Building a custom nest container
4. Setting up sensors and other hardware
5. Troubleshooting software and hardware issues

Citing ABISSMAL

If you are using or modifying one or more components of the ABISSMAL tracking system, then please cite the associated methods paper.
Paper citation:
Smith-Vidaurre, G., Molina, T., Jarvis, E.D., and Hobson, E.A. (2023). Automated tracking of avian parental care behavior. Submitted. EcoEvoRxiv preprint: https://doi.org/10.32942/X2Z60C

Reporting issues while using ABISSMAL

Anyone using ABISSMAL is welcome to post issues about bugs. We will do our best to respond and help with bugs, but our top priority will be to fix bugs that hinder data collection, system monitoring, error logging, data cleaning, and processing for the current version of ABISSMAL.
This tracking system can be modified for different questions that require behavioral tracking, as well as for different species and/or research settings. Those interested in modifying the system for other purposes are welcome to do so independently, as long as you cite both the associated methods paper (currently a preprint), and this GitHub repository. Unless we have come to an agreement with collaborators who are adapting ABISSMAL, we will not have time to help individuals or research teams modify the tracking system.

Contributing to ABISSMAL as an open-access tool

We have laid out collaborative roles for contributing to ABISSMAL code development in our Wiki Project Management page. Contributing to ABISSMAL code development requires a local version of all components of the tracking system, including sensors and other hardware. As such, we are limiting ABISSMAL code contributions to the current developers (Tania Molina, Grace Smith-Vidaurre) and future members of the Smith-Vidaurre lab who will have access to the full set of hardware needed to test code. The lab may add additional layers of data collection and processing in future releases of ABISSMAL. We recommend that others who interested in modifying ABISSMAL fork this repository as a foundation for independent customization.

Ethics Statement

We developed and tested this tracking system with an institutional animal care and use (IACUC) protocol that was approved for captive zebra finches by Rockefeller University. If you plan to use this tracking system for research with live animals (captive or wild), then you must have your own approved institutional protocols and permits for ethical and responsible use of animals in research.