st-bender / pyspaceweather

Space weather indices for python

PySpaceWeather

Python interface for space weather indices

This python module interfaces the space weather data available at https://celestrak.com/SpaceData/, https://kp.gfz-potsdam.de/en/data, and https://omniweb.gsfc.nasa.gov/ow.html. It includes the geomagnetic Ap and Kp indices, both the 3h values and the daily sum/averages. The data also include the solar f10.7 cm radio fluxes, the observed values as well as the 1 AU adjusted values, daily values and the 81-day running means. See Data sources below.

⚠️ This package is in beta stage, that is, it works for the most part and the interface should not change (much) in future versions.

Documentation is available at https://pyspaceweather.readthedocs.io.

Install

Requirements

• numpy - required
• pandas - required
• requests - required for updating the data files
• pytest, pytest-mock - optional, for testing

spaceweather

A pip package called spaceweather is available from the main package repository, and can be installed with:

$ pip install spaceweather

The latest development version can be installed with pip directly from github (see https://pip.pypa.io/en/stable/reference/pip_install/#vcs-support and https://pip.pypa.io/en/stable/reference/pip_install/#git):

$ pip install [-e] git+https://github.com/st-bender/pyspaceweather.git

The other option is to use a local clone:

$ git clone https://github.com/st-bender/pyspaceweather.git
$ cd pyspaceweather

and then using pip (optionally using -e, see https://pip.pypa.io/en/stable/reference/pip_install/#install-editable):

$ pip install [-e] .

or using setup.py:

$ python setup.py install

Optionally, test the correct function of the module with

$ py.test [-v]

or even including the doctests in this document:

$ py.test [-v] --doctest-glob='*.md'

Usage

The python module itself is named spaceweather and is imported as usual by calling

>>> import spaceweather

Celestrak

The module provides two functions to access the data from Celestrak, sw_daily() for the daily data as available from the website, and ap_kp_3h() for the 3h Ap and Kp values. Both functions return pandas.DataFrames. When the data available in the packaged version are too old for the use case, they can be updated by passing update=True to both functions, or by calling update_data() explicitly.

>>> import spaceweather as sw
>>> df_d = sw.sw_daily()
>>> df_d.loc["2000-01-01"].Apavg
30.0
>>> df_3h = sw.ap_kp_3h()
>>> df_3h.loc["2000-01-01 01:30:00"]
Ap    56.0
Kp     5.3
Name: 2000-01-01 01:30:00, dtype: float64
>>> # All 3h values for one day
>>> df_3h.loc["2000-01-01"]
                     Ap   Kp
2000-01-01 01:30:00  56  5.3
2000-01-01 04:30:00  39  4.7
2000-01-01 07:30:00  27  4.0
2000-01-01 10:30:00  18  3.3
2000-01-01 13:30:00  32  4.3
2000-01-01 16:30:00  15  3.0
2000-01-01 19:30:00  32  4.3
2000-01-01 22:30:00  22  3.7

GFZ

The "GFZ" module supports the ascii and WDC files as offered by the GFZ German Research Centre for Geosciences on their data page. In contrast to the official python client, this module reads the data from the (downloaded) files and does not access the web service API. The interface is mostly the same as for the "Celestrak" data:

>>> import spaceweather as sw
>>> df_d = sw.gfz_daily()
>>> df_d.loc["2000-01-01"].Apavg
30.0
>>> df_3h = sw.gfz_3h()
>>> df_3h.loc["2000-01-01 01:30:00"]
Ap    56.000
Kp     5.333
Name: 2000-01-01 01:30:00, dtype: float64

Currently, the data are not included in the package, downloads can be triggered by passing update=True to sw.gfz_daily() or by running sw.update_gfz(). The lower-level interface functions are called read_gfz(<filename>) for the ascii .txt files, and read_gfz_wdc(<filename>) for the WDC format. They can also be used directly for reading already downloaded data files outside of the package's data directory.

>>> import spaceweather as sw
>>> df_d = sw.read_gfz("./tests/Kp_ap_Ap_SN_F107_since_2024.txt")
>>> df_d.loc["2024-01-01"].Apavg
10.0

OMNI

The OMNI 1-hour yearly data are accessible via omnie_hourly(<year>) or read_omnie(<file>). Both functions should work with the OMNI2 standard and extended text files. If the data are not already available locally, they can be cached by passing cache=True to that function or by calling cache_omnie(<year>) explicitly. As for the Celestrak data, pandas.DataFrames are returned.

>>> import spaceweather as sw
>>> df_h = sw.omnie_hourly(2000)  # doctest: +SKIP
>>> # or with automatic caching (downloading)
>>> df_h = sw.omnie_hourly(2000, cache=True)  # doctest: +SKIP

If the data are already available locally, you can point the parser to that location:

>>> import spaceweather as sw
>>> df_h = sw.omnie_hourly(2000, local_path="/path/to/omni/data/")  # doctest: +SKIP

Another option is to provide a filename directly to read_omnie():

>>> import spaceweather as sw
>>> df = sw.read_omnie("/path/to/omni/data/file.dat")  # doctest: +SKIP

Reference

Basic class and method documentation is accessible via pydoc:

$ pydoc spaceweather
$ pydoc spaceweather.celestrak
$ pydoc spaceweather.gfz
$ pydoc spaceweather.omni

License

This python interface is free software: you can redistribute it or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2 (GPLv2), see local copy or online version.

Data sources

Celestrak

The "celestrak" data can be found at https://celestrak.com/SpaceData/ and is included with kind permission from Dr. T.S. Kelso at celestrak, for details see the included COPYING.data file.

The data sources and file format are described at http://celestrak.com/SpaceData/SpaceWx-format.php (see file_format.txt for a local copy of the format description).

GFZ

The "GFZ" data are provided as tabulated ascii files (format description, local copy) and in WDC format (local copy) by the GFZ German Research Centre for Geosciences on their official data webpage. The data have the doi: 10.5880/Kp.0001, and they are provided under the "Creative Commons attribution license" CC-by 4.0 (local copy COPYING.CCby4.0). See also COPYING.gfz for details.

OMNI

This package includes part of the hourly-resolved OMNI data, accessible through https://spdf.gsfc.nasa.gov/pub/data/omni/low_res_omni/, and it enables easy downloading of it. The file format is described at https://spdf.gsfc.nasa.gov/pub/data/omni/low_res_omni/omni2.text (local copy omni_format.txt) and the "extended" format at https://spdf.gsfc.nasa.gov/pub/data/omni/low_res_omni/extended/aareadme_extended (local copy omnie_format.txt).

If you use the OMNI data in your work, please read COPYING.omni carefully and cite the following publication:

King, Joseph H. and Natalia E. Papitashvili, Solar wind spatial scales in and comparisons of hourly Wind and ACE plasma and magnetic field data, J. Geophys. Res., 110, A02104, 2005.

Please acknowledge the OMNI sources, using the following DOIs for the OMNI datasets:

Papitashvili, Natalia E. and King, Joseph H. (2022), "OMNI 1-min Data" [Data set], NASA Space Physics Data Facility, https://doi.org/10.48322/45bb-8792

Papitashvili, Natalia E. and King, Joseph H. (2022), "OMNI 5-min Data" [Data set], NASA Space Physics Data Facility, https://doi.org/10.48322/gbpg-5r77

Papitashvili, Natalia E. and King, Joseph H. (2022), "OMNI Hourly Data" [Data Set], NASA Space Physics Data Facility, https://doi.org/10.48322/1shr-ht18

Papitashvili, Natalia E. and King, Joseph H. (2022), "OMNI Daily Data" [Data set], NASA Space Physics Data Facility, https://doi.org/10.48322/5fmx-hv56

Papitashvili, Natalia E. and King, Joseph H. (2022), "OMNI 27-Day Data" [Data set], NASA Space Physics Data Facility, https://doi.org/10.48322/nmh3-jf75

The OMNI data are also available from CDAWeb, and thus available via various other methods https://cdaweb.gsfc.nasa.gov/alternative_access_methods.html In particular, you might find our Python web service library useful https://pypi.org/project/cdasws Or through the HAPI streaming protocol https://github.com/hapi-server/client-python