Skip to content

MagGeo Documentation

Welcome to the MagGeo API Documentation - A comprehensive guide to GPS trajectory annotation with geomagnetic data from ESA's Swarm satellites.

For Developers & Package Users

  • Quick Start --- Get MagGeo running in 5 minutes with installation and basic examples

  • API Reference --- Complete function reference with examples and parameters

  • User Guide --- Comprehensive guides for all MagGeo features and workflows

  • Examples --- Practical examples from basic usage of MagGeo to advanced parallel processing

For Researchers

Package Information

Installation

pip install maggeo

Quick Example

import pandas as pd
from maggeo.core import annotate_gps_with_geomag

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

# Annotate with geomagnetic data
result = annotate_gps_with_geomag(
    gps_data,
    lat_col='latitude',
    lon_col='longitude',
    datetime_col='datetime'
)

# Save annotated trajectory
result.to_csv('annotated_trajectory.csv')

What's New in v0.2.0

Major Performance Improvements

  • 5.6x faster processing for large trajectories
  • Enhanced parallel processing with smart chunking
  • SwarmDataManager for unified data handling
  • Comprehensive CLI with 4 commands

Documentation Structure

Section Purpose Audience
Getting Started Installation, setup, first steps All users
User Guide Detailed usage instructions Package users
API Reference Function documentation Developers
Examples Practical code examples All users
Scientific Site → Research background Researchers

Contributing

We welcome contributions! See our Contributing Guidelines for:

  • Bug reports and feature requests
  • Documentation improvements
  • Code contributions
  • Scientific validation and use cases

Citation

If you use MagGeo in your research, please cite:

Primary 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

Complete citation guide →