<jupyter_start><jupyter_text>pySPEDAS 1.0 Tutorial<NAME> <EMAIL> Introduction Requirements- Python 3.5 or later All of this depends on the hard work of the pyTplot developers at LASPTo learn more about pytplot:https://pytplot.readthedocs.io/ Virtual Environments- Best to use them to avoid dependency issues; Python 3.5 and later make creating a virtual environment as simple as:`python -m venv pyspedas-tutorial`Then, to run the virtual environment, on Windows:`.\pyspedas-tutorial\Scripts\activate`and on macOS / Linux:`source pyspedas-tutorial/bin/activate`To exit the current virtual environment, type `deactivate` Installing pySPEDASIn your virtual environment, type:`pip install pyspedas` Upgrade pySPEDAS`pip install pyspedas --upgrade` pySPEDAS on GitHubhttps://github.com/spedas/pyspedas Problems with AnacondaNote: if you have trouble creating a virtual environment or installing pyspedas and are using Anaconda, try to update Anaconda in your terminal with the command:`conda update --all`  Getting Started Structure of the load routinesThe structure of the load routines follow:    pyspedas.mission.instrument()e.g.,     pyspedas.mms.fgm()Data options are set via keywords passed to the load routines; e.g.,     pyspedas.mms.fgm(trange=['2015-12-15', '2015-12-16'])these have defaults which should load some default data. These functions return the names of the tplot variables created. Note: some options change the return values, e.g., setting `notplot=True` will tell the load routine to return the variables in hash tables containing numpy arrays; `downloadonly=True` will return the names of the files downloaded. Local data directoryYour data directory can be set using the `SPEDAS_DATA_DIR` environment variable. Each mission also has its own data directory, e.g., `MMS_DATA_DIR`, `THM_DATA_DIR`, etc. Note: mission data directories will override the root data directory set in `SPEDAS_DATA_DIR`. Importing pySPEDASTo get started, import pyspedas:<jupyter_code>import pyspedas<jupyter_output><empty_output><jupyter_text>You can also access the load routines by importing the mission modules:<jupyter_code>from pyspedas import mms, themis, cluster<jupyter_output><empty_output><jupyter_text>This allows you to load data via mms.fgm(trange=[...])You can also import the instrument load routines, e.g.:<jupyter_code>from pyspedas.mms import fgm, fpi
from pyspedas.themis import esa, sst<jupyter_output><empty_output><jupyter_text>Projects Supported- Advanced Composition Explorer (ACE)- Arase (ERG) - note: experimental!- Cluster- Colorado Student Space Weather Experiment (CSSWE)- Deep Space Climate Observatory (DSCOVR)- Equator-S- Fast Auroral Snapshot Explorer (FAST)- Geotail- Geostationary Operational Environmental Satellite (GOES)- Imager for Magnetopause-to-Aurora Global Exploration (IMAGE)- Mars Atmosphere and Volatile Evolution (MAVEN)- Magnetic Induction Coil Array (MICA)- Magnetospheric Multiscale (MMS)- OMNI- Polar Orbiting Environmental Satellites (POES)- Polar- Parker Solar Probe (PSP)- Van Allen Probes (RBSP)- Solar Terrestrial Relations Observatory (STEREO)- Time History of Events and Macroscale Interactions during Substorms (THEMIS)- Two Wide-Angle Imaging Neutral-Atom Spectrometers (TWINS)- Ulysses- Wind To find the available options in a load routine, call the help() function on the load routine<jupyter_code>help(pyspedas.mms.fpi)
help(esa)<jupyter_output>Help on function esa in module pyspedas.themis.spacecraft.particles.esa:

esa(trange=['2007-03-23', '2007-03-24'], probe='c', level='l2', suffix='', get_support_data=False, varformat=None, varnames=[], downloadonly=False, notplot=False, no_update=False, time_clip=False)
    This function loads Electrostatic Analyzer (ESA) data
    
    Parameters:
        trange : list of str
            time range of interest [starttime, endtime] with the format
            'YYYY-MM-DD','YYYY-MM-DD'] or to specify more or less than a day
            ['YYYY-MM-DD/hh:mm:ss','YYYY-MM-DD/hh:mm:ss']
    
        probe: str or list of str
            Spacecraft probe letter(s) ('a', 'b', 'c', 'd' and/or 'e')
    
        level: str
            Data type; Valid options: 'l1', 'l2'
    
        suffix: str
            The tplot variable names will be given this suffix.
            By default, no suffix is added.
    
        get_support_data: bool
            Data with an attribute "VAR_TYPE" with a value of [...]<jupyter_text>Loading Data Magnetospheric Multiscale (MMS) MissionTo load 6 hours of MMS FGM data on Oct 16, 2015:<jupyter_code>data = pyspedas.mms.fgm(trange=['2015-10-16/6:00', '2015-10-16/12:00'], time_clip=True)
