Are you a scientist involved in movement ecology working with biologging data collected from central-place foraging seabirds? cpforager is a Python package designed to help you manipulate, process, analyse and visualise the biologging datasets with ease.

The main objectives of cpforager are :

1. Efficiently handle large-scale biologging datasets, including high-resolution sensor data (e.g. accelerometers).
2. Provide a modular and extensible architecture, allowing users to tailor the code to their specific research needs.
3. Facilitate a smooth transition to Python for movement ecology researchers familiar with other languages (e.g. R).

cpforager package supports various biologging sensor types commonly used in movement ecology and provides the following core classes:

• GPS : for handling position recordings.
• TDR : for handling pressure recordings.
• AXY : for handling tri-axial acceleration recordings at high resolution combined with lower resolution position and pressure recordings.
• GPS_TDR : for handling position and pressure recordings.
• GPS_Collection : for working with datasets composed of multiple GPS loggers.
• TDR_Collection : for working with datasets composed of multiple TDR loggers.
• AXY_Collection : for working with datasets composed of multiple AXY loggers.
• GPS_TDR_Collection : for working with datasets composed of multiple GPS_TDR loggers.

Each class automatically enhances raw data but also computes key features specific to each biologger (e.g. trip segmentation for GPS, dive segmentation for TDR, ODBA calculation for AXY). They are also accompanied with methods for data processing and visualisation.

Installation

1. Fork this repository and then clone it on your local machine :

git clone https://github.com/AdrienBrunel/seabird-movement-cpf.git

2. Create a conda environment using the environment.yml file :

conda env create --name seabird-movement-cpf --file environment.yml

3. Open any Python script in /tests/ folder and start running line by line to check that everything is working.

4. Load your raw data in the data/ folder, create your own script and enjoy !

Documentation

The documentation of cpforager is automatically generated using Sphinx and can be found here.

User guide

The Python scripts in the /tests/ folder illustrate how the GPS, TDR, AXY, GPS_TDR, GPS_Collection, TDR_Collection, AXY_Collection and GPS_TDR_Collection classes can be used to fully benefit the users. Results of the scripts are also found in the /tests/ folder. For more details, you can browse the package documentation.

Future developments

• make classes' methods available in documentation.
• uniformise types of arguments/attributes in function arguments and accordingly in documentation.
• add a proper zero offset correction inside TDR class (according to the scientific consensus). See scikit-diveMove.
• complete and improve GPS_TDR class.
• write GPS_TDR test script and demo.
• write GPS_TDR_Collection test script and demo.
• improve folium map of GPS_Collection.
• use new dtypes dictionary for Collection classes.
• add a function GPS_TDR = merge_gps_tdr(GPS, TDR) that will merge TDR data within GPS data and produce the resulting dataframe.
• add Butterworth filter for AXY.
• add parameters in parameters.py to be able to choose between rolling average and Butterworth filter for AXY.
• hmmlearn for a state estimation of seabird behaviour.
• create first Github release / version 1.0.
• build Python package Python package building.
• draft for Applications in Methods in Ecology and Evolution.

Infos

• Python version used is 3.13.3.
• OS used is Ubuntu 20.04.
• The graphic design of the logos was done by Lisa Brunel.