Metadata-Version: 2.5
Name: el_paso
Version: 2.1.3rc2
Summary: EL-PASO is a Python framework designed to streamline the download, processing, and saving of satellite particle observation data.
Project-URL: Homepage, https://github.com/GFZ/EL_PASO
Project-URL: Tracker, https://github.com/GFZ/EL_PASO/issues
Project-URL: Documentation, https://el-paso.readthedocs.io/en/latest/
Author-email: Bernhard Haas <bhaas@gfz.de>
License-Expression: (Apache-2.0 OR LGPL-3.0-only)
License-File: LICENSES/Apache-2.0.txt
License-File: LICENSES/LGPL-3.0-only.txt
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.12
Requires-Dist: astropy>=7.2.0
Requires-Dist: cdflib==1.3.8
Requires-Dist: dotenv>=0.9.9
Requires-Dist: gitpython==3.1.46
Requires-Dist: joblib>=1.4.0
Requires-Dist: lazy-loader>=0.6
Requires-Dist: matplotlib>=3.10.8
Requires-Dist: netcdf4>=1.7.2
Requires-Dist: numpy>=2.4.2
Requires-Dist: pandas>=3.0.0
Requires-Dist: pyspedas>=2.1.5
Requires-Dist: python-dateutil>=2.9.0.post0
Requires-Dist: requests>=2.32.5
Requires-Dist: rich>=13.0.0
Requires-Dist: richpool>=0.1.2
Requires-Dist: scipy>=1.17
Requires-Dist: skyfield==1.54
Requires-Dist: sscws==2.4.6
Requires-Dist: swvo>=1.2.7rc0
Requires-Dist: tabulate==0.9.0
Requires-Dist: tqdm>=4.67.2
Requires-Dist: typer>=0.15
Requires-Dist: wget>=3.2
Requires-Dist: wheel==0.46.3
Requires-Dist: xarray>=2026.4.0
Description-Content-Type: text/markdown

<!--
SPDX-FileCopyrightText: 2025 GFZ Helmholtz Centre for Geosciences
SPDX-FileContributor: Bernhard Haas

SPDX-License-Identifier: Apache-2.0
-->

|            |                                                                                                                                                                                                                                                                                                                                                            |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Versions   | [![PyPi](https://badge.fury.io/py/el-paso.svg)](https://badge.fury.io/py/el-paso) [![Python version](https://img.shields.io/pypi/pyversions/el-paso.svg)](https://badge.fury.io/py/el-paso) [![Zenodo](https://img.shields.io/badge/Zenodo-10.5281/zenodo.20760790-blue)](https://doi.org/10.5281/zenodo.20760790)                                     |
| Status     | [![Tests](https://github.com/GFZ/EL_PASO/actions/workflows/test.yml/badge.svg)](https://github.com/GFZ/EL_PASO/actions/workflows/test.yml) [![Coverage Status](https://coveralls.io/repos/github/GFZ/EL_PASO/badge.svg?branch=main)](https://coveralls.io/github/GFZ/EL_PASO?branch=main) [![Docs](https://app.readthedocs.org/projects/el-paso/badge/?version=latest)](https://el-paso.readthedocs.io/en/latest/) [![REUSE status](https://api.reuse.software/badge/github.com/GFZ/EL_PASO)](https://api.reuse.software/info/github.com/GFZ/EL_PASO) |
| Tools      | [![Pre-Commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) [![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty) |
| License    | [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![License: LGPL v3](https://img.shields.io/badge/License-LGPL_v3-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0)                                                                                                                    |
| Paper      | [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/GFZ/EL_PASO/executable_paper?urlpath=%2Fdoc%2Ftree%2Fpaper%2Fel_paso_executable_paper.ipynb) [![Paper](https://img.shields.io/badge/Open_Access-10.22541/essoar.15002644/v1-blue)](https://essopenarchive.org/doi/abs/10.22541/essoar.15002644/v1)                          |
| SPEC       | [![SPEC 0 — Minimum Supported Dependencies](https://img.shields.io/badge/SPEC-0-green?labelColor=%23004811&color=%235CA038)](https://scientific-python.org/specs/spec-0000/) [![SPEC 1 — Lazy Loading of Submodules and Functions](https://img.shields.io/badge/SPEC-1-green?labelColor=%23004811&color=%235CA038)](https://scientific-python.org/specs/spec-0001/) |

# ELaborative Particle Analysis from Satellite Observations (EL-PASO)

`EL-PASO` is a Python framework designed to streamline the download, processing, and saving of satellite particle observation data.

Its primary purpose is to prepare and standardize particle data for use in radiation belt modeling.

<img width="1200" height="682" alt="el_paso_recipe" src="https://github.com/user-attachments/assets/1903bc32-eea6-41a0-8bf2-e48c4d9dcba9" />

## Features

- **Format Flexibility:** Capable of handling different input formats including `cdf`, `netcdf`, `h5`, `ascii`, and `json`
- **Integrated Processing:** Provides a comprehensive set of functions for common particle data analysis tasks
- **Supports Metadata:** Stores all processing and metadata alongside the data, ensuring full traceability and reproducibility.
- **Standardized output files:** Saving processed data in different standards (e.g. PRBEM) to enable easy loading and sharing of processed data

Full documentation can be viewed [here](https://el-paso.readthedocs.io/en/latest/).

## Available processing scripts

- **Arase**
    - MEPe
    - XEP (archived and real-time)
    - PWE density
- **DMSP**
    - SSJ (electrons)
- **GOES-R**
    - MPS-High real-time
    - MPS-High
- **GPS**
    - GPS processing
- **ESA**
    - NGRM satellites
- **POES**
    - MEPED (electrons)
    - TED (electrons)
- **PROBA-V**
    - EPT (electrons and protons)
- **THEMIS**
    - FFT waves
    - Spacecraft-potential density
- **Van Allen Probes**
    - HOPE (electrons and protons)
    - MagEIS (electrons and protons)
    - RBSPICE (protons)
    - ECT-combined
    - EMFISIS waves
    - EMFISIS and EFW density
- **DMSP**
    - SSJ (electrons)

Every recipe shares one command line interface; see
[Running a recipe](#running-a-recipe) below.

## Installation

### Step 1: Clone the Repository

Begin by cloning the EL-PASO repository and navigating into its directory.

```bash
git clone https://github.com/GFZ/EL_PASO.git
cd EL_PASO
```

### Step 2: Set up a Python Virtual Environment

It is highly recommended to use a virtual environment to manage dependencies.

```bash
uv venv --python 3.12 --seed
source .venv/bin/activate
uv pip install .
```

The custom `setup.py` script will automatically download and compile the IRBEM Fortran library during this step.

### Verifying the Installation

You can validate your installation by running the minimal example located in *examples*:

```bash
python examples/minimal_example.py
```
> [!TIP]
> #### Using the Apptainer Image
>
> Instead of setting up a Python environment yourself, you can pull a prebuilt [Apptainer](https://apptainer.org/) [el_paso](https://github.com/GFZ/EL_PASO/pkgs/container/el_paso) image:
> ```bash
> apptainer pull -F elpaso.sif oras://ghcr.io/gfz/el_paso:latest
> ```
> Run a command inside the image with `apptainer exec` or `apptainer run`, e.g.:
> ```bash
> apptainer exec elpaso.sif python examples/minimal_example.py
> ```
> Available tags mirror the CI build: `latest` (most recent build on `main`), a specific commit SHA, or a released package version (e.g. `oras://ghcr.io/gfz/el_paso:2.1.2`).

## Running a recipe

Installing EL-PASO provides the `el-paso` command, which exposes every recipe
under a common set of options:

```bash
el-paso list                 # show every available recipe
el-paso poes meped --help    # options for one recipe

el-paso poes meped \
    --start-time 2013-03-16 --end-time 2013-03-16T23:59:59 \
    --satellite noaa15 --mag-field T89 --bin-cadence 10s \
    --raw-data-path ./raw --processed-data-path ./processed
```

Recipes can equally be run as modules, which is convenient inside job scripts:

```bash
python -m el_paso.recipes.poes.process_poes_meped \
    --start-time 2013-03-16 --end-time 2013-03-16T23:59:59
```

Both forms accept the same options, because both are generated from the recipe
function's own signature. `--start-time` and `--end-time` are required; the rest
have per-recipe defaults. Common options are
`--satellite` (repeat it to process several), `--mag-field`, `--bin-cadence`
(`10s`, `5min`, `1h`), `--raw-data-path`, `--processed-data-path` and
`--num-cores`. Add `--dry-run` to print the resolved arguments without
processing anything, and `--install-completion` to set up shell completion.
Which options a given recipe accepts depends on what it actually supports, so
check `--help`.

See the [command line documentation](docs/getting_started/command_line.md) for
the full list.

## Testing

### Step 1: Download the Test Data

Most tests rely on reference/system test data hosted on [Zenodo](https://zenodo.org). Download it by running the following script from the repository root:

```bash
bash download_data_for_tests.sh
```

This fetches the dataset archive and extracts it into `tests/system/`. You only need to do this once (rerun it if the data changes upstream).

`pytest` is installed as part of the regular dependencies (see [Installation](#installation)), so no separate test install step is needed.

### Step 2: Run the Tests

Run the full test suite with `pytest`:

```bash
pytest tests
```

Tests are grouped using pytest markers, defined in `pytest.ini`:

- `basic`: quick tests suitable for fast, everyday verification of the code. This is what CI runs on every push/PR:

  ```bash
  pytest tests -m basic
  ```

- `visual`: tests that produce plots or other visual output which must be checked manually rather than being asserted automatically:

  ```bash
  pytest tests -m visual
  ```

You can combine or exclude markers using standard pytest marker expressions, e.g. to run everything except visual tests:

```bash
pytest tests -m "not visual"
```

Some system tests compare against previously stored reference solutions. Pass `--renew_solution` to regenerate and overwrite those reference solutions instead of comparing against them:

```bash
pytest tests --renew_solution=true
```

Use this only when you intend to intentionally update the stored reference outputs.

## Contributing

Please read our comprehensive [contribution guide](CONTRIBUTING.md) before submitting a pull request.

## Citation

If you use `EL-PASO` in your research, please cite the associated preprint:

> Haas, B., Drozdov, A. Y., and Jhawar, S. 	EL-PASO: An Open-Source Python Library for Processing and Standardizing Particle Measurements Taken in Space. ESS Open Archive. https://essopenarchive.org/doi/full/10.22541/essoar.15002644/v1

```bibtex
@article{
doi:10.22541/essoar.15002644/v1,
author = {Bernhard Haas  and Alexander Y. Drozdov  and Sahil Jhawar },
title = {EL-PASO: An Open-Source Python Library for Processing and Standardizing Particle Measurements Taken in Space},
journal = {ESS Open Archive},
volume = {2026},
number = {0502},
pages = {},
year = {2026},
doi = {10.22541/essoar.15002644/v1},
URL = {https://essopenarchive.org/doi/abs/10.22541/essoar.15002644/v1},
eprint = {https://essopenarchive.org/doi/pdf/10.22541/essoar.15002644/v1}}
```

To cite this repository you can use [CITATION.cff](CITATION.cff).

## Acknowledgements

This work has been funded by the German Research Foundation (NFDI4Earth, DFG project no. 460036893, https://www.nfdi4earth.de/).
The authors acknowledge the work of Mátyás Szabó-Roberts who led the foundation for the EL-PASO framework.

The thank the authors of the [IRBEM library](https://github.com/PRBEM/IRBEM) for providing their code.