data<jupyter_output><empty_output><jupyter_text>To list the tplot variables loaded, use `tplot_names` from `pytplot`<jupyter_code>from pytplot import tplot_names
tplot_names()<jupyter_output>0 : mms1_fgm_b_gse_srvy_l2
1 : mms1_fgm_b_gsm_srvy_l2
2 : mms1_fgm_b_dmpa_srvy_l2
3 : mms1_fgm_b_bcs_srvy_l2
4 : mms1_fgm_flag_srvy_l2
5 : mms1_fgm_r_gse_srvy_l2
6 : mms1_fgm_r_gsm_srvy_l2
7 : mms1_fgm_hirange_srvy_l2
8 : mms1_fgm_bdeltahalf_srvy_l2
9 : mms1_fgm_stemp_srvy_l2
10 : mms1_fgm_etemp_srvy_l2
11 : mms1_fgm_mode_srvy_l2<jupyter_text>To plot a variable, import `tplot` from pytplot<jupyter_code>from pytplot import tplot
tplot('mms1_fgm_b_gse_srvy_l2')<jupyter_output><empty_output><jupyter_text>`tplot` also accepts a list of variable names, e.g.,<jupyter_code>tplot(['mms1_fgm_b_gse_srvy_l2', 'mms1_fgm_b_gsm_srvy_l2'], save_png='/path/to/filename')<jupyter_output><empty_output><jupyter_text>To load MMS FPI burst-mode electron energy spectra (from the moments CDFs)<jupyter_code>pyspedas.mms.fpi(trange=['2015-10-16/13:06', '2015-10-16/13:07'], data_rate='brst', datatype='des-moms')
tplot(['mms1_des_energyspectr_omni_brst', 'mms1_des_energyspectr_perp_brst', 'mms1_des_energyspectr_par_brst'])<jupyter_output><empty_output><jupyter_text>Time History of Events and Macroscale Interactions during Substorms (THEMIS)To load THEMIS search-coil magnetometer (SCM) data:<jupyter_code>pyspedas.themis.scm(probe='d', trange=['2016-10-16', '2016-10-17'])
tplot(['thd_scf_gse', 'thd_scf_gsm'])<jupyter_output><empty_output><jupyter_text>The plot metadata can be updated with `options` fron `pytplot`<jupyter_code>from pytplot import options<jupyter_output><empty_output><jupyter_text>To find the available options, run the help() function on the options function after importing it<jupyter_code>help(options)<jupyter_output>Help on function options in module pytplot.options:

options(name, option=None, value=None, opt_dict=None)
    This function allows the user to set a large variety of options for individual plots.
    
    Parameters:
        name : str
            Name or number of the tplot variable
        option : str
            The name of the option.  See section below.
        value : str/int/float/list
            The value of the option.  See section below.
        dict : dict
            This can be a dictionary of option:value pairs.  Option and value
            will not be needed if this dictionary item is supplied.
    
    Options:
        =================== ==========   =====
        Options             Value type   Notes
        =================== ==========   =====
        Color               str/list     Red, Orange, Yellow, Green, Blue, etc.
        Colormap            str/list     https://matplotlib.org/examples/color/colormaps_reference.html.
        Spec                int    [...]<jupyter_text>Set the label names<jupyter_code>options('thd_scf_gsm', 'legend_names', ['Bx GSM', 'By GSM', 'Bz GSM'])
options('thd_scf_gse', 'legend_names', ['Bx GSE', 'By GSE', 'Bz GSE'])<jupyter_output><empty_output><jupyter_text>Set the line colors<jupyter_code>options('thd_scf_gsm', 'Color', ['blue', 'green', 'red'])
options('thd_scf_gse', 'Color', ['blue', 'green', 'red'])<jupyter_output><empty_output><jupyter_text>Set the yrange<jupyter_code>options('thd_scf_gsm', 'yrange', [-20, 20])
options('thd_scf_gse', 'yrange', [-20, 20])<jupyter_output><empty_output><jupyter_text>Replot the data with the updated metadata<jupyter_code>tplot(['thd_scf_gse', 'thd_scf_gsm'])<jupyter_output><empty_output><jupyter_text>Van Allen Probes (RBSP)To load RBSP emfisis data:<jupyter_code>pyspedas.rbsp.emfisis(trange=['2016-10-16', '2016-10-17'])
help(pyspedas.rbsp.emfisis)
tplot(['Magnitude', 'Mag'])<jupyter_output><empty_output><jupyter_text>Just like with MMS instruments, you can find the available options for the load routines using help()<jupyter_code>help(pyspedas.rbsp.mageis)<jupyter_output>Help on function mageis in module pyspedas.rbsp:

