MagGeo is a Python package for fusing 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 enhanced migration studies and movement ecology research.
- GPS Trajectory Annotation: Enrich GPS tracks with geomagnetic field components (N, E, C, H, D, I, F)
- High Performance: 5.6x faster processing compared to v0.1.0 through optimized algorithms
- Parallel Processing: Efficient handling of large datasets with automatic chunking
- Swarm Data Integration: Direct access to ESA Swarm satellite geomagnetic data
- Geomagnetic Indices: Integration with AE and SME geomagnetic activity indices
- Command Line Interface: User-friendly CLI for batch processing and automation
- Comprehensive Documentation: Complete API reference and user guides
- Full Documentation: MagGeo.github.io/MagGeo (available after publication)
- 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 processingmatplotlib- Visualization capabilitiesviresclient- Swarm satellite data accesschaosmagpy- CHAOS geomagnetic modelclick- Command-line interfacetqdm- 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'
)
# 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 infofrom 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 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 satellite 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
- Enhanced Testing: Expanded test suite with better coverage
- Type Hints: Improved code clarity and IDE support
MagGeo represents the evolution of a research prototype into a robust, production-ready scientific package:
- Initial Release: Basic functionality for trajectory annotation
- Community Adoption: Used by movement ecology researchers globally
- Feature Expansion: Added CHAOS model integration and basic parallel processing
- 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
📋 Complete citation guidelines with multiple formats →
Core Development Team:
- Fernando Benitez-Paez - Lead Developer - University of St Andrews
- Urška Demšar - Principal Investigator - University of St Andrews
- Jed A. Long - Co-Investigator - University of Western Ontario
- Ciarán D. Beggan - Geomagnetic Expert - British Geological Survey
Contact: [email protected]
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
- Movement Ecology Community - For feedback and scientific validation
- NERC, UKRI - For funding support of the original research
| Resource | Link |
|---|---|
| 📦 PyPI Package | https://pypi.org/project/maggeo/ |
| 📖 Documentation | https://MagGeo.github.io/MagGeo |
| 🐙 GitHub Repository | https://github.com/MagGeo/MagGeo |
| 📄 Original Paper | https://doi.org/10.1186/s40462-021-00268-4 |
| 🎯 Issue Tracker | https://github.com/MagGeo/MagGeo/issues |
MagGeo is 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: [email protected], [email protected], [email protected]
For errors, or improvements please submit an issue in this repo, describing the problem you have.