Getting Started with pySPEDAS

Welcome to PySPEDAS

PySPEDAS is an implementation of the SPEDAS framework in Python. PySPEDAS has tools for loading, analyzing, and plotting data from over 30 different directly supported satellite missions and ground magnetometer networks, as well as other sources like NASA's CDAWeb multi-mission data archive service, and HAPI (Heliophysics Application Programming Interface) servers.

PySPEDAS is a core package of the Python Heliophysics Community (pyhc.org) PyHC is working to promote standardization, interoperability, and open science principles among the various Python packages in this space (Astropy, SunPy, pysat, SpiceyPy, and others).

Requirements

As of PySPEDAS version 1.4.46, Python 3.8 or later is required. Note that PySPEDAS has dependencies on many other Python packages, some of which may need to be updated to work with newly released Python versions, OS versions, CPU architectures, etc. As of this writing (October 2023), PySPEDAS and its dependencies should be compatible with Python 3.8 through 3.10.

Certain packages may still have incompatibilities with Python 3.11 or Python 3.12. Other packages may depend on binary libraries that may not be available "out of the box" for certain OS versions or CPU architectures (for example, Mac laptops with M2 chips). It is possible that "pip install" may fail for such packages, if your environment doesn't have all the necessary compiler tools or prerequisite packages installed. If this happens to you while installing or updating PySPEDAS, please let the development team know, and we'll try to help you get things running.

pySPEDAS releases

• GitHub (bleeding edge and major releases)
• PyPI (latest stable release)

Installing Python

If you're not already familiar with using Python, you may want to visit (python.org) and read some documentation, work through a few tutorials, and familiarize yourself a bit with the Python ecosystem, before taking the plunge and installing a Python environment. PyHC also has links to some resources for getting started with Python.

We suggest that you install Python using the Anaconda distribution; step-by-step instructions for installing Anaconda can be found at:

• macOS: https://docs.anaconda.com/anaconda/install/mac-os/
• Windows: https://docs.anaconda.com/anaconda/install/windows/
• Linux: https://docs.anaconda.com/anaconda/install/linux/

Once Anaconda is installed, you can use Anaconda Navigator as a graphical interface to create Python virtual environments (described more fully below) with several options for the version of Python to be used in each environment, by selecting "Environments" from the leftmost pane, then using the "Create" button at the bottom of the second pane. You should get a dropdown menu of Python versions...select the version you want to use, and once it's created, you can activate it for use within Anaconda, or use it in your interactive development environment (see below) when you're setting up a new project.

Installing an Interactive Development Environment (IDE)

Strictly speaking, all you really need is a Python interpreter and a text editor to create and run PySPEDAS programs. But a good Python IDE will make it much easier to install, understand, navigate, and run PySPEDAS code. An IDE will generally let you create multiple independent projects, each with its own virtual environment. There will probably be a way to create a new project from a git or other version control repository. The PySPEDAS code and many usage examples are developed in several repositories on Github (for example, PySPEDAS, Pyspedas examples, MMS examples). (You may want to consider installing the git command line tools on your machine...some IDEs rely on having git available to connect your project to a Github repository.) Within a project, the IDE provide an area with editing tools where you can view or develop Python code. You will probably be able to highlight routine names and go directly to files where they're implemented, or hover over a routine name and get a tooltip showing the parameters it expects and other documentation.

Some popular IDEs for Python development include:

• PyCharm , used by several PySPEDAS developers
• Visual Studio Code , also used by some PySPEDAS developers
• Spyder

PyHC also has a list of suggested IDEs and other Python development tools.

Downloads, installation instructions, and other documentation is available at each of their respective web sites,

Creating a virtual environment

To avoid potential dependency issues with other Python packages, it’s best to create a dedicated virtual environment in Python for working with PySPEDAS.

You can create a virtual environment in your terminal with:

<syntaxhighlight lang="cmd"> python -m venv pyspedas </syntaxhighlight>

And enter into that virtual environment by running the 'activate' script with:

macOS and Linux

<syntaxhighlight lang="cmd"> source pyspedas/bin/activate </syntaxhighlight>

Windows

<syntaxhighlight lang="cmd"> .\pyspedas\Scripts\activate </syntaxhighlight>

Installing pySPEDAS

The first time you enter your virtual environment, you’ll have to install pyspedas; this is as simple as:

<syntaxhighlight lang="cmd"> pip install pyspedas </syntaxhighlight>

This should go out and find all of the required libraries and install them inside the virtual environment.

If you would like to upgrade your copy of the pySPEDAS libraries inside of your virtual environment, use:

<syntaxhighlight lang="cmd"> pip install pyspedas --upgrade </syntaxhighlight>

Setting your local data directory

The recommended way of setting your local data directory is to set the 'SPEDAS_DATA_DIR' environment variable. 'SPEDAS_DATA_DIR' acts as a root data directory for all missions, and will also be used by IDL (if you’re running a recent copy of the bleeding edge).

Mission specific data directories (e.g., 'MMS_DATA_DIR') can also be set, and these will override 'SPEDAS_DATA_DIR'

Network mirror for the MMS dataset

If you have a mirror of the MMS dataset on your local network, you may want to set the MMS_MIRROR_DATA_DIR environment variable.

If set, when you use the no_update keyword in the load routines (or if don’t have an internet connection), the load routines will check the mirror for data. Just as in IDL, data files found on the network mirror will be copied to your local data directory before loading them.

Checking that everything is working

The quickest way to check if everything is working is to load some data; once you’re inside Python in your virtual environment, try:

<syntaxhighlight lang="python"> import pyspedas pyspedas.mms.fgm() </syntaxhighlight>

This should load some default data (srvy mode, probe 1) for Oct 16, 2015. You can then plot the FGM data with:

<syntaxhighlight lang="python"> from pytplot import tplot tplot('mms1_fgm_b_gse_srvy_l2') </syntaxhighlight>

Using Jupyter notebooks with your virtual environment

To get virtual environments working with Jupyter, there are a few extra steps:

in the virtual environment, type:

<syntaxhighlight lang="cmd"> pip install ipykernel python -m ipykernel install --user --name pyspedas --display-name "Python (pySPEDAS)" </syntaxhighlight>

(note: "pyspedas" is the name of your virtual environment)

Then once you open the notebook, go to "Kernel" then "Change kernel" and select the one named "Python (pySPEDAS)"

Recorded tutorials, presentation slides, notebooks

• UCLA class and demo, October 5, 2023

Examples

There are two repositories that contain examples of using pyspedas:

MMS Examples

• Jupyter notebooks containing MMS examples

Examples for other missions and general webinars

• Jupyter notebooks containing pySPEDAS examples

Google Colab Examples (Jupyter notebooks that run in the cloud...no local Python installation required!)

• Getting Started with PySPEDAS, UCLA class demo, October 5, 2023
• Exploring the Heliosphere with Python

You can also browse the README.md files using GitHub for more information and examples, e.g.,

• MMS README.md file

Comparison of pySPEDAS to SPEDAS

Some examples that demonstrate how to achieve the same results using either IDL SPEDAS or python pySPEDAS.

• Smooth function
• Spectrogram
• Wavelet
• Cotrans