Metadata-Version: 2.4
Name: space-mango
Version: 0.1.1
Summary: Python client and server for the MANGO magnetospheric dataset
Project-URL: Repository, https://github.com/LaboratoryOfPlasmaPhysics/mango
Author-email: Alexis Jeandet <alexis.jeandet@member.fsf.org>
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Typing :: Typed
Requires-Python: <4.0,>=3.11
Requires-Dist: httpx>=0.28
Requires-Dist: polars>=1.0
Requires-Dist: pyarrow>=18.0
Provides-Extra: server
Requires-Dist: cyclopts>=4.10.1; extra == 'server'
Requires-Dist: fastapi>=0.115; extra == 'server'
Requires-Dist: gunicorn>=23.0; extra == 'server'
Requires-Dist: uvicorn-worker>=0.3; extra == 'server'
Requires-Dist: uvicorn[standard]>=0.34; extra == 'server'
Description-Content-Type: text/markdown


# MANGO: Magnetospheric Atlas from Normalized Geospace Observations

<img width="300" height="300" alt="mangologo" src="https://github.com/user-attachments/assets/5a92150f-ce77-45a8-b15e-8f66ff7cf44b" />


## 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](https://pola.rs) 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

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

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

## Quick Start

```python
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

```bash
# 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`:

```bash
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](https://doi.org/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](https://doi.org/10.1029/2025JA034558) | [🌌 ADS](https://ui.adsabs.harvard.edu/abs/2025JGRA..13034558M)

* **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](https://doi.org/10.1029/2024GL113488) | [🌌 ADS](https://ui.adsabs.harvard.edu/abs/2025GeoRL..5213488M)

---

### 🛰️ 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](https://doi.org/10.1007/s11214-024-01095-w) | [🌌 ADS](https://ui.adsabs.harvard.edu/abs/2024SSRv..220...68H)

* **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](https://doi.org/10.1029/2023JA032137) | [🌌 ADS](https://ui.adsabs.harvard.edu/abs/2024JGRA..12932137H)

* **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](https://doi.org/10.1029/2023JA032098) | [🌌 ADS](https://ui.adsabs.harvard.edu/abs/2024JGRA..12932098M)

* **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](https://doi.org/10.3389/fspas.2024.1427791) | [🌌 ADS](https://ui.adsabs.harvard.edu/abs/2024FrASS..1127791M)

---

### 🔍 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](https://doi.org/10.1029/2021JA029773)
2.  **Part 2: Shape and Location** Nguyen, G., Aunai, N., **Michotte de Welle, B.**, et al. [🔗 DOI: 10.1029/2021JA029774](https://doi.org/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](https://doi.org/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](https://doi.org/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](https://doi.org/10.1029/2022JA030996) | [🌌 ADS](https://ui.adsabs.harvard.edu/abs/2022JGRA..12730996M)


