MagGeo is a Python package to annotate GPS trajectories with geomagnetic data from ESA's Swarm satellite constellation. This tool enables researchers to annotate animal movement data with Earth's magnetic field measurements for animal movement analytics research.

Citation | Benitez-Paez, F., Brum-Bastos, V.d., Beggan, C.D. et al. Fusion of wildlife tracking and satellite geomagnetic data for the study of animal migration. Mov Ecol 9, 31 (2021). https://doi.org/10.1186/s40462-021-00268-4

• GPS Trajectory Annotation: Enrich GPS tracks with geomagnetic field components (N, E, C, H, D, I, F) and optionally witih indices (Kp, AE, SME)
• High Performance: 5.6x faster processing compared to the previous version.
• Parallel Processing: Efficient handling of large datasets so it can process large GPS trajectories in parallel.
• Swarm Data Integration: Direct access to ESA Swarm satellite geomagnetic data through the ViRES platform.
• Geomagnetic Indices: Integration with AE and SME geomagnetic activity indices for enhanced analysis.
• Command Line Interface: User-friendly CLI for batch processing and automation
• Comprehensive Documentation: Complete Research and API documentation with examples and tutorials.

• Full Documentation: MagGeo.github.io/MagGeo
• Quick Start Guide: Getting Started
• API Reference: API Documentation
• Examples: Usage Examples

pip install maggeo

# Clone the repository
git clone https://github.com/MagGeo/MagGeo.git
cd MagGeo

# Install in development mode
pip install -e ".[dev,docs]"

MagGeo requires Python 3.8+ and depends on:

• numpy, scipy, pandas - Core data processing
• matplotlib - Visualization capabilities
• viresclient - Swarm satellite data access
• chaosmagpy - CHAOS geomagnetic model
• click - Command-line interface
• tqdm - Progress bars for long operations

import pandas as pd
from maggeo.core import annotate_gps_with_geomag

# Load your GPS trajectory data
gps_data = pd.read_csv('your_trajectory.csv')

# Annotate with geomagnetic data
annotated_data = annotate_gps_with_geomag(
    gps_data,
    lat_col='latitude',
    lon_col='longitude', 
    datetime_col='datetime',
    altitude_col='altitude',  # Optional altitude column
    token='your_vires_token',  # ViRES API token for Swarm data access
)

# Save results
annotated_data.to_csv('trajectory_with_geomag.csv', index=False)

# Annotate a GPS trajectory file
maggeo annotate trajectory.csv --output annotated_trajectory.csv

# Download Swarm satellite data
maggeo swarm --start-date 2023-01-01 --end-date 2023-01-31

# Validate GPS file format
maggeo validate trajectory.csv

# Get package information
maggeo info

from maggeo.parallel_processing import parallel_maggeo_annotation
from maggeo.swarm_data_manager import SwarmDataManager

# For large datasets, use parallel processing
large_dataset = pd.read_csv('large_trajectory.csv')

annotated_data = parallel_maggeo_annotation(
    large_dataset,
    chunk_size=1000,  # Optimize based on your system
    n_jobs=-1         # Use all available cores
)

# Manage Swarm data efficiently
manager = SwarmDataManager()
swarm_data = manager.download_swarm_data(
    start_date='2023-01-01',
    end_date='2023-01-31',
    satellite='A'
)

This major refactor of MagGeo and introduces significant improvements:

• 5.6x faster processing for large trajectories
• Optimized memory usage with efficient data structures
• Smart chunking for parallel processing

• SwarmDataManager: Unified interface for Swarm data handling
• Enhanced CLI: Four comprehensive commands for all workflows
• Geomagnetic Indices: AE and SME index integration
• Improved Error Handling: Better validation and user feedback

• Modern Package Structure: PyPI-ready with pyproject.toml
• Comprehensive Documentation: MkDocs Material with API reference and Research documentation.
• Enhanced Testing: Expanded test suite with better coverage

• Initial Release: Initial functionality for trajectory annotation and repository setup, it uses Jupyter notebooks for examples and documentation.

• Major Refactor: Complete codebase restructuring for performance and usability
• Production Ready: Professional packaging, documentation, and testing
• Enhanced Capabilities: 5.6x performance improvement and expanded feature set
• Open Science: Full PyPI publication for broader scientific community access

If you use MagGeo in your research, please cite both the original methodology paper and the software:

Benitez-Paez, F., Brum-Bastos, V.d., Beggan, C.D. et al. Fusion of wildlife tracking and 
satellite geomagnetic data for the study of animal migration. Mov Ecol 9, 31 (2021). 
https://doi.org/10.1186/s40462-021-00268-4

Benitez-Paez, F., Demšar, U., Long, J. A., & Beggan, C. D. (2025). MagGeo: A Python package 
for fusion of GPS trajectories and satellite geomagnetic data (Version 0.2.0) [Computer software]. 
https://github.com/MagGeo/MagGeo

• Fernando Benitez-Paez - Lead Author and Developer - University of St Andrews
• Urška Demšar - Principal Investigator - University of St Andrews
• Jed A. Long - Co-Investigator - University of Western Ontario
• Vanessa Brum-Bastos - Co-Investigator - University of Canterbury
• Ciarán D. Beggan - Geomagnetic Expert - British Geological Survey

Contact: Fernando.Benitez@st-andrews.ac.uk

We welcome contributions from the scientific community! Please see our Contributing Guidelines for details on:

• 🐛 Bug Reports: Help us improve by reporting issues
• 💡 Feature Requests: Suggest new capabilities for movement ecology research
• 🔧 Code Contributions: Submit pull requests for enhancements
• 📖 Documentation: Improve guides and examples
• 🧪 Scientific Validation: Share use cases and research applications

MagGeo is released under the MIT License, allowing free use for academic and commercial applications with proper attribution.

• ESA Swarm Mission - For providing high-quality geomagnetic satellite data
• VirES Platform - For accessible Swarm data distribution
• Max Planck Institute of Animal Behavior - For feedback and Ecological validation
• Leverhulme Trust Grant - For funding support of the original research

MagGeo is a work in progress, and we are constantly making improvements that you can follow up with the commits made in the pubic GitHub repo. For general enquiries, scientific concepts, suggestions, please email: Fernando.Benitez@st-andrews.ac.uk, ud2@st-andrews.ac.uk, jed.long@uwo.ca

For errors, or improvements, please submit an issue in this repo, describing the problem you have.