Getting Started with pySPEDAS

From SPEDAS Wiki
Jump to navigation Jump to search

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 2.0.7, Python 3.10 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 (February 2026), PySPEDAS and its dependencies should be compatible with Python 3.10 through 3.13.

Certain packages may still have incompatibilities with Python 3.14. 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.

Documentation

The main documentation hub for PySPEDAS is pyspedas.readthedocs.io . Those pages are tightly coupled to the PySPEDAS code itself, and are continuously updated along with the PySPEDAS code base.

In addition to detailed descriptions of the PySPEDAS utilities, we have several pages describing how to get started with Python and PySPEDAS:


Getting started with Python and PySPEDAS: https://pyspedas.readthedocs.io/en/latest/getting_started.html#

PySPEDAS developers guide: https://pyspedas.readthedocs.io/en/latest/devguide.html

Migrating older PySPEDAS code to work with PySPEDAS 2.0 and above: https://pyspedas.readthedocs.io/en/latest/pyspedas_2_migration.html

Setting up a PySPEDAS development environment with PyCharm: https://pyspedas.readthedocs.io/en/latest/dev_pycharm.html

Setting up a PySPEDAS development environment with Visual Studio Code: https://pyspedas.readthedocs.io/en/latest/dev_vscode.html

Contributing to PySPEDAS: https://pyspedas.readthedocs.io/en/latest/contributing.html

Example Notebooks

The PySPEDAS developers maintain several sets of example notebooks on Github:


See this section of the "Getting Started" guide for instructions to download and run Jupyter notebooks from our example repositories:

https://pyspedas.readthedocs.io/en/latest/getting_started.html#working-with-jupyter-notebooks

"PySPEDAS in the cloud" with Google Colab

Google runs a cloud service, "Google Colab", which can run Jupyter notebooks in their cloud, with no local Python or PySPEDAS installation required. This is a great

way to try out PySPEDAS without committing to a complicated installation process, or to share your work with a colleague who might not have a PySPEDAS installation.

See this section of the "Getting Started" guide for instructions to run PySPEDAS examples in the Google Colab environment:


https://pyspedas.readthedocs.io/en/latest/getting_started.html#pyspedas-examples-on-google-colab-pyspedas-in-the-cloud-no-local-installation-required


Here are a couple of direct links to PySPEDAS examples on Google Colab:

pySPEDAS releases

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:

Once Anaconda is installed, you can use Anaconda Navigator as a graphical interface to create Python virtual environments (described more fully below), or install a variety of development environments and other useful tools.


See the "Getting Started" guide for the latest recommended setup steps for Python and PySPEDAS: https://pyspedas.readthedocs.io/en/latest/getting_started.html#


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:

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.

See our latest recommend steps for setting up a PySPEDAS development environment here:

Setting up a PySPEDAS development environment with PyCharm: https://pyspedas.readthedocs.io/en/latest/dev_pycharm.html

Setting up a PySPEDAS development environment with Visual Studio Code: https://pyspedas.readthedocs.io/en/latest/dev_vscode.html

Developer install via Github, versus user install via "pip install"

When you're creating a new project, your IDE probably offers several ways to get started. The method you choose depends on how you'll be using PySPEDAS. If you'll be using PySPEDAS as more of an end user, and just want to install a stable, fully-tested package, you'll probably want to create a fresh virtual environment (described below), then install the PySPEDAS package using "pip install pyspedas".

If you are interested in contributing to PySPEDAS itself, or if you want to keep up with the "bleeding edge", and have access to new features and bug fixes as soon as they're committed to the PySPEDAS repository, you would probably want to use your IDE's option to create a project starting from a Github repository. If you take this route, you may need to have the Git command-line tools installed on your machine. See the Git web site for downloads and installation instructions. The URL for the PySPEDAS Github repo is https://github.com/spedas/pyspedas.git . Copy and paste this URL into your IDE's project setup panel, then follow the rest of your IDE's instructions for creating the project. If you use this method to get PySPEDAS, you don't need to do the "pip install pyspedas" step...you will already have the PySPEDAS source code cloned directly from the repository. However, you will still need to install several packages that PySPEDAS depends on. Your IDE may prompt you to do this as part of creating the project, or you might have to use a command like "pip install -r requirements.txt" to install the dependencies.

Recorded tutorials, presentation slides, notebooks

Comparison of pySPEDAS to SPEDAS

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

Retrieved from "http://spedas.org/wiki/index.php?title=Getting_Started_with_pySPEDAS&oldid=13276"