Getting Started with pySPEDAS

Welcome to pySPEDAS

pySPEDAS is an implementation of the SPEDAS framework in Python.

Requirements

• Python 3.8 and later (as of pySPEDAS v1.4.46)

pySPEDAS releases

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

Installing 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 should be able to open Python in your terminal window by typing "python". Note: your Python version will be the first line displayed; Python 3.7 or later is required.

Creating a virtual environment

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

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)"

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

Recorded Tutorials

• UCLA Class and Demo, October 5, 2023

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