Merge pull request #102 from spedas/docs-updates

Docs updates

docs/source/ace.rst

@@ -19,6 +19,8 @@ Example
 .. image:: _static/ace_mfi.png
    :scale: 75 %
    :align: center
+   :class: imgborder
+
 
 Solar Wind Electron, Proton and Alpha Monitor (SWEPAM)
 --------------------------------------------------------
@@ -37,6 +39,8 @@ Example
 .. image:: _static/ace_swepam.png
    :scale: 75 %
    :align: center
+   :class: imgborder
+
 
 Electron, Proton, and Alpha-particle Monitor (EPAM)
 ----------------------------------------------------

docs/source/conf.py

@@ -33,7 +33,7 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx.ext.intersphinx']
 
 # Napoleon settings
 napoleon_numpy_docstring = True
@@ -47,7 +47,6 @@
 napoleon_use_param = False
 napoleon_use_rtype = True
 napoleon_preprocess_types = True
-
 napoleon_attr_annotations = True
 
 # Add any paths that contain templates here, relative to this directory.
@@ -74,3 +73,20 @@
 html_css_files = ['css/custom.css']
 
 autodoc_mock_imports = ['sip', 'PyQt5', 'PyQt5.QtGui', 'PyQt5.QtCore', 'PyQt5.QtWidgets']
+
+# Intersphinx generates automatic links to the documentation of objects
+# in other packages. When mappings are removed or added, please update
+# the section in docs/doc_guide.rst on references to other packages.
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy/reference/", None),
+    "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None),
+    "astropy": ("https://docs.astropy.org/en/stable/", None),
+    "pytplot": ("https://pytplot.readthedocs.io/en/latest/", None),
+    "sphinx_automodapi": (
+        "https://sphinx-automodapi.readthedocs.io/en/latest/",
+        None,
+    ),
+    "sphinx": ("https://www.sphinx-doc.org/en/master/", None),
+}

docs/source/getting_started.rst

@@ -1,13 +1,17 @@
 Getting Started
 ====================================
 
+pySPEDAS supports Windows, macOS and Linux. 
+
 Requirements
 --------------
 Python 3.7 or later is required.
 
+We recommend Anaconda, which comes with a suite of packages useful for scientific data analysis. Step-by-step instructions for installing Anaconda can be found at: `Windows <https://docs.anaconda.com/anaconda/install/windows/>`_, `macOS <https://docs.anaconda.com/anaconda/install/mac-os/>`_, `Linux <https://docs.anaconda.com/anaconda/install/linux/>`_
+
 Installation
 --------------
-pySPEDAS supports Windows, macOS and Linux. To get started, install the pyspedas package using PyPI:
+To get started, install the pyspedas package using PyPI:
 
 .. code-block:: bash
 
@@ -23,9 +27,9 @@ To upgrade to the latest version of pySPEDAS, include the '--upgrade' option whe
 
 Local Data Directories
 ------------------------
-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).
+By default, the data are stored in your pyspedas directory in a folder named 'pydata'. 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 for MMS, THM_DATA_DIR for THEMIS) can also be set, and these will override SPEDAS_DATA_DIR
+Mission specific data directories (e.g., **MMS_DATA_DIR** for MMS, **THM_DATA_DIR** for THEMIS) can also be set, and these will override **SPEDAS_DATA_DIR**.
 
 Loading and Plotting Data
 ---------------------------
@@ -47,4 +51,19 @@ To plot the tplot variables that were loaded, use tplot from pytplot, e.g.,
    tplot(['mms1_fgm_b_gse_srvy_l2_btot', 'mms1_fgm_b_gse_srvy_l2_bvec'])
 
 
+Accessing the Data and Timestamps
+-----------------------------------
+Once the data are loaded into tplot variables, you can access them using the get_data function from pytplot. e.g., 
+
+.. code-block:: python
+
+   from pytplot import get_data
+
+   mag_data = get_data('mms1_fgm_b_gse_srvy_l2_bvec')
+
+   # get_data returns a namedtuple with 'times' and 'y':
+   mag_data.times # the unix times, stored as a numpy array
+   mag_data.y # the data values
+
+Note: some types of data (spectrograms, DFs) have higher dimensions; e.g., spectra have a 'v' with the y-axis values for the data stored in 'y', and some data can have several dimensions: 'v1', 'v2', and 'v3'
 

docs/source/goes.rst

@@ -1,5 +1,5 @@
 Geostationary Operational Environmental Satellite (GOES)
