# PySpaceWeather
**Python interface for space weather indices**
[](https://github.com/st-bender/pyspaceweather/actions/workflows/ci_build_and_test.yml)
[](https://pyspaceweather.readthedocs.io/en/latest/?badge=latest)
[](https://pypi.org/project/spaceweather)
[](https://pypi.org/project/spaceweather)
[](https://pypi.org/project/spaceweather)
[](https://codecov.io/gh/st-bender/pyspaceweather)
[](https://coveralls.io/github/st-bender/pyspaceweather)
[](https://scrutinizer-ci.com/g/st-bender/pyspaceweather/?branch=master)
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](#data-sources) below.
:warning: 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:
```sh
$ pip install spaceweather
```
The latest development version can be installed
with [`pip`](https://pip.pypa.io) 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>):
```sh
$ pip install [-e] git+https://github.com/st-bender/pyspaceweather.git
```
The other option is to use a local clone:
```sh
$ 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>):
```sh
$ pip install [-e] .
```
or using `setup.py`:
```sh
$ python setup.py install
```
Optionally, test the correct function of the module with
```sh
$ py.test [-v]
```
or even including the [doctests](https://docs.python.org/library/doctest.html)
in this document:
```sh
$ py.test [-v] --doctest-glob='*.md'
```
## Usage
The python module itself is named `spaceweather` and is imported as usual
by calling
```python
>>> import spaceweather
```
### Celestrak
The module provides two functions to access the data from
[Celestrak](https://celestrak.com/SpaceData/),
`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.DataFrame`s.
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.
```python
>>> 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](https://www.gfz-potsdam.de/en/)
on their [data page](https://kp.gfz-potsdam.de/en/data).
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:
```python
>>> 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.
```python
>>> 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](https://omniweb.gsfc.nasa.gov/ow.html) 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.DataFrame`s are returned.
```python
>>> 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:
```python
>>> 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()`:
```python
>>> 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`:
```sh
$ 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](./COPYING.GPLv2)
or [online version](http://www.gnu.org/licenses/gpl-2.0.html).
## 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](https://celestrak.com),
for details see the included [COPYING.data](COPYING.data) file.
The data sources and file format are described at
<http://celestrak.com/SpaceData/SpaceWx-format.php>
(see [file_format.txt](file_format.txt) for a local copy of the format description).
### GFZ
The "GFZ" data are provided as tabulated ascii files
([format description](https://kp.gfz-potsdam.de/app/format/Kp_ap_Ap_SN_F107_format.txt),
[local copy](gfz_Kp_ap_Ap_SN_F107_format.txt))
and in [WDC format](https://kp.gfz-potsdam.de/app/format/wdc_fmt.txt)
([local copy](gfz_wdc_fmt.txt))
by the
[GFZ German Research Centre for Geosciences](https://www.gfz-potsdam.de/en/)
on their official [data webpage](https://kp.gfz-potsdam.de/en/data).
The data have the doi: [10.5880/Kp.0001](https://doi.org/10.5880/Kp.0001),
and they are provided under the "Creative Commons attribution license"
[CC-by 4.0](https://creativecommons.org/licenses/by/4.0/)
(local copy [COPYING.CCby4.0](COPYING.CCby4.0)).
See also [COPYING.gfz](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](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](omnie_format.txt)).
If you use the OMNI data in your work, please read [COPYING.omni](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>
Raw data
{
"_id": null,
"home_page": "https://github.com/st-bender/pyspaceweather",
"name": "spaceweather",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Stefan Bender",
"author_email": "stefan.bender@ntnu.no",
"download_url": "https://files.pythonhosted.org/packages/55/da/759c4e9504d763b162129163c8757f5a263510d79c2baff5c971b9f566fe/spaceweather-0.3.0.tar.gz",
"platform": null,
"description": "# PySpaceWeather\n\n**Python interface for space weather indices**\n\n[](https://github.com/st-bender/pyspaceweather/actions/workflows/ci_build_and_test.yml)\n[](https://pyspaceweather.readthedocs.io/en/latest/?badge=latest)\n[](https://pypi.org/project/spaceweather)\n[](https://pypi.org/project/spaceweather)\n[](https://pypi.org/project/spaceweather)\n[](https://codecov.io/gh/st-bender/pyspaceweather)\n[](https://coveralls.io/github/st-bender/pyspaceweather)\n[](https://scrutinizer-ci.com/g/st-bender/pyspaceweather/?branch=master)\n\nThis python module interfaces the space weather data available at\n<https://celestrak.com/SpaceData/>,\n<https://kp.gfz-potsdam.de/en/data>,\nand <https://omniweb.gsfc.nasa.gov/ow.html>.\nIt includes the geomagnetic Ap and Kp indices, both the 3h values and\nthe daily sum/averages.\nThe data also include the solar f10.7 cm radio fluxes,\nthe observed values as well as the 1 AU adjusted values,\ndaily values and the 81-day running means.\nSee [Data sources](#data-sources) below.\n\n:warning: This package is in **beta** stage, that is, it works for the most part\nand the interface should not change (much) in future versions.\n\nDocumentation is available at <https://pyspaceweather.readthedocs.io>.\n\n## Install\n\n### Requirements\n\n- `numpy` - required\n- `pandas` - required\n- `requests` - required for updating the data files\n- `pytest`, `pytest-mock` - optional, for testing\n\n### spaceweather\n\nA `pip` package called `spaceweather` is available from the\nmain package repository, and can be installed with:\n```sh\n$ pip install spaceweather\n```\nThe latest development version can be installed\nwith [`pip`](https://pip.pypa.io) directly from github\n(see <https://pip.pypa.io/en/stable/reference/pip_install/#vcs-support>\nand <https://pip.pypa.io/en/stable/reference/pip_install/#git>):\n\n```sh\n$ pip install [-e] git+https://github.com/st-bender/pyspaceweather.git\n```\n\nThe other option is to use a local clone:\n\n```sh\n$ git clone https://github.com/st-bender/pyspaceweather.git\n$ cd pyspaceweather\n```\nand then using `pip` (optionally using `-e`, see\n<https://pip.pypa.io/en/stable/reference/pip_install/#install-editable>):\n\n```sh\n$ pip install [-e] .\n```\n\nor using `setup.py`:\n\n```sh\n$ python setup.py install\n```\n\nOptionally, test the correct function of the module with\n\n```sh\n$ py.test [-v]\n```\n\nor even including the [doctests](https://docs.python.org/library/doctest.html)\nin this document:\n\n```sh\n$ py.test [-v] --doctest-glob='*.md'\n```\n\n## Usage\n\nThe python module itself is named `spaceweather` and is imported as usual\nby calling\n\n```python\n>>> import spaceweather\n\n```\n\n### Celestrak\n\nThe module provides two functions to access the data from\n[Celestrak](https://celestrak.com/SpaceData/),\n`sw_daily()` for the daily data\nas available from the website, and `ap_kp_3h()` for the 3h Ap and Kp values.\nBoth functions return `pandas.DataFrame`s.\nWhen the data available in the packaged version are too old for the use case,\nthey can be updated by passing `update=True` to both functions, or by calling\n`update_data()` explicitly.\n\n```python\n>>> import spaceweather as sw\n>>> df_d = sw.sw_daily()\n>>> df_d.loc[\"2000-01-01\"].Apavg\n30.0\n>>> df_3h = sw.ap_kp_3h()\n>>> df_3h.loc[\"2000-01-01 01:30:00\"]\nAp 56.0\nKp 5.3\nName: 2000-01-01 01:30:00, dtype: float64\n>>> # All 3h values for one day\n>>> df_3h.loc[\"2000-01-01\"]\n Ap Kp\n2000-01-01 01:30:00 56 5.3\n2000-01-01 04:30:00 39 4.7\n2000-01-01 07:30:00 27 4.0\n2000-01-01 10:30:00 18 3.3\n2000-01-01 13:30:00 32 4.3\n2000-01-01 16:30:00 15 3.0\n2000-01-01 19:30:00 32 4.3\n2000-01-01 22:30:00 22 3.7\n\n```\n\n### GFZ\n\nThe \"GFZ\" module supports the ascii and WDC files as offered by the\n[GFZ German Research Centre for Geosciences](https://www.gfz-potsdam.de/en/)\non their [data page](https://kp.gfz-potsdam.de/en/data).\nIn contrast to the official python client, this module reads the data\nfrom the (downloaded) files and does not access the web service API.\nThe interface is mostly the same as for the \"Celestrak\" data:\n\n```python\n>>> import spaceweather as sw\n>>> df_d = sw.gfz_daily()\n>>> df_d.loc[\"2000-01-01\"].Apavg\n30.0\n>>> df_3h = sw.gfz_3h()\n>>> df_3h.loc[\"2000-01-01 01:30:00\"]\nAp 56.000\nKp 5.333\nName: 2000-01-01 01:30:00, dtype: float64\n\n```\n\nCurrently, the data are not included in the package, downloads can be triggered\nby passing `update=True` to `sw.gfz_daily()` or by running `sw.update_gfz()`.\nThe lower-level interface functions are called `read_gfz(<filename>)`\nfor the ascii `.txt` files, and `read_gfz_wdc(<filename>)` for the WDC format.\nThey can also be used directly for reading already downloaded data files\noutside of the package's data directory.\n\n```python\n>>> import spaceweather as sw\n>>> df_d = sw.read_gfz(\"./tests/Kp_ap_Ap_SN_F107_since_2024.txt\")\n>>> df_d.loc[\"2024-01-01\"].Apavg\n10.0\n\n```\n\n### OMNI\n\nThe [OMNI](https://omniweb.gsfc.nasa.gov/ow.html) 1-hour yearly data\nare accessible via `omnie_hourly(<year>)` or `read_omnie(<file>)`.\nBoth functions should work with the OMNI2 standard and extended text files.\nIf the data are not already available locally, they can be cached by passing\n`cache=True` to that function or by calling `cache_omnie(<year>)` explicitly.\nAs for the Celestrak data, `pandas.DataFrame`s are returned.\n\n```python\n>>> import spaceweather as sw\n>>> df_h = sw.omnie_hourly(2000) # doctest: +SKIP\n>>> # or with automatic caching (downloading)\n>>> df_h = sw.omnie_hourly(2000, cache=True) # doctest: +SKIP\n\n```\n\nIf the data are already available locally, you can point the parser\nto that location:\n\n```python\n>>> import spaceweather as sw\n>>> df_h = sw.omnie_hourly(2000, local_path=\"/path/to/omni/data/\") # doctest: +SKIP\n\n```\n\nAnother option is to provide a filename directly to `read_omnie()`:\n\n```python\n>>> import spaceweather as sw\n>>> df = sw.read_omnie(\"/path/to/omni/data/file.dat\") # doctest: +SKIP\n\n```\n\n\n### Reference\n\nBasic class and method documentation is accessible via `pydoc`:\n\n```sh\n$ pydoc spaceweather\n$ pydoc spaceweather.celestrak\n$ pydoc spaceweather.gfz\n$ pydoc spaceweather.omni\n```\n\n## License\n\nThis python interface is free software: you can redistribute it or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation, version 2 (GPLv2), see [local copy](./COPYING.GPLv2)\nor [online version](http://www.gnu.org/licenses/gpl-2.0.html).\n\n## Data sources\n\n### Celestrak\n\nThe \"celestrak\" data can be found at <https://celestrak.com/SpaceData/>\nand is included with kind permission from Dr. T.S. Kelso at\n[celestrak](https://celestrak.com),\nfor details see the included [COPYING.data](COPYING.data) file.\n\nThe data sources and file format are described at\n<http://celestrak.com/SpaceData/SpaceWx-format.php>\n(see [file_format.txt](file_format.txt) for a local copy of the format description).\n\n### GFZ\n\nThe \"GFZ\" data are provided as tabulated ascii files\n([format description](https://kp.gfz-potsdam.de/app/format/Kp_ap_Ap_SN_F107_format.txt),\n[local copy](gfz_Kp_ap_Ap_SN_F107_format.txt))\nand in [WDC format](https://kp.gfz-potsdam.de/app/format/wdc_fmt.txt)\n([local copy](gfz_wdc_fmt.txt))\nby the\n[GFZ German Research Centre for Geosciences](https://www.gfz-potsdam.de/en/)\non their official [data webpage](https://kp.gfz-potsdam.de/en/data).\nThe data have the doi: [10.5880/Kp.0001](https://doi.org/10.5880/Kp.0001),\nand they are provided under the \"Creative Commons attribution license\"\n[CC-by 4.0](https://creativecommons.org/licenses/by/4.0/)\n(local copy [COPYING.CCby4.0](COPYING.CCby4.0)).\nSee also [COPYING.gfz](COPYING.gfz) for details.\n\n### OMNI\n\nThis package includes part of the hourly-resolved OMNI data,\naccessible through <https://spdf.gsfc.nasa.gov/pub/data/omni/low_res_omni/>,\nand it enables easy downloading of it.\nThe file format is described at\n<https://spdf.gsfc.nasa.gov/pub/data/omni/low_res_omni/omni2.text>\n(local copy [omni_format.txt](omni_format.txt))\nand the \"extended\" format at\n<https://spdf.gsfc.nasa.gov/pub/data/omni/low_res_omni/extended/aareadme_extended>\n(local copy [omnie_format.txt](omnie_format.txt)).\n\nIf you use the OMNI data in your work, please read [COPYING.omni](COPYING.omni)\ncarefully and cite the following publication:\n\nKing, Joseph H. and Natalia E. Papitashvili,\nSolar wind spatial scales in and comparisons of hourly Wind and ACE plasma and magnetic field data,\nJ. Geophys. Res., 110, A02104, 2005.\n\nPlease acknowledge the OMNI sources, using the following DOIs for the OMNI datasets:\n\nPapitashvili, Natalia E. and King, Joseph H. (2022), \"OMNI 1-min Data\" [Data set],\nNASA Space Physics Data Facility, <https://doi.org/10.48322/45bb-8792>\n\nPapitashvili, Natalia E. and King, Joseph H. (2022), \"OMNI 5-min Data\" [Data set],\nNASA Space Physics Data Facility, <https://doi.org/10.48322/gbpg-5r77>\n\nPapitashvili, Natalia E. and King, Joseph H. (2022), \"OMNI Hourly Data\" [Data Set],\nNASA Space Physics Data Facility, <https://doi.org/10.48322/1shr-ht18>\n\nPapitashvili, Natalia E. and King, Joseph H. (2022), \"OMNI Daily Data\" [Data set],\nNASA Space Physics Data Facility, <https://doi.org/10.48322/5fmx-hv56>\n\nPapitashvili, Natalia E. and King, Joseph H. (2022), \"OMNI 27-Day Data\" [Data set],\nNASA Space Physics Data Facility, <https://doi.org/10.48322/nmh3-jf75>\n\nThe OMNI data are also available from CDAWeb, and thus available via various other methods\n<https://cdaweb.gsfc.nasa.gov/alternative_access_methods.html>\nIn particular, you might find our Python web service library useful\n<https://pypi.org/project/cdasws>\nOr through the HAPI streaming protocol <https://github.com/hapi-server/client-python>\n",
"bugtrack_url": null,
"license": "GPLv2",
"summary": "Python interface for space weather indices",
"version": "0.3.0",
"project_urls": {
"Homepage": "https://github.com/st-bender/pyspaceweather"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1b14b2ff446c2a807c3a2f3860548b9c0316eeed5648b5e71fb287729e308fef",
"md5": "6c56f2c54b5df3ffa6351a273329dbaa",
"sha256": "fca04eaabe953da5503a8d52f129fd29f3aa5399b16cd83ee9239430d5605151"
},
"downloads": -1,
"filename": "spaceweather-0.3.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "6c56f2c54b5df3ffa6351a273329dbaa",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 913136,
"upload_time": "2024-04-04T17:19:36",
"upload_time_iso_8601": "2024-04-04T17:19:36.913967Z",
"url": "https://files.pythonhosted.org/packages/1b/14/b2ff446c2a807c3a2f3860548b9c0316eeed5648b5e71fb287729e308fef/spaceweather-0.3.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "55da759c4e9504d763b162129163c8757f5a263510d79c2baff5c971b9f566fe",
"md5": "b53a45a3a0d5168fd48dd6ed8929d325",
"sha256": "b17705be965b022f03132356113e797224e69de4db816333c92cef09ec09b269"
},
"downloads": -1,
"filename": "spaceweather-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "b53a45a3a0d5168fd48dd6ed8929d325",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 929750,
"upload_time": "2024-04-04T17:19:38",
"upload_time_iso_8601": "2024-04-04T17:19:38.539486Z",
"url": "https://files.pythonhosted.org/packages/55/da/759c4e9504d763b162129163c8757f5a263510d79c2baff5c971b9f566fe/spaceweather-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-04 17:19:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "st-bender",
"github_project": "pyspaceweather",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"lcname": "spaceweather"
}
JSON
