SWVO @ GFZ

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
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
    • OMNI: SWOMNI
    • SWIFT: SWSWIFTEnsemble
    • 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.

SuperMAG substorm-onset catalogues

SubstormsSuperMAG retrieves one of the five scientifically distinct onset catalogues distributed by SuperMAG. Newell is the default, and sophie is accepted as an alias for the official forsyth identifier:

from swvo.io.substorms import SubstormsSuperMAG

reader = SubstormsSuperMAG(username, data_dir=cache_directory)
newell = reader.read(start, end, download=True)
sophie = reader.read(start, end, download=True, catalog="sophie")

Results contain onset location, canonical catalogue name, UTC indexing, and local-file provenance. Annual self-documented caches retain SuperMAG revision and acknowledgement information. See the SuperMAG substorm catalogue guide for catalogue differences, coverage, location interpretation, caching, revisions, reliability, and publication requirements.

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.