-===================================================
+==========================================================
 The routines in this module can be used to load data from the GOES mission.
 
 Magnetometer (FGM)

docs/source/index.rst

@@ -8,11 +8,11 @@ pySPEDAS Documentation
 ====================================
 |build| |coverage| |version| |quality| |status| |license|
 
-pySPEDAS is an implementation of the SPEDAS framework for Python.
+pySPEDAS is an implementation of the Space Physics Environment Data Analysis Software (SPEDAS) framework in Python.
 
-The Space Physics Environment Data Analysis Software (SPEDAS) framework is written in IDL and contains data loading, data analysis and data plotting tools for various scientific missions (NASA, NOAA, etc.) and ground magnetometers.
+The SPEDAS framework is written in IDL and contains data loading, data analysis and data plotting tools for various scientific missions (NASA, NOAA, etc.) and ground magnetometers.
 
-pySPEDAS makes creating multi-mission, multi-instrument figures simple, e.g., to create a figure showing magnetometer data from Solar Orbiter, Parker Solar Probe, MMS, and THEMIS,
+pySPEDAS and `pyTplot <https://pytplot.readthedocs.io/>`_ make creating multi-mission, multi-instrument figures simple, e.g., to create a figure showing magnetometer data from `Solar Orbiter <https://pyspedas.readthedocs.io/en/latest/solo.html>`_, `Parker Solar Probe <https://pyspedas.readthedocs.io/en/latest/psp.html>`_, `MMS <https://pyspedas.readthedocs.io/en/latest/mms.html>`_, and `THEMIS <https://pyspedas.readthedocs.io/en/latest/themis.html>`_,
 
 .. code-block:: python
    

docs/source/mms.rst

@@ -24,6 +24,7 @@ FGM Example
 .. image:: _static/mms_fgm.png
    :scale: 75 %
    :align: center
+   :class: imgborder
 
 Search-coil Magnetometer (SCM)
 --------------------------------
@@ -42,6 +43,7 @@ SCM Example
 .. image:: _static/mms_scm.png
    :scale: 75 %
    :align: center
+   :class: imgborder
 
 Level 3 FGM+SCM Data (FSM)
 -----------------------------
@@ -54,12 +56,13 @@ FSM Example
    
    import pyspedas
    from pytplot import tplot
-   pyspedas.ace.mfi(trange=['2018-11-5', '2018-11-6'])
-   tplot(['BGSEc', 'Magnitude'])
+   pyspedas.mms.fsm(trange=['2015-10-16/13:06', '2015-10-16/13:07'], time_clip=True)
+   tplot(['mms1_fsm_b_mag_brst_l3', 'mms1_fsm_b_gse_brst_l3'])
 
 .. image:: _static/mms_fsm.png
    :scale: 75 %
    :align: center
+   :class: imgborder
 
 Electric field Double Probe (EDP)
 -----------------------------------
@@ -72,12 +75,13 @@ EDP Example
    
    import pyspedas
    from pytplot import tplot
-   pyspedas.ace.mfi(trange=['2018-11-5', '2018-11-6'])
-   tplot(['BGSEc', 'Magnitude'])
+   pyspedas.mms.edp(trange=['2015-10-16/13:06', '2015-10-16/13:07'], time_clip=True)
+   tplot('mms1_edp_dce_gse_fast_l2')
 
 .. image:: _static/mms_edp.png
    :scale: 75 %
    :align: center
+   :class: imgborder
 
 Electron Drift Instrument (EDI)
 ---------------------------------
@@ -90,12 +94,13 @@ EDI Example
    
    import pyspedas
    from pytplot import tplot
-   pyspedas.ace.mfi(trange=['2018-11-5', '2018-11-6'])
-   tplot(['BGSEc', 'Magnitude'])
+   pyspedas.mms.edi(trange=['2016-10-16/21:00', '2016-10-16/22:00'], time_clip=True)
+   tplot(['mms1_edi_vdrift_gse_srvy_l2', 'mms1_edi_e_gse_srvy_l2'])
 
 .. image:: _static/mms_edi.png
    :scale: 75 %
    :align: center
+   :class: imgborder
 
 Fly's Eye Energetic Particle Sensor (FEEPS)
 --------------------------------------------
@@ -108,12 +113,13 @@ FEEPS Example
    
    import pyspedas
    from pytplot import tplot
-   pyspedas.ace.mfi(trange=['2018-11-5', '2018-11-6'])
-   tplot(['BGSEc', 'Magnitude'])
+   pyspedas.mms.feeps(trange=['2015-10-16', '2015-10-17'])
+   tplot('mms1_epd_feeps_srvy_l2_electron_intensity_omni_spin')
 
 .. image:: _static/mms_feeps.png
    :scale: 75 %
    :align: center
+   :class: imgborder
 
 Energetic Ion Spectrometer (EIS)
 -----------------------------------
@@ -126,12 +132,13 @@ EIS Example
    
    import pyspedas
    from pytplot import tplot
-   pyspedas.ace.mfi(trange=['2018-11-5', '2018-11-6'])
-   tplot(['BGSEc', 'Magnitude'])
+   pyspedas.mms.eis(trange=['2015-10-16', '2015-10-17'])
+   tplot(['mms1_epd_eis_srvy_l2_extof_proton_flux_omni', 'mms1_epd_eis_srvy_l2_extof_proton_flux_omni_spin'])
 
 .. image:: _static/mms_eis.png
    :scale: 75 %
    :align: center
+   :class: imgborder
 
 Active Spacecraft Potential Control (ASPOC)
 --------------------------------------------
@@ -144,12 +151,13 @@ ASPOC Example
    
    import pyspedas
    from pytplot import tplot
-   pyspedas.ace.mfi(trange=['2018-11-5', '2018-11-6'])
-   tplot(['BGSEc', 'Magnitude'])
+   pyspedas.mms.aspoc(trange=['2015-10-16', '2015-10-17'])
+   tplot(['mms1_aspoc_ionc_l2', 'mms1_asp1_ionc_l2', 'mms1_asp2_ionc_l2'])
 
 .. image:: _static/mms_aspoc.png
    :scale: 75 %
    :align: center
+   :class: imgborder
 
 Fast Plasma Investigation (FPI)
 --------------------------------
@@ -162,12 +170,13 @@ FPI Example
    
    import pyspedas
    from pytplot import tplot
-   pyspedas.ace.mfi(trange=['2018-11-5', '2018-11-6'])
-   tplot(['BGSEc', 'Magnitude'])
+   pyspedas.mms.fpi(trange=['2015-10-16', '2015-10-17'], datatype='des-moms')
+   tplot(['mms1_des_energyspectr_omni_fast', 'mms1_des_bulkv_gse_fast', 'mms1_des_numberdensity_fast'])
 
 .. image:: _static/mms_fpi.png
    :scale: 75 %
    :align: center
+   :class: imgborder
 
 Hot Plasma Composition Analyzer (HPCA)
 ---------------------------------------
@@ -180,12 +189,13 @@ HPCA Example
    
    import pyspedas
    from pytplot import tplot
-   pyspedas.ace.mfi(trange=['2018-11-5', '2018-11-6'])
-   tplot(['BGSEc', 'Magnitude'])
+   pyspedas.mms.hpca(trange=['2015-10-16', '2015-10-17'], datatype='moments')
+   tplot(['mms1_hpca_hplus_number_density', 'mms1_hpca_hplus_ion_bulk_velocity', 'mms1_hpca_hplus_scalar_temperature'])
 
 .. image:: _static/mms_hpca.png
    :scale: 75 %
    :align: center
+   :class: imgborder
 
 Magnetic Ephemeris Coordinates (MEC)
 -------------------------------------
@@ -198,12 +208,13 @@ MEC Example
    
    import pyspedas
    from pytplot import tplot
-   pyspedas.ace.mfi(trange=['2018-11-5', '2018-11-6'])
-   tplot(['BGSEc', 'Magnitude'])
+   pyspedas.mms.mec(trange=['2015-10-16', '2015-10-17'])
+   tplot(['mms1_mec_r_gsm', 'mms1_mec_v_gsm'])
 
 .. image:: _static/mms_mec.png
    :scale: 75 %
    :align: center
+   :class: imgborder
 
 .. autofunction:: pyspedas.mms.state
 
@@ -214,9 +225,10 @@ State Example
    
    import pyspedas
    from pytplot import tplot
-   pyspedas.ace.mfi(trange=['2018-11-5', '2018-11-6'])
-   tplot(['BGSEc', 'Magnitude'])
+   pyspedas.mms.state(trange=['2020-12-16', '2020-12-17'])
+   tplot(['mms1_defeph_pos', 'mms1_defeph_vel'])
 
 .. image:: _static/mms_state.png
    :scale: 75 %
    :align: center
+   :class: imgborder