mageis(trange=['2015-11-5', '2015-11-6'], probe='a', datatype='', level='l3', rel='rel04', suffix='', get_support_data=False, varformat=None, downloadonly=False, notplot=False, no_update=False, time_clip=False)
    This function loads data from the Energetic Particle, Composition, and Thermal Plasma Suite (ECT)
    
    Parameters:
        trange : list of str
            time range of interest [starttime, endtime] with the format 
            'YYYY-MM-DD','YYYY-MM-DD'] or to specify more or less than a day 
            ['YYYY-MM-DD/hh:mm:ss','YYYY-MM-DD/hh:mm:ss']
    
        probe: str or list of str
            Spacecraft probe name ('a' or 'b'); default: a
    
        datatype: str
            Data type; Valid options:
    
        suffix: str
            The tplot variable names will be given this suffix.  By default, 
            no suffix is added.
    
        get_support_data: bool
            Data with an attribute "VAR_TYPE[...]<jupyter_text>Most load routines support the downloadonly option; this tells the load routine to download the data files, but not load them into tplot variables<jupyter_code>files = pyspedas.rbsp.mageis(trange=['2018-11-5', '2018-11-6'], probe=['a', 'b'], downloadonly=True)
files<jupyter_output><empty_output><jupyter_text>Deep Space Climate Observatory (DSCOVR)To load DSCOVR magnetometer data:<jupyter_code>from pyspedas import dscovr
dscovr.mag(trange=['2016-10-16', '2016-10-17'])<jupyter_output>01-May-20 10:38:09: Downloading remote index: https://spdf.sci.gsfc.nasa.gov/pub/data/dscovr/h0/mag/2016/
01-May-20 10:38:10: File is current: /Volumes/data/data/dscovr/h0/mag/2016/dscovr_h0_mag_20161016_v01.cdf<jupyter_text>and DSCOVR faraday cup data:<jupyter_code>dscovr.fc(trange=['2016-10-16', '2016-10-17'])
tplot(['B1GSE', 'V_GSE', 'Np'])<jupyter_output><empty_output><jupyter_text>Geotail To load some Geotail magnetometer data, and append a suffix to the variable names:<jupyter_code>pyspedas.geotail.mgf(trange=['2018-11-5/6:00', '2018-11-5/12:00'], suffix='_suffix', time_clip=True)
tplot(['IB_suffix', 'IB_vector_suffix'])<jupyter_output><empty_output><jupyter_text>and to load data from the Low Energy Particle experiment (LEP):<jupyter_code>lep_vars = pyspedas.geotail.lep(trange=['2018-11-5/8:00', '2018-11-5/9:00'], time_clip=True)
lep_vars
tplot(['N0', 'V0'])<jupyter_output><empty_output><jupyter_text>IMAGE MENATo load the energetic neutral atom images from the MENA instrument onboard IMAGE<jupyter_code>pyspedas.image.mena(trange=['2003-10-31', '2003-11-1'])<jupyter_output>01-May-20 10:41:50: Downloading remote index: https://spdf.sci.gsfc.nasa.gov/pub/data/image/mena/mena_k0/2003/
01-May-20 10:41:51: File is current: /Volumes/data/data/image/mena/mena_k0/2003/im_k0_mena_20031031_v01.cdf<jupyter_text>Plot the IMAGE spacecraft position<jupyter_code>tplot('gsm_pos')<jupyter_output><empty_output><jupyter_text>OMNI To load OMNI solar wind data (note: OMNI data are time-shifted to the magnetopause):<jupyter_code>pyspedas.omni.data(trange=['2013-11-5', '2013-11-6'])
tplot(['BX_GSE', 'BY_GSE', 'BZ_GSE', 'flow_speed', 'Vx', 'Vy', 'Vz', 'SYM_H'])<jupyter_output><empty_output><jupyter_text>Working with the data valuesYou can use get_data to extract the data values from the tplot variables:<jupyter_code>from pytplot import get_data
bx_times, bx_values = get_data('BX_GSE')<jupyter_output><empty_output><jupyter_text>Just as in IDL, times are stored as unix times<jupyter_code>bx_times
bx_values<jupyter_output><empty_output><jupyter_text>You can convert the unix times to strings using time_string<jupyter_code>from pyspedas import time_string
time_string(bx_times[0:5])<jupyter_output><empty_output><jupyter_text>You can convert the strings back to unix times using time_double<jupyter_code>from pyspedas import time_double
time_double(time_string(bx_times[0:5]))<jupyter_output><empty_output><jupyter_text>For energy spectra, the process is similar<jupyter_code>times, data, energies = get_data('mms1_des_energyspectr_omni_brst')<jupyter_output><empty_output><jupyter_text>note: burst mode FPI energy spectra are time varying<jupyter_code>energies<jupyter_output><empty_output><jupyter_text>Internally, pytplot variables are stored as xarray objectsIf you're familiar with xarray, you can access the underlying xarray object by setting `xarray=True`<jupyter_code>xr = get_data('mms1_des_energyspectr_omni_brst', xarray=True)
xr<jupyter_output><empty_output><jupyter_text>You can use store_data to create tplot variables<jupyter_code>from pytplot import store_data
store_data('bx_values', data={'x': bx_times, 'y': bx_values})
tplot('bx_values')<jupyter_output><empty_output><jupyter_text>You can use join_vec to join multiple tplot variables into a single tplot variable<jupyter_code>from pytplot import join_vec
join_vec(['BX_GSE', 'BY_GSE', 'BZ_GSE'], new_tvar='OMNI_B_GSE')
tplot('OMNI_B_GSE')<jupyter_output><empty_output><jupyter_text>You can use split_vec to split a vector variable into multiple tplot variables<jupyter_code>from pytplot import split_vec
split_vec('OMNI_B_GSE')
tplot(['OMNI_B_GSE_0', 'OMNI_B_GSE_1', 'OMNI_B_GSE_2'])<jupyter_output><empty_output><jupyter_text>Set the labels on a tplot variable<jupyter_code>options('OMNI_B_GSE', 'legend_names', ['Bx GSE', 'By GSE', 'Bz GSE'])
tplot('OMNI_B_GSE')<jupyter_output><empty_output><jupyter_text>To change the colors of the lines (note: the docs for the options are incorrect here)<jupyter_code>options('OMNI_B_GSE', 'Color', ['b', 'g', 'r'])
tplot('OMNI_B_GSE')<jupyter_output><empty_output><jupyter_text>To change the title on the Y axis<jupyter_code>options('OMNI_B_GSE', 'ytitle', 'OMNI B-field (nT)')
tplot('OMNI_B_GSE')<jupyter_output><empty_output><jupyter_text>You can change spectra back into line plots using the 'Spec' option<jupyter_code>options('mms1_des_energyspectr_omni_brst', 'Spec', False)
tplot('mms1_des_energyspectr_omni_brst')<jupyter_output>01-May-20 10:53:31: /Users/eric/anaconda3/lib/python3.7/site-packages/pyqtgraph/graphicsItems/PlotDataItem.py:533: RuntimeWarning: divide by zero encountered in log10
  y = np.log10(y)<jupyter_text>and convert it back to a spectra<jupyter_code>options('mms1_des_energyspectr_omni_brst', 'Spec', True)
tplot('mms1_des_energyspectr_omni_brst')<jupyter_output><empty_output><jupyter_text>You can also control ylog and zlog using options<jupyter_code>options('mms1_des_energyspectr_omni_brst', 'zlog', False)
tplot('mms1_des_energyspectr_omni_brst')<jupyter_output><empty_output><jupyter_text>Global plot options can be set with tplot_options<jupyter_code>from pytplot import tplot_options
help(tplot_options)
tplot_options('title', 'OMNI Bz and Flow Speed')
tplot(['BZ_GSM', 'flow_speed'])<jupyter_output><empty_output>
{'fraction_non_alphanumeric': 0.11295161079953045, 'fraction_numerical': 0.028368331811660364, 'mean_word_length': 5.779398762157383, 'pattern_counts': {'":': 0, '<': 168, '<?xml version=': 0, '>': 168, 'https://': 5, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 9, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'chain_length': '43', 'dir': 'jupyter-structured-clean-dedup', 'id': '160411', 'license': 'MIT', 'n_tokens_mistral': 5838, 'n_tokens_neox': 5471, 'n_words': 1319, 'path': 'pyspedas_examples/notebooks/pySPEDAS 1.0 tutorial - dry run (1 May 2020).ipynb', 'repo_name': 'spedas/pyspedas_examples', 'size': '15352'}