space-mango 0.1.1

Python client and server for the MANGO magnetospheric dataset

MANGO: Magnetospheric Atlas from Normalized Geospace Observations

Overview

MANGO is a dataset and Python toolkit for the global analysis of Earth's magnetosphere. Unlike raw satellite observations, MANGO provides a unified, classified, and spatially normalized view of geospace, where each datapoint is contextualized by its magnetospheric region and upstream solar wind conditions and repositioned relative to dynamic boundaries like the magnetopause and bow shock.

By accounting for the dynamic nature of magnetospheric boundaries, MANGO allows researchers to treat disparate satellite observations as part of a single, coherent atlas.

Key Features

Every data point in the MANGO dataset is:

• Classified: Labeled by its specific magnetospheric region (magnetosphere, magnetosheath, solar wind).
• Contextualized: Associated with the causal upstream solar wind conditions retrieved from OMNI data.
• Normalized: Repositioned spatially relative to dynamic boundaries (the bow shock and magnetopause).

The Python package provides:

• A client for querying the public MANGO server — returns Polars DataFrames via Arrow IPC.
• A server (optional) for self-hosting the dataset with FastAPI.
• Data-driven filter catalog — range filters on IMF, solar wind, spatial coordinates, and local plasma parameters.

---

Installation

# Client only (query the public server)
pip install space-mango

# With server dependencies (self-hosting)
pip install space-mango[server]

Quick Start

import space_mango as sm

# List available regions
sm.regions()
# ['magnetosphere', 'magnetosheath', 'solar_wind']

# Get magnetosheath data with southward IMF and high dynamic pressure
df = sm.get_data("magnetosheath", bz_imf_max=-2, pd_sw_min=3)

# Select specific columns and spacecraft
df = sm.get_data(
    "magnetosphere",
    columns=["Time", "X_gsm", "Y_gsm", "Z_gsm", "Np", "Bz"],
    spacecraft=["MMS1", "THA"],
    time_min="2015-01-01",
    time_max="2020-12-31",
)

# List available filters for a region
sm.filters("magnetosheath")

# List columns
sm.columns("magnetosphere")

Self-Hosting

# Start the server (requires mango[server])
mango serve --data-dir /path/to/parquet/data

# Docker
./docker/build.sh
docker run -d -p 8000:8000 -v /path/to/data:/data/mango:ro mango

The server supports deployment behind a reverse proxy via MANGO_ROOT_PATH:

docker run -d -p 8000:8000 \
  -e MANGO_ROOT_PATH="/mango" \
  -v /path/to/data:/data/mango:ro mango

📚 References

List of publications using the MANGO dataset:

---

🚀 2026

• The MANGO dataset: Magnetospheric Atlas of Normalized Geospace Observations Michotte de Welle, B., Aunai, N., Ghisalberti, A., Lavraud, B., et al.
  In prep. for Nature Scientific Data

---

🚀 2025

• Statistical Estimate of the Magnetopause Reconnection Rate as a Function of the Interplanetary Magnetic Field Clock Angle Michotte de Welle, B., Aunai, N., Lavraud, B., et al.
  ESS Open Archive, Septembre 2025.
  🔗 DOI: 10.22541/essoar.175745453.30048233/v1

• A New X-Line Model: Comparison to MHD Magnetic Separator Michotte de Welle, B., Connor, H., Sibeck, D., Glocer, A., Fuselier, S., Trattner, K., Petrinec, S., Brenner, A., Bagheri, F., & Lee, S.
  Journal of Geophysical Research (Space Physics), 130(11).
  🔗 DOI: 10.1029/2025JA034558 | 🌌 ADS

• The Speed of Interplanetary Shocks Through the Magnetosheath: A Toy Model Moissard, C., Butcher, C., Ruler, E., Richardson, J., Michotte de Welle, B., Steward, W., Pritchard, M., et al.
  Geophysical Research Letters, 52(7).
  🔗 DOI: 10.1029/2024GL113488 | 🌌 ADS

---

🛰️ 2024

• Advanced Methods for Analyzing in-Situ Observations of Magnetic Reconnection Hasegawa, H., Argall, M. R., Aunai, N., ..., Michotte de Welle, B., ..., & Zenitani, S.
  Space Science Reviews, 220(6).
  🔗 DOI: 10.1007/s11214-024-01095-w | 🌌 ADS

• Surface Charging of the Jupiter Icy Moons Explorer (JUICE) Spacecraft in the Solar Wind at 1 AU Holmberg, M. K. G., Jackman, C. M., Taylor, M. G. G. T., Witasse, O., Wahlund, J.-E., Barabash, S., Michotte de Welle, B., et al.
  Journal of Geophysical Research (Space Physics), 129(9).
  🔗 DOI: 10.1029/2023JA032137 | 🌌 ADS

• Global Environmental Constraints on Magnetic Reconnection at the Magnetopause From In Situ Measurements Michotte de Welle, B., Aunai, N., Lavraud, B., Génot, V., Nguyen, G., Ghisalberti, A., Smets, R., & Jeandet, A.
  Journal of Geophysical Research (Space Physics), 129(8).
  🔗 DOI: 10.1029/2023JA032098 | 🌌 ADS

• Spatial distribution of plasma density and magnetic field amplitude in the dayside magnetosheath as a function of the IMF orientation Michotte de Welle, B., Aunai, N., Lavraud, B., Génot, V., Jeandet, A., Nguyen, G., Ghisalberti, A., & Smets, R.
  Frontiers in Astronomy and Space Sciences, 11.
  🔗 DOI: 10.3389/fspas.2024.1427791 | 🌌 ADS

---

🔍 2022

Massive Multi-Mission Statistical Study and Analytical Modeling of the Earth's Magnetopause:

1. Part 1: A Gradient Boosting Based Automatic Detection of Near-Earth Regions Nguyen, G., Aunai, N., Michotte de Welle, B., et al. 🔗 DOI: 10.1029/2021JA029773
2. Part 2: Shape and Location Nguyen, G., Aunai, N., Michotte de Welle, B., et al. 🔗 DOI: 10.1029/2021JA029774
3. Part 3: An Asymmetric Non Indented Magnetopause Analytical Model Nguyen, G., Aunai, N., Michotte de Welle, B., et al. 🔗 DOI: 10.1029/2021JA030112
4. Part 4: On the Near-Cusp Magnetopause Indentation Nguyen, G., Aunai, N., Michotte de Welle, B., et al. 🔗 DOI: 10.1029/2021JA029776

Others

• Global Three-Dimensional Draping of Magnetic Field Lines in Earth's Magnetosheath Michotte de Welle, B., Aunai, N., Nguyen, G., Lavraud, B., Génot, V., et al.
  Journal of Geophysical Research (Space Physics), 127(12).
  🔗 DOI: 10.1029/2022JA030996 | 🌌 ADS