Difference between revisions of "Getting Started with pySPEDAS"

From SPEDAS Wiki
Jump to navigation Jump to search
Line 1: Line 1:
 
== Welcome to pySPEDAS ==
 
== Welcome to pySPEDAS ==
  
pySPEDAS is the SPEDAS software in the python programming language.
+
pySPEDAS is an implementation of the SPEDAS framework in Python.
It is currently in development and it does not contain as many functions as the IDL SPEDAS software.  
 
  
Examples and tutorials can be found in the companion projects:<br>
+
=== Requirements ===
pyspedas_examples<br>
+
* Python 3.7 and later (as of pySPEDAS v1.2)
mms_examples
 
  
 +
== pySPEDAS releases ==
 +
 +
* [https://github.com/spedas/pyspedas github source code/bleeding edge]
 +
* [https://pypi.org/project/pyspedas/ PyPI]
 +
 +
== 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:
  
== pySPEDAS releases ==
+
=== macOS and Linux ===
 +
<syntaxhighlight lang="cmd">
 +
source environment-name/bin/activate
 +
</syntaxhighlight>
 +
 
 +
=== Windows ===
 +
<syntaxhighlight lang="cmd">
 +
.\environment-name\Scripts\activate
 +
</syntaxhighlight>
 +
 
 +
== Installing pySPEDAS ==
 +
 
 +
The first time you enter your virtual environment, you’ll have to install pyspedas; this is as simple as:
  
* [https://github.com/spedas/pyspedas github source code]
+
<syntaxhighlight lang="cmd">
* [https://pypi.org/project/pyspedas/ pip release]
+
pip install pyspedas
* [https://anaconda.org/spedas/pyspedas conda release]
+
</syntaxhighlight>
  
 +
This should go out and find all of the required libraries and install them inside the virtual environment.
  
== Install pySPEDAS ==
+
If you would like to upgrade your copy of the pySPEDAS libraries inside of your virtual environment, use:
  
An easy way to install pyspedas is to install the latest Anaconda distribution:
+
<syntaxhighlight lang="cmd">
 +
pip install pyspedas --upgrade
 +
</syntaxhighlight>
  
* https://www.anaconda.com/distribution/
+
== 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).
  
Then, open the anaconda prompt and type:
+
Mission specific data directories (e.g., 'MMS_DATA_DIR') can also be set, and these will override 'SPEDAS_DATA_DIR'
  
<pre>conda install -c spedas pyspedas</pre>
+
== Checking that everything is working ==
  
This will install all required files. To test the installation, you can open a command prompt, type 'python' to start the python interpreter and then type:
+
The quickest way to check if everything is working is to load some data; once you’re inside Python in your virtual environment, try:
  
<pre>
+
<syntaxhighlight lang="python">
 
import pyspedas
 
import pyspedas
pyspedas.version()
+
pyspedas.mms.fgm()
</pre>
+
</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>
  
The installed version of pyspedas should be printed.
+
== Using Jupyter notebooks with your virtual environment ==
  
 +
To get virtual environments working with Jupyter, there are a few extra steps:
  
You can also install pyspedas using pip:
+
in the virtual environment, type:
  
<pre>pip install pyspedas</pre>
+
<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 ==
 
== Examples ==
Line 46: Line 99:
 
There are two projects that contain examples of using pyspedas:
 
There are two projects that contain examples of using pyspedas:
  
 +
MMS Examples
 +
* [https://github.com/spedas/mms-examples github source code for mms-examples]
  
* [https://github.com/spedas/mms-examples github source code for mms-examples]
+
Examples for other missions and general webinars
 
* [https://github.com/spedas/pyspedas_examples github source code for pyspedas_examples]
 
* [https://github.com/spedas/pyspedas_examples github source code for pyspedas_examples]
 
 
These can be installed using pip:
 
 
<pre>
 
pip install pyspedas_examples
 
</pre>
 
 
  
 
== Comparison of pySPEDAS to SPEDAS ==
 
== Comparison of pySPEDAS to SPEDAS ==

Revision as of 22:53, 18 May 2021

Welcome to pySPEDAS

pySPEDAS is an implementation of the SPEDAS framework in Python.

Requirements

  • Python 3.7 and later (as of pySPEDAS v1.2)

pySPEDAS releases

Installing 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 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:

python -m venv pyspedas

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

macOS and Linux

source environment-name/bin/activate

Windows

.\environment-name\Scripts\activate

Installing pySPEDAS

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

pip install pyspedas

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:

pip install pyspedas --upgrade

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'

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:

import pyspedas
pyspedas.mms.fgm()

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

from pytplot import tplot
tplot('mms1_fgm_b_gse_srvy_l2')

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:

pip install ipykernel
python -m ipykernel install --user --name pyspedas --display-name "Python (pySPEDAS)"

(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 projects that contain examples of using pyspedas:

MMS Examples

Examples for other missions and general webinars

Comparison of pySPEDAS to SPEDAS

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