Added examples for rbspice_lib, updated the rest of the documentation

pyspedas/rbsp/__init__.py

@@ -34,7 +34,7 @@ def emfisis(trange=['2018-11-5', '2018-11-6'],
             ['YYYY-MM-DD/hh:mm:ss','YYYY-MM-DD/hh:mm:ss']
 
         probe : str or list of str, default='a'
-            Spacecraft probe name ('a' or 'b')
+            Spacecraft probe name: 'a' or 'b'
 
         datatype : str, default='magnetometer'
             Data type with options varying by data level.
@@ -150,13 +150,13 @@ def rbspice(trange=['2018-11-5', '2018-11-6'],
             ['YYYY-MM-DD/hh:mm:ss','YYYY-MM-DD/hh:mm:ss']
 
         probe : str or list of str, default='a'
-            Spacecraft probe name ('a' or 'b')
+            Spacecraft probe name: 'a' or 'b'
 
         datatype: str, default='TOFxEH'
             Data type; Valid options are specific to different data levels.
 
         level : str, default='l3'
-            Data level. Valid options: 'l1', 'l2', 'l3', 'l4'
+            Data level. Valid options: 'l1', 'l2', 'l3'
 
         suffix: str, optional
             The tplot variable names will be given this suffix.  By default, 
@@ -265,7 +265,7 @@ def efw(trange=['2015-11-5', '2015-11-6'],
             ['YYYY-MM-DD/hh:mm:ss','YYYY-MM-DD/hh:mm:ss']
 
         probe : str or list of str, default='a'
-            Spacecraft probe name ('a' or 'b')
+            Spacecraft probe name: 'a' or 'b'
 
         datatype : str, default='spec'
             Data type. Valid options are specific to different data levels.
@@ -340,7 +340,7 @@ def mageis(trange=['2015-11-5', '2015-11-6'],
             ['YYYY-MM-DD/hh:mm:ss','YYYY-MM-DD/hh:mm:ss']
 
         probe : str or list of str, default='a'
-            Spacecraft probe name ('a' or 'b')
+            Spacecraft probe name: 'a' or 'b'
 
         datatype : str, default=''
             Data type. Valid options are specific to different data levels.
@@ -418,7 +418,7 @@ def hope(trange=['2015-11-5', '2015-11-6'],
             ['YYYY-MM-DD/hh:mm:ss','YYYY-MM-DD/hh:mm:ss']
 
         probe : str or list of str, default='a'
-            Spacecraft probe name ('a' or 'b')
+            Spacecraft probe name: 'a' or 'b'
 
         datatype : str, default='moments'
             Data type. Valid options are specific to different data levels.
@@ -497,7 +497,7 @@ def rept(trange=['2015-11-5', '2015-11-6'],
             ['YYYY-MM-DD/hh:mm:ss','YYYY-MM-DD/hh:mm:ss']
 
         probe : str or list of str, default='a'
-            Spacecraft probe name ('a' or 'b')
+            Spacecraft probe name: 'a' or 'b'
 
         datatype : str, default=''
             Data type. Valid options are specific to different data levels.
@@ -575,7 +575,7 @@ def rps(trange=['2015-11-5', '2015-11-6'],
             ['YYYY-MM-DD/hh:mm:ss','YYYY-MM-DD/hh:mm:ss']
 
         probe : str or list of str, default='a'
-            Spacecraft probe name ('a' or 'b')
+            Spacecraft probe name: 'a' or 'b'
 
         datatype : str, default='rps-1min'
             Data type. Valid options are specific to different data levels.

pyspedas/rbsp/load.py

@@ -42,13 +42,13 @@ def load(trange=['2018-11-5', '2018-11-6'],
         ['YYYY-MM-DD/hh:mm:ss', 'YYYY-MM-DD/hh:mm:ss']. Default is ['2018-11-5', '2018-11-6'].
 
     probe : str or list of str, default='a'
-        Spacecraft probe name ('a' or 'b').
+        Spacecraft probe name: 'a' or 'b'
 
     instrument : str, default='emfisis'
         Name of the instrument.
 
     level : str, default='l3'
-        Data level (options: 'l1', 'l2', 'l3', 'l4').
+        Data level
 
     datatype : str, default='magnetometer'
         Instrument-specific data type.

pyspedas/rbsp/rbspice_lib/rbsp_load_rbspice_read.py

@@ -10,13 +10,23 @@ def rbsp_load_rbspice_read(level='l3', probe='a', datatype='TOFxEH'):
     
     Parameters
     ----------
-    level : str
-        data level ['l1','l2','l3' (default),'l3pap']
-    probe : str
-        RBSP spacecraft indicator [Options: 'a' (default), 'b']
-    datatype : str
-        RBSPICE data type ['EBR','ESRHELT','ESRLEHT','IBR','ISBR','ISRHELT','TOFxEH' (default),'TOFxEIon','TOFxEnonH','TOFxPHHHELT','TOFxPHHLEHT'],
+    level : str, default='l3'
+        data level 'l1','l2','l3'
+
+    probe : str or list of str, default='a'
+        Spacecraft probe name: 'a' or 'b'
+
+    datatype : str, default='TOFxEH'
+        RBSPICE data type: 'EBR','ESRHELT','ESRLEHT','IBR','ISBR','ISRHELT','TOFxEH' (default),'TOFxEIon','TOFxEnonH','TOFxPHHHELT','TOFxPHHLEHT'
         but change for different data levels.
+
+    Returns
+    -------
+    None
+
+    Examples
+    --------
+    This function is called within pyspedas.rbsp.rbspice
     """
     if level != 'l1':
         units_label = '1/(cm^2-sr-s-keV)'

pyspedas/rbsp/rbspice_lib/rbsp_rbspice_omni.py

@@ -18,17 +18,24 @@ def rbsp_rbspice_omni(probe='a', datatype='TOFxEH', level='l3'):
     
     Parameters
     ----------
-    probe : str
-        RBSP spacecraft indicator [Options: 'a' (default), 'b']
-    datatype : str
-        RBSPICE data type ['EBR','ESRHELT','ESRLEHT','IBR','ISBR','ISRHELT','TOFxEH' (default),'TOFxEIon','TOFxEnonH','TOFxPHHHELT','TOFxPHHLEHT'],
-        but change for different data levels.
-    level : str
-        data level ['l1','l2','l3' (default),'l3pap']
+    probe : str or list of str, default='a'
+        Spacecraft probe name: 'a' or 'b'
+
+    datatype: str, default='TOFxEH'
+        RBSPICE data type: 'EBR','ESRHELT','ESRLEHT','IBR','ISBR','ISRHELT','TOFxEH','TOFxEIon','TOFxEnonH','TOFxPHHHELT','TOFxPHHLEHT'
+        Values depends on different data levels.
+
+    level : str, default='l3'
+        data level: 'l1','l2','l3'
 
     Returns
     -------
-    Tplot variables created
+    out : list
+        Tplot variables created
+
+    Examples
+    --------
+    This function is called within pyspedas.rbsp.rbspice
     """
     if probe is None:
         probe = 'a'

pyspedas/rbsp/rbspice_lib/rbsp_rbspice_pad.py

@@ -19,22 +19,38 @@ def rbsp_rbspice_pad(probe='a', datatype='TOFxEH', level='l3', energy=[0, 1000],
     
     Parameters
     ----------
-    probe : str
-        RBSP spacecraft indicator [Options: 'a' (default), 'b']
-    datatype : str
-        desired data type [Options: 'TOFxEH' (default), 'TOFxEnonH']
-    level : str
-        data level ['l1','l2','l3' (default),'l3pap']
-    energy : list
-        user-defined energy range to include in the calculation in keV [default = [0,1000]]
-    bin_size : float
-        desired size of the pitch angle bins in degrees [default = 15]
-    scopes : list
+    probe : str or list of str, default='a'
+        Spacecraft probe name: 'a' or 'b'
+
+    datatype: str, default='TOFxEH'
+        desired data type: 'TOFxEH', 'TOFxEnonH'
+
+    level : str, default='l3'
+        data level: 'l1','l2','l3'
+
+    energy : list, default=[0,1000]
+        user-defined energy range to include in the calculation in keV
+
+    bin_size : float, default=15
+        desired size of the pitch angle bins in degrees
+
+    scopes : list, optional
         string array of telescopes to be included in PAD [0-5, default is all]
-    
+
     Returns
     -------
-    Tplot variables created
+    out : list
+        Tplot variables created
+
+    Examples
+    --------
+    >>> rbspice_vars = pyspedas.rbsp.rbspice(trange=['2018-11-5', '2018-11-6'], datatype='TOFxEH', level='l3')
+    >>> tplot('rbspa_rbspice_l3_TOFxEH_proton_omni_spin')
+
+    # Calculate the pitch angle distributions
+    >>> from pyspedas.rbsp.rbspice_lib.rbsp_rbspice_pad import rbsp_rbspice_pad
+    >>> rbsp_rbspice_pad(probe='a', datatype='TOFxEH', level='l3')
+    >>> tplot('rbspa_rbspice_l3_TOFxEH_proton_omni_0-1000keV_pad')
     """
     if datatype == 'TOFxEH':
         species = 'proton'

pyspedas/rbsp/rbspice_lib/rbsp_rbspice_pad_spinavg.py

@@ -14,28 +14,47 @@
 
 def rbsp_rbspice_pad_spinavg(probe='a', datatype='TOFxEH', level='l3', species=None, energy=[0, 1000], bin_size=15., scopes=None):
     """
-    Calculates spin-averaged PADs for the RBSPICE instrument
+    Calculates spin-averaged pitch angle distributions using data from the
+    RBSP Radiation Belt Storm Probes Ion Composition Experiment (RBSPICE)
     
-    Parameters
+        Parameters
     ----------
-    probe : str
-        RBSP spacecraft indicator [Options: 'a' (default), 'b']
-    datatype : str
-        desired data type [Options: 'TOFxEH' (default), 'TOFxEnonH']
-    level : str
-        data level ['l1','l2','l3' (default),'l3pap']
-    species : str
-        desired ion species [Options: 'proton' (default), 'helium', 'oxygen']
-    energy : list
-        user-defined energy range to include in the calculation in keV [default = [0,1000]]
-    bin_size : float
-        desired size of the pitch angle bins in degrees [default = 15]
-    scopes : list
+    probe : str or list of str, default='a'
+        Spacecraft probe name: 'a' or 'b'
+
+    datatype: str, default='TOFxEH'
+        desired data type: 'TOFxEH', 'TOFxEnonH'
+
+    level : str, default='l3'
+        data level: 'l1','l2','l3'
+
+    species : str, default='proton'
+        desired ion species: 'proton' , 'helium', 'oxygen'
+
+    energy : list, default=[0,1000]
+        user-defined energy range to include in the calculation in keV
+
+    bin_size : float, default = 15.
+        desired size of the pitch angle bins in degrees
+
+    scopes : list, optional
         string array of telescopes to be included in PAD [0-5, default is all]
 
+
     Returns
     --------
-    Tplot variables created
+    out : list
+        Tplot variables created
+
+    Examples
+    --------
+    >>> rbspice_vars = pyspedas.rbsp.rbspice(trange=['2018-11-5', '2018-11-6'], datatype='TOFxEH', level='l3')
+    >>> tplot('rbspa_rbspice_l3_TOFxEH_proton_omni_spin')
+
+    # Calculate the pitch angle distributions
+    >>> from pyspedas.rbsp.rbspice_lib.rbsp_rbspice_pad import rbsp_rbspice_pad_spinavg
+    >>> rbsp_rbspice_pad_spinavg(probe='a', datatype='TOFxEH', level='l3')
+    >>> tplot('rbspa_rbspice_l3_TOFxEH_proton_omni_0-1000keV_pad_spin')
     """
     if level != 'l1':
         units_label = '1/(cm^2-sr-s-keV)'

pyspedas/rbsp/rbspice_lib/rbsp_rbspice_spin_avg.py

@@ -18,16 +18,23 @@ def rbsp_rbspice_spin_avg(probe='a', datatype='TOFxEH', level='l3'):
     
     Parameters
     ----------
-    probe : str
-        RBSP spacecraft indicator [Options: 'a' (default), 'b']
-    datatype : str
-        RBSPICE data type ['TOFxEH' (default),'TOFxEnonH']
-    level : str
-        data level ['l1','l2','l3' (default),'l3pap']
+    probe : str or list of str, default='a'
+        Spacecraft probe name: 'a' or 'b'
+
+    datatype: str, default='TOFxEH'
+        desired data type: 'TOFxEH', 'TOFxEnonH'
+
+    level : str, default='l3'
+        data level: 'l1','l2','l3'
 
     Returns
     --------
-    Tplot variables created
+    out, list
+        Tplot variables created
+
+    Examples
+    --------
+    This function is called within pyspedas.rbsp.rbspice
     """
     if probe is None:
         probe = 'a'