MANGO: Magnetospheric Atlas from Normalized Geospace Observations

Documentation: https://space-mango.readthedocs.io

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 mango

# What is there? (nothing below downloads data)
mango.regions()                     # ['magnetosphere', 'magnetosheath', 'solar_wind']
mango.magnetosheath                 # <MANGO region 'magnetosheath': Between the bow shock and ...>
mango.describe("magnetosheath")     # column | unit | frame | description | filter | dtype
mango.spacecraft("magnetosheath")   # sc | start | stop | n_rows
mango.search("density")             # columns and filters matching a word
mango.count("magnetosheath", bz_imf_max=-2)   # {'n_rows', 'est_mb', 'download_mb_estimate'}

# Statistical study: southward IMF, inner magnetosheath
r = mango.magnetosheath.get_data(           # tab-complete the filters; help() lists their units
    spacecraft=["THA", "MMS"],              # spacecraft names: see mango.spacecraft(...)
    start="2016-01", stop="2021-01",        # start inclusive, stop exclusive
    columns=["Time", "Np", "Bx_swi", "R_norm"],
    bz_imf_max=-2, d_msh_max=0.3,
)
df = r.to_pandas()                          # or r.to_polars(), r.to_xarray()
r.metadata["Np"]                            # {'unit': 'cm⁻³', 'frame': '', 'description': ...}
print(r.cite())                             # BibTeX, with the dataset version

# Event context: where was THA, and when did it cross a boundary?
t = mango.timeline("THA", "2017-01-12T10:00", "2017-01-12T12:00")
t.to_intervals()                            # sc | region | start | stop | n_points

Results are cached on disk (~/.cache/space-mango, size cap SPACE_MANGO_CACHE_SIZE bytes, default 10 GB); re-running a notebook does not download again. mango.cache.info() / mango.cache.clear() manage it.

Changes in 0.2: get_data returns a MangoResult (use .to_polars() for the previous polars DataFrame); time_min/time_max are deprecated in favour of start/stop; unknown spacecraft, columns or filters now raise an error instead of returning empty or unfiltered data. The spacecraft name for MMS is MMS (not MMS1).

• Re-check analyses that used d_msh, d_msp or tilt: before this release the server silently ignored these three filters and returned unfiltered data.
• Release order: the 0.2 client needs a 0.2 server — deploy the server first. Against an older server the client raises ServerError ("older than 0.2"); keep space-mango<0.2 until the server is upgraded.

Full reference (columns, frames, filters, cache, errors): docs/user_guide.md.

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

Clients cache downloaded data per dataset version and schema. Changing the served data requires bumping MANGO_DATASET_VERSION; otherwise clients keep serving the old data from their cache.

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