Welcome to swvo documentation!#

SWVO @ GFZ#

PyPI version Build Sphinx HTML SWVO Tests Python version Coverage Status REUSE status

Introduction#

This package provides a set of tools for managing solar data in Python. It includes functionalities for reading, writing, and processing data from various sources.

Example#

from datetime import datetime, timezone
from swvo.io.solar_wind import SWACE

ACE_DIR = "./ace_data/"  # data directory for ACE data

start = datetime(2024, 11, 20, 0, 0, tzinfo=timezone.utc)
end = datetime(2024, 11, 20, 6, 0, tzinfo=timezone.utc)

# Read ACE solar wind data with downloading
swace = SWACE(ACE_DIR)
ace_df = swace.read(start, end, download=True)

See here for a detailed example docs/examples/solar_wind_example.ipynb

Space Weather Data Overview#

This package provides tools to read, process, and analyze several key solar and geomagnetic indices. For each index, the available data sources and the corresponding reader classes are listed below:

  • Kp Index: A global geomagnetic activity index with a 3-hour cadence, ranging from 0 (quiet) to 9 (extremely disturbed). Used to assess geomagnetic storm conditions.

    • Sources & Classes:

      • OMNI: KpOMNI

      • SWPC: KpSWPC

      • Niemegk: KpNiemegk

      • Ensemble: KpEnsemble

      • BSG: KpBGS

      • SIDC: KpSIDC

      • Combined: read_kp_from_multiple_models

  • Dst Index: The Disturbance Storm Time (Dst) index measures the intensity of the Earth’s ring current, related to geomagnetic storms. Provided hourly and is negative during storm conditions.

    • Sources & Classes:

      • OMNI: DSTOMNI

      • WDC: DSTWDC

      • Combined: read_dst_from_multiple_models

  • Hp Index: The Hp30 and Hp60 indices are high-cadence (30-minute and 60-minute) geomagnetic indices provided by GFZ, used for detailed geomagnetic activity studies.

    • Sources & Classes:

      • GFZ: HpGFZ

      • Ensemble: HpEnsemble

      • Combined: read_hp_from_multiple_models

  • F10.7 Index: The F10.7 solar radio flux index is a daily measure of solar activity (flux density at 10.7 cm), a standard proxy for solar EUV emissions.

    • Sources & Classes:

      • OMNI: F107OMNI

      • SWPC: F107SWPC

      • Combined: read_f107_from_multiple_models

  • SuperMAG electrojet indices: SME, SML, and SMU describe the auroral electrojet using the SuperMAG ground-magnetometer network at one-minute cadence. Access requires a valid SuperMAG account.

    • Sources & Classes:

      • SuperMAG: SMESuperMAG

  • Substorm-onset events: Sparse onset catalogues identified from SuperMAG SML or auroral images. The available techniques are Newell, Forsyth/SOPHIE, Ohtani, Frey, and Liou.

    • Sources & Classes:

      • SuperMAG: SubstormsSuperMAG

  • Solar Wind Parameters: Access to solar wind data (speed, density, magnetic field components) from various spacecraft. Essential for solar-terrestrial interaction studies.

    • Sources & Classes:

      • ACE: SWACE

      • DSCOVR: DSCOVR

      • IMAP: SWIMAP

      • OMNI: SWOMNI

      • SWIFT: SWSWIFTEnsemble

      • ENLIL: SWENLIL_BKG (ambient background runs), SWENLIL_CME (CME simulation runs)

      • MIDL: SWMIDL (merged L1 record from ACE, DSCOVR, WIND and SOHO)

      • Combined: read_solar_wind_from_multiple_models

  • Plasmasphere Density Predictions: Reader utilities for PAGER plasmasphere density grids and model combined inputs.

    • Sources & Classes:

      • Density predictions: PlasmaspherePredictionReader

      • Combined inputs: PlasmasphereCombinedInputsReader

      • Density cube container: PlasmasphereDensityCube

Each index can be accessed via these dedicated reader classes, which handle downloading and read methods. See the code in swvo/io or API documentation for details on each index’s implementation.

Installation#

To install the package, run the following command:

uv venv

uv venv venv --python 3.11 --seed
source venv/bin/activate
uv pip install -e .

or it can be installed directly from PyPI:

uv pip install swvo

All the above uv commands assume you have uv installed, if not then remove uv prefix from the commands and run them directly.

Test Data#

The data used by the test suite is hosted on Zenodo and is not tracked in this repository. Install the dev dependency group (uv sync --group dev), which pulls in zenodo_get, then run ./download_data_for_tests.sh to fetch and unpack it.

API#

swvo

User Guide#