<h1 align="center">
<img src="https://raw.githubusercontent.com/SciQLop/speasy/main/logo/logo_speasy.svg" width="300">
</h1><br>
# Space Physics made EASY
[](https://matrix.to/#/#speasy:matrix.org)
[](https://pypi.python.org/pypi/speasy)
[](https://github.com/SciQLop/speasy/actions?query=workflow%3A%22Tests%22)
[](https://speasy.readthedocs.io/en/latest/?badge=latest)
[](https://codecov.io/gh/SciQLop/speasy/branch/main)
[](https://github.com/SciQLop/speasy/actions/workflows/codeql.yml)
[](https://doi.org/10.5281/zenodo.4118780)
[](https://mybinder.org/v2/gh/SciQLop/speasy/main?labpath=docs/examples)
[](https://colab.research.google.com/github/SciQLop/speasy)
[](http://sciqlop.lpp.polytechnique.fr/cache)
Speasy is a free and open-source Python package that makes it easy to find and load space physics data from a variety of
data sources, whether it is online and public such as [CDAWEB](https://cdaweb.gsfc.nasa.gov/index.html/)
and [AMDA](http://amda.irap.omp.eu/),
or any described archive, local or remote.
This task, where any science project starts, would seem easy a priori but, considering the very
diverse array of missions and instrument nowaday available, proves to be one of the major bottleneck,
especially for students and newcomers.
Speasy solves this problem by providing a **single, easy-to-use interface to over 70 space missions and 65,000 products
**.
## Main features
- Simple and intuitive API (`spz.get_data(...)` to get them all)
- Speasy variables are like Pandas DataFrame with seemless conversion to/from it.
- Local cache to avoid redundant downloads
- Uses the SciQLOP ultra fast community cache server
- Full support of [AMDA](http://amda.irap.omp.eu/) API
- Can retrieve time-series from [AMDA](http://amda.irap.omp.eu/),
[CDAWeb](https://cdaweb.gsfc.nasa.gov/),
[CSA](https://csa.esac.esa.int/csa-web/),
[SSCWeb](https://sscweb.gsfc.nasa.gov/)
- Support data access from any local or remote archives described by YAML file.
## Help us improve Speasy!
We want Speasy to be the best possible tool for space physics research. You can help us by:
- Answering our user
survey [here](https://docs.google.com/forms/d/e/1FAIpQLScV12kvETk8jc4Zc4sIsHiteMHRVo5I8DiSAE8RyVdVkUaxJA/viewform?usp=sf_link).
- Reporting bugs or requesting features [here](https://github.com/SciQLop/speasy/issues/new).
- Creating or participating in discussions [here](https://github.com/SciQLop/speasy/discussions).
Your feedback is essential to making Speasy a better tool for everyone.
## Quickstart
Installing Speasy with pip ([more details
here](https://speasy.readthedocs.io/en/stable/installation.html)):
``` console
$ python -m pip install speasy
# or
$ python -m pip install --user speasy
```
This simple code example shows how easy it is to get data using Speasy. The code imports the Speasy package and defines
a variable named ace_mag. This variable stores the data for the ACE IMF product, for the time period from June 2, 2016
to June 5, 2016. The code then uses the Speasy plot() function to plot the data.
```python
import speasy as spz
ace_mag = spz.get_data('amda/imf', "2016-6-2", "2016-6-5")
ace_mag.plot();
```
Where amda is the webservice and imf is the product id you will get with
this request.
Using the dynamic inventory will produce the same result as the previous example, but it has the advantage of being
easier to manipulate, since you can discover available data from your favorite Python environment completion tool, such
as IPython or notebooks.
```python
import speasy as spz
amda_tree = spz.inventories.data_tree.amda
ace_mag = spz.get_data(amda_tree.Parameters.ACE.MFI.ace_imf_all.imf, "2016-6-2", "2016-6-5")
ace_mag.plot();
```
This code example shows how to use Speasy to plot multiple time series of space physics data from the **MMS1**
spacecraft on a single figure, with a shared x-axis. The code imports the Speasy package and
the [Matplotlib](https://matplotlib.org/stable/) plotting library. It then creates a figure with six subplots, arranged
in a single column. Next, it defines a list of products and axes to plot. Finally, it iterates over the list of products
and axes, plotting each product on the corresponding axis. The code uses the
Speasy [get_data()](https://speasy.readthedocs.io/en/latest/dev/speasy.html#speasy.get_data) function to load the data
for each product, and
the [replace_fillval_by_nan()](https://speasy.readthedocs.io/en/latest/dev/speasy.html#speasy.SpeasyVariable.replace_fillval_by_nan)
function to replace any fill values with NaNs.
```python
import speasy as spz
import matplotlib.pyplot as plt
fig = plt.figure(figsize=(8, 16), layout="constrained")
gs = fig.add_gridspec(6, hspace=0, wspace=0)
axes = gs.subplots(sharex=True)
plots = [
(spz.inventories.tree.cda.MMS.MMS1.FGM.MMS1_FGM_SRVY_L2.mms1_fgm_b_gse_srvy_l2_clean, axes[0]),
(spz.inventories.tree.cda.MMS.MMS1.SCM.MMS1_SCM_SRVY_L2_SCSRVY.mms1_scm_acb_gse_scsrvy_srvy_l2, axes[1]),
(spz.inventories.tree.cda.MMS.MMS1.DES.MMS1_FPI_FAST_L2_DES_MOMS.mms1_des_bulkv_gse_fast, axes[2]),
(spz.inventories.tree.cda.MMS.MMS1.DES.MMS1_FPI_FAST_L2_DES_MOMS.mms1_des_temppara_fast, axes[3]),
(spz.inventories.tree.cda.MMS.MMS1.DES.MMS1_FPI_FAST_L2_DES_MOMS.mms1_des_tempperp_fast, axes[3]),
(spz.inventories.tree.cda.MMS.MMS1.DES.MMS1_FPI_FAST_L2_DES_MOMS.mms1_des_energyspectr_omni_fast, axes[4]),
(spz.inventories.tree.cda.MMS.MMS1.DIS.MMS1_FPI_FAST_L2_DIS_MOMS.mms1_dis_energyspectr_omni_fast, axes[5])
]
def plot_product(product, ax):
values = spz.get_data(product, "2019-01-02T15", "2019-01-02T22")
values.replace_fillval_by_nan().plot(ax=ax)
for p in plots:
plot_product(p[0], p[1])
plt.show()
```
More complex requests like this one are supported:
```python
import speasy as spz
products = [
spz.inventories.tree.amda.Parameters.Wind.SWE.wnd_swe_kp.wnd_swe_vth,
spz.inventories.tree.amda.Parameters.Wind.SWE.wnd_swe_kp.wnd_swe_pdyn,
spz.inventories.tree.amda.Parameters.Wind.SWE.wnd_swe_kp.wnd_swe_n,
spz.inventories.tree.cda.Wind.WIND.MFI.WI_H2_MFI.BGSE,
spz.inventories.tree.ssc.Trajectories.wind,
]
intervals = [["2010-01-02", "2010-01-02T10"], ["2009-08-02", "2009-08-02T10"]]
data = spz.get_data(products, intervals)
data
```
[[<speasy.products.variable.SpeasyVariable at 0x7fddf2168d00>,
<speasy.products.variable.SpeasyVariable at 0x7fddf2570ac0>],
[<speasy.products.variable.SpeasyVariable at 0x7fddf220bc00>,
<speasy.products.variable.SpeasyVariable at 0x7fddf2158780>],
[<speasy.products.variable.SpeasyVariable at 0x7fddf2176c00>,
<speasy.products.variable.SpeasyVariable at 0x7fddf2177500>],
[<speasy.products.variable.SpeasyVariable at 0x7fddf2185c80>,
<speasy.products.variable.SpeasyVariable at 0x7fddf2187cc0>],
[<speasy.products.variable.SpeasyVariable at 0x7fddf2187940>,
<speasy.products.variable.SpeasyVariable at 0x7fddf21905c0>]]
### Documentation and examples
Check out [Speasy documentation](https://speasy.readthedocs.io/en/stable/)
and [examples](https://speasy.readthedocs.io/en/latest/examples/index.html).
### Caveats
- Speasy is not a plotting package.
basic plotting capabilities are here for illustration purposes and making quick-and-dirty plots.
It is not meant to produce publication ready figures, prefer using Matplotlib directly for example.
- Speasy is not a data analysis package.
It is meant to be used in conjunction with other packages such as [Pandas](https://pandas.pydata.org/),
[NumPy](https://numpy.org/), [SciPy](https://www.scipy.org/), [Astropy](https://www.astropy.org/), etc.
- Importing Speasy is slow.
This is due to the fact that Speasy has to load all the inventories and build the data tree.
This is done only once per session, so it is not a problem for interactive use.
However, if you are writing a script that needs to be run many times, you may want to consider disabling unused
providers. See [here](https://speasy.readthedocs.io/en/latest/user/configuration.html#disabling-providers) for more
details.
### Credits
The development of Speasy is supported by the [CDPP](http://www.cdpp.eu/).
This package was created with
[Cookiecutter](https://github.com/audreyr/cookiecutter) and the
[audreyr/cookiecutter-pypackage](https://github.com/audreyr/cookiecutter-pypackage)
project template.
Raw data
{
"_id": null,
"home_page": null,
"name": "speasy",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Alexis Jeandet <alexis.jeandet@member.fsf.org>",
"keywords": "satellite, plasma-physics, nasa-data, amda, cdpp, CDF",
"author": null,
"author_email": "Alexis Jeandet <alexis.jeandet@member.fsf.org>",
"download_url": "https://files.pythonhosted.org/packages/cd/38/2c1504c2699381f524e88a279c6e16403a22ce9c59c15d0dccacb0a20952/speasy-1.2.7.tar.gz",
"platform": null,
"description": "<h1 align=\"center\">\n<img src=\"https://raw.githubusercontent.com/SciQLop/speasy/main/logo/logo_speasy.svg\" width=\"300\">\n</h1><br>\n\n# Space Physics made EASY\n\n[](https://matrix.to/#/#speasy:matrix.org)\n[](https://pypi.python.org/pypi/speasy)\n[](https://github.com/SciQLop/speasy/actions?query=workflow%3A%22Tests%22)\n[](https://speasy.readthedocs.io/en/latest/?badge=latest)\n[](https://codecov.io/gh/SciQLop/speasy/branch/main)\n[](https://github.com/SciQLop/speasy/actions/workflows/codeql.yml)\n[](https://doi.org/10.5281/zenodo.4118780)\n[](https://mybinder.org/v2/gh/SciQLop/speasy/main?labpath=docs/examples)\n[](https://colab.research.google.com/github/SciQLop/speasy)\n[](http://sciqlop.lpp.polytechnique.fr/cache)\n\nSpeasy is a free and open-source Python package that makes it easy to find and load space physics data from a variety of\ndata sources, whether it is online and public such as [CDAWEB](https://cdaweb.gsfc.nasa.gov/index.html/)\nand [AMDA](http://amda.irap.omp.eu/),\nor any described archive, local or remote.\nThis task, where any science project starts, would seem easy a priori but, considering the very\ndiverse array of missions and instrument nowaday available, proves to be one of the major bottleneck,\nespecially for students and newcomers.\nSpeasy solves this problem by providing a **single, easy-to-use interface to over 70 space missions and 65,000 products\n**.\n\n## Main features\n\n- Simple and intuitive API (`spz.get_data(...)` to get them all)\n- Speasy variables are like Pandas DataFrame with seemless conversion to/from it.\n- Local cache to avoid redundant downloads\n- Uses the SciQLOP ultra fast community cache server\n- Full support of [AMDA](http://amda.irap.omp.eu/) API\n- Can retrieve time-series from [AMDA](http://amda.irap.omp.eu/),\n [CDAWeb](https://cdaweb.gsfc.nasa.gov/),\n [CSA](https://csa.esac.esa.int/csa-web/),\n [SSCWeb](https://sscweb.gsfc.nasa.gov/)\n- Support data access from any local or remote archives described by YAML file.\n\n## Help us improve Speasy!\n\nWe want Speasy to be the best possible tool for space physics research. You can help us by:\n\n- Answering our user\n survey [here](https://docs.google.com/forms/d/e/1FAIpQLScV12kvETk8jc4Zc4sIsHiteMHRVo5I8DiSAE8RyVdVkUaxJA/viewform?usp=sf_link).\n- Reporting bugs or requesting features [here](https://github.com/SciQLop/speasy/issues/new).\n- Creating or participating in discussions [here](https://github.com/SciQLop/speasy/discussions).\n\nYour feedback is essential to making Speasy a better tool for everyone.\n\n## Quickstart\n\nInstalling Speasy with pip ([more details\nhere](https://speasy.readthedocs.io/en/stable/installation.html)):\n\n``` console\n$ python -m pip install speasy\n# or\n$ python -m pip install --user speasy\n```\n\nThis simple code example shows how easy it is to get data using Speasy. The code imports the Speasy package and defines\na variable named ace_mag. This variable stores the data for the ACE IMF product, for the time period from June 2, 2016\nto June 5, 2016. The code then uses the Speasy plot() function to plot the data.\n\n```python\nimport speasy as spz\n\nace_mag = spz.get_data('amda/imf', \"2016-6-2\", \"2016-6-5\")\nace_mag.plot();\n```\n\n\n\nWhere amda is the webservice and imf is the product id you will get with\nthis request.\n\nUsing the dynamic inventory will produce the same result as the previous example, but it has the advantage of being\neasier to manipulate, since you can discover available data from your favorite Python environment completion tool, such\nas IPython or notebooks.\n\n```python\nimport speasy as spz\n\namda_tree = spz.inventories.data_tree.amda\nace_mag = spz.get_data(amda_tree.Parameters.ACE.MFI.ace_imf_all.imf, \"2016-6-2\", \"2016-6-5\")\nace_mag.plot();\n```\n\n\n\nThis code example shows how to use Speasy to plot multiple time series of space physics data from the **MMS1**\nspacecraft on a single figure, with a shared x-axis. The code imports the Speasy package and\nthe [Matplotlib](https://matplotlib.org/stable/) plotting library. It then creates a figure with six subplots, arranged\nin a single column. Next, it defines a list of products and axes to plot. Finally, it iterates over the list of products\nand axes, plotting each product on the corresponding axis. The code uses the\nSpeasy [get_data()](https://speasy.readthedocs.io/en/latest/dev/speasy.html#speasy.get_data) function to load the data\nfor each product, and\nthe [replace_fillval_by_nan()](https://speasy.readthedocs.io/en/latest/dev/speasy.html#speasy.SpeasyVariable.replace_fillval_by_nan)\nfunction to replace any fill values with NaNs.\n\n```python\nimport speasy as spz\nimport matplotlib.pyplot as plt\n\nfig = plt.figure(figsize=(8, 16), layout=\"constrained\")\ngs = fig.add_gridspec(6, hspace=0, wspace=0)\naxes = gs.subplots(sharex=True)\n\nplots = [\n (spz.inventories.tree.cda.MMS.MMS1.FGM.MMS1_FGM_SRVY_L2.mms1_fgm_b_gse_srvy_l2_clean, axes[0]),\n (spz.inventories.tree.cda.MMS.MMS1.SCM.MMS1_SCM_SRVY_L2_SCSRVY.mms1_scm_acb_gse_scsrvy_srvy_l2, axes[1]),\n (spz.inventories.tree.cda.MMS.MMS1.DES.MMS1_FPI_FAST_L2_DES_MOMS.mms1_des_bulkv_gse_fast, axes[2]),\n (spz.inventories.tree.cda.MMS.MMS1.DES.MMS1_FPI_FAST_L2_DES_MOMS.mms1_des_temppara_fast, axes[3]),\n (spz.inventories.tree.cda.MMS.MMS1.DES.MMS1_FPI_FAST_L2_DES_MOMS.mms1_des_tempperp_fast, axes[3]),\n (spz.inventories.tree.cda.MMS.MMS1.DES.MMS1_FPI_FAST_L2_DES_MOMS.mms1_des_energyspectr_omni_fast, axes[4]),\n (spz.inventories.tree.cda.MMS.MMS1.DIS.MMS1_FPI_FAST_L2_DIS_MOMS.mms1_dis_energyspectr_omni_fast, axes[5])\n]\n\n\ndef plot_product(product, ax):\n values = spz.get_data(product, \"2019-01-02T15\", \"2019-01-02T22\")\n values.replace_fillval_by_nan().plot(ax=ax)\n\n\nfor p in plots:\n plot_product(p[0], p[1])\n\nplt.show()\n```\n\n\n\nMore complex requests like this one are supported:\n\n```python\nimport speasy as spz\n\nproducts = [\n spz.inventories.tree.amda.Parameters.Wind.SWE.wnd_swe_kp.wnd_swe_vth,\n spz.inventories.tree.amda.Parameters.Wind.SWE.wnd_swe_kp.wnd_swe_pdyn,\n spz.inventories.tree.amda.Parameters.Wind.SWE.wnd_swe_kp.wnd_swe_n,\n spz.inventories.tree.cda.Wind.WIND.MFI.WI_H2_MFI.BGSE,\n spz.inventories.tree.ssc.Trajectories.wind,\n]\nintervals = [[\"2010-01-02\", \"2010-01-02T10\"], [\"2009-08-02\", \"2009-08-02T10\"]]\ndata = spz.get_data(products, intervals)\ndata\n```\n\n [[<speasy.products.variable.SpeasyVariable at 0x7fddf2168d00>,\n <speasy.products.variable.SpeasyVariable at 0x7fddf2570ac0>],\n [<speasy.products.variable.SpeasyVariable at 0x7fddf220bc00>,\n <speasy.products.variable.SpeasyVariable at 0x7fddf2158780>],\n [<speasy.products.variable.SpeasyVariable at 0x7fddf2176c00>,\n <speasy.products.variable.SpeasyVariable at 0x7fddf2177500>],\n [<speasy.products.variable.SpeasyVariable at 0x7fddf2185c80>,\n <speasy.products.variable.SpeasyVariable at 0x7fddf2187cc0>],\n [<speasy.products.variable.SpeasyVariable at 0x7fddf2187940>,\n <speasy.products.variable.SpeasyVariable at 0x7fddf21905c0>]]\n\n### Documentation and examples\n\nCheck out [Speasy documentation](https://speasy.readthedocs.io/en/stable/)\nand [examples](https://speasy.readthedocs.io/en/latest/examples/index.html).\n\n### Caveats\n\n- Speasy is not a plotting package.\n basic plotting capabilities are here for illustration purposes and making quick-and-dirty plots.\n It is not meant to produce publication ready figures, prefer using Matplotlib directly for example.\n- Speasy is not a data analysis package.\n It is meant to be used in conjunction with other packages such as [Pandas](https://pandas.pydata.org/),\n [NumPy](https://numpy.org/), [SciPy](https://www.scipy.org/), [Astropy](https://www.astropy.org/), etc.\n- Importing Speasy is slow.\n This is due to the fact that Speasy has to load all the inventories and build the data tree.\n This is done only once per session, so it is not a problem for interactive use.\n However, if you are writing a script that needs to be run many times, you may want to consider disabling unused\n providers. See [here](https://speasy.readthedocs.io/en/latest/user/configuration.html#disabling-providers) for more\n details.\n\n### Credits\n\nThe development of Speasy is supported by the [CDPP](http://www.cdpp.eu/).\n\nThis package was created with\n[Cookiecutter](https://github.com/audreyr/cookiecutter) and the\n[audreyr/cookiecutter-pypackage](https://github.com/audreyr/cookiecutter-pypackage)\nproject template.\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "A simple Python package to deal with main Space Physics WebServices (CDA, CSA, AMDA and SSC).",
"version": "1.2.7",
"project_urls": {
"homepage": "https://github.com/SciQLop/speasy"
},
"split_keywords": [
"satellite",
" plasma-physics",
" nasa-data",
" amda",
" cdpp",
" cdf"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "dfcf929c432923509dd122a87e1bb7ac8eef8bb14fa8046a6053689fdbefe67f",
"md5": "24a4bb51e0423f2b65b3dd488eaaff75",
"sha256": "55d3ecf70963578384602641844cdfe081b838b5086381ad3c0497c912757a01"
},
"downloads": -1,
"filename": "speasy-1.2.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "24a4bb51e0423f2b65b3dd488eaaff75",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 80931,
"upload_time": "2024-04-17T13:31:21",
"upload_time_iso_8601": "2024-04-17T13:31:21.340231Z",
"url": "https://files.pythonhosted.org/packages/df/cf/929c432923509dd122a87e1bb7ac8eef8bb14fa8046a6053689fdbefe67f/speasy-1.2.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cd382c1504c2699381f524e88a279c6e16403a22ce9c59c15d0dccacb0a20952",
"md5": "a2ac2007523bc0af69f057bd4ad998dc",
"sha256": "70dd0f1a559ba7ca707c94fcce29f57157494557096740ee316219f83d5a37e9"
},
"downloads": -1,
"filename": "speasy-1.2.7.tar.gz",
"has_sig": false,
"md5_digest": "a2ac2007523bc0af69f057bd4ad998dc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 64530,
"upload_time": "2024-04-17T13:31:30",
"upload_time_iso_8601": "2024-04-17T13:31:30.891634Z",
"url": "https://files.pythonhosted.org/packages/cd/38/2c1504c2699381f524e88a279c6e16403a22ce9c59c15d0dccacb0a20952/speasy-1.2.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-17 13:31:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "SciQLop",
"github_project": "speasy",
"travis_ci": true,
"coveralls": true,
"github_actions": true,
"requirements": [
{
"name": "pandas",
"specs": []
},
{
"name": "appdirs",
"specs": []
},
{
"name": "diskcache",
"specs": []
},
{
"name": "requests",
"specs": []
},
{
"name": "urllib3",
"specs": [
[
">=",
"1.26.0"
]
]
},
{
"name": "packaging",
"specs": []
},
{
"name": "numpy",
"specs": []
},
{
"name": "python_dateutil",
"specs": []
},
{
"name": "astropy",
"specs": []
},
{
"name": "pyistp",
"specs": [
[
">=",
"0.4.0"
]
]
},
{
"name": "astroquery",
"specs": []
},
{
"name": "tqdm",
"specs": []
},
{
"name": "matplotlib",
"specs": []
},
{
"name": "PyYAML",
"specs": []
}
],
"tox": true,
"lcname": "speasy"
}
JSON
