First pass at adding docstrings to everything

.gitignore

@@ -12,6 +12,8 @@ build
 dist
 gripspy.egg-info
 
+docs/_build
+
 *.swp
 *~
 

docs/code_ref/index.rst

@@ -7,6 +7,6 @@ Code reference for gripspy
 .. toctree::
    :maxdepth: 2
 
-   science
+   science/index.rst
    telemetry
    util

docs/code_ref/science/aspect.rst

@@ -0,0 +1,6 @@
+Aspect
+======
+
+.. automodule:: gripspy.science.aspect
+   :members:
+   :undoc-members:

docs/code_ref/science/bgo.rst

@@ -0,0 +1,6 @@
+BGO
+======
+
+.. automodule:: gripspy.science.bgo
+   :members:
+   :undoc-members:

docs/code_ref/science/ge.rst

@@ -0,0 +1,6 @@
+Ge
+======
+
+.. automodule:: gripspy.science.ge
+   :members:
+   :undoc-members:

docs/code_ref/science/index.rst

@@ -0,0 +1,8 @@
+Science
+=======
+
+.. toctree::
+
+   ge
+   bgo
+   aspect

docs/code_ref/telemetry.rst

@@ -1,6 +1,4 @@
 Telemetry
 =========
 
-.. automodule:: gripspy.telemetry
-   :members:
-   :undoc-members:
+.. autofunction:: gripspy.telemetry.parser_generator

docs/code_ref/util.rst

@@ -1,6 +1,10 @@
 Utilities
 =========
 
-.. automodule:: gripspy.util
+.. automodule:: gripspy.util.checksum
+   :members:
+   :undoc-members:
+
+.. automodule:: gripspy.util.coincidence
    :members:
    :undoc-members:

gripspy/__init__.py

@@ -1,3 +1,6 @@
+"""
+Python package for GRIPS data analysis
+"""
 from __future__ import absolute_import
 
 from . import science

gripspy/science/__init__.py

@@ -1,3 +1,6 @@
+"""
+Subpackage for working with GRIPS science data
+"""
 from __future__ import absolute_import
 
 from . import ge

gripspy/science/aspect.py

@@ -1,3 +1,6 @@
+"""
+Module for processing aspect data
+"""
 from __future__ import division, absolute_import, print_function
 
 from sys import stdout
@@ -17,6 +20,7 @@
 
 
 def _kernel(radius):
+    """The empirically chosen kernel to represent both the Sun and the fiducials."""
     axis = np.arange(-(radius * 2), radius * 2 + 1)
     x, y = np.meshgrid(axis, axis)
     template = 1 - np.cosh(np.sqrt(x**2 + y**2) * 5. / radius) / 200.
@@ -29,6 +33,18 @@ def _kernel(radius):
 
 
 class Frame(object):
+    """Base class for a camera frame
+
+    Parameters
+    ----------
+    filename : str
+        The name of the FITS file of the camera frame
+    uid : int
+        The UID of the camera to check for consistency with the camera frame.
+        The default of None means that consistency is not checked.
+    decimation_range : tuple of int
+        The allowable range of decimation levels.
+    """
     def __init__(self, filename, uid=None, decimation_range=(2, 10)):
         with fits.open(filename) as f:
             if uid != None and f[0].header['CAMERA'] != uid:
@@ -48,6 +64,21 @@ def __init__(self, filename, uid=None, decimation_range=(2, 10)):
             self.image = warp(self.data, transformation, output_shape=(NUM_ROWS, NUM_COLS))
 
     def _detect_decimation(self, decimation_range):
+        """Detects the decimation level of the camera frame.
+
+        Parameters
+        ----------
+        decimation_range : tuple of int
+            The inclusive range of decimation levels to check against the camera frame
+
+        Returns
+        -------
+        decimation_level : int
+            For a decimation_level of N, N-1 rows out of every N rows is empty
+        decimation_index : int
+            The index of the non-empty row for every decimation block
+            (i.e. strictly less than decimation_level)
+        """
         dead1 = (self.data == 0).sum(1) == NUM_COLS
         for step in range(decimation_range[0], decimation_range[1] + 1):
             sub_rows = NUM_ROWS // step
@@ -58,6 +89,7 @@ def _detect_decimation(self, decimation_range):
         return (1, 0)
 
     def plot_image(self, **kwargs):
+        """Plots the camera frame, defaulting to no interpolation."""
         imshow_args = {'cmap'   : 'gray',
                        'extent' : [-0.5, NUM_COLS - 0.5, NUM_ROWS - 0.5, -0.5],
                        'interpolation' : 'none'}
@@ -66,6 +98,15 @@ def plot_image(self, **kwargs):
 
 
 class PYFrame(Frame):
+    """Class for a pitch-yaw image
+
+    Parameters
+    ----------
+    filename : str
+        The name of the FITS file of the camera frame
+    uid : int
+        Defaults to the UID of the pitch-yaw camera, but can be set to a different camera's UID or to None
+    """
     def __init__(self, filename, uid=158434):
         try:
             Frame.__init__(self, filename, uid=uid)
@@ -75,6 +116,7 @@ def __init__(self, filename, uid=158434):
         self.peaks, self.fiducials = self._process()
 
     def _process(self):
+        """Finds the Suns and the fiducials."""
         # Perform a coarse search for Suns
         coarse_image = self.image[::10, ::10]
         coarse_match = match_template(coarse_image, template_sun[::10, ::10], pad_input=True)
@@ -113,6 +155,7 @@ def _process(self):
         return fine_peaks, fiducials
 
     def plot_image(self, **kwargs):
+        """Plots the pitch-yaw image, including Sun/fiducial detections."""
         if self.peaks:
             # Draw an X at the center of each Sun
             arr_peaks = np.array(self.peaks)
@@ -133,6 +176,15 @@ def plot_image(self, **kwargs):
 
 
 class RFrame(Frame):
+    """Class for a roll image
+
+    Parameters
+    ----------
+    filename : str
+        The name of the FITS file of roll image
+    uid : int
+        Defaults to the UID of the roll camera, but can be set to a different camera's UID or to None
+    """
     def __init__(self, filename, uid=142974):
         try:
             Frame.__init__(self, filename, uid=uid, decimation_range=(10, 10))
@@ -141,10 +193,18 @@ def __init__(self, filename, uid=142974):
 
 
 class FrameSequence(list):
+    """Base class for a sequence of camera frames"""
     pass
 
 
 class PYSequence(FrameSequence):
+    """Class for a sequence of pitch-yaw images
+
+    Parameters
+    ----------
+    list_of_files : list of str
+        List of FITS files with pitch-yaw images
+    """
     def __init__(self, list_of_files):
         FrameSequence.__init__(self)
 
@@ -155,6 +215,7 @@ def __init__(self, list_of_files):
         stdout.write("\n")
 
     def plot_centers(self, **kwargs):
+        """Plot the center of the brightest Sun across the entire image sequence"""
         time = []
         center_y = []
         center_x = []
@@ -168,6 +229,13 @@ def plot_centers(self, **kwargs):
 
 
 class RSequence(FrameSequence):
+    """Class for a sequence of roll images
+
+    Parameters
+    ----------
+    list_of_files : list of str
+        List of FITS files with roll images
+    """
     def __init__(self, list_of_files):
         FrameSequence.__init__(self)
 

gripspy/science/bgo.py

@@ -1,3 +1,6 @@
+"""
+Module for analyzing data from the BGO shields
+"""
 from __future__ import division, absolute_import, print_function
 
 import os
@@ -18,6 +21,19 @@
 
 
 class BGOEventData(object):
+    """Class for analyzing event data from the BGO shields
+
+    Parameters
+    ----------
+    telemetry_file : str
+        The name of the telemetry file to analyze.  If None is specified, a save file must be specified.
+    save_file : str
+        The name of a save file from a telemetry file that was previously parsed.
+
+    Notes
+    -----
+    `event_time` is stored in 10-ns steps
+    """
     def __init__(self, telemetry_file=None, save_file=None):
         if telemetry_file is not None:
             self.filename = telemetry_file
@@ -70,11 +86,11 @@ def save(self, save_file=None):
         ----------
         save_file : str
             The name of the save file to create.  If none is provided, the default is the name of
-            the telemetry file with the extension ".bgo.pgz" appended.
+            the telemetry file with the extension ".bgoe.pgz" appended.
 
         """
         if save_file is None:
-            save_file = self.filename + ".bgo.pgz"
+            save_file = self.filename + ".bgoe.pgz"
 
         with gzip.open(save_file, 'wb') as f:
             pickle.dump({'filename' : self.filename,
@@ -86,34 +102,50 @@ def save(self, save_file=None):
 
     @property
     def c(self):
+        """Shorthand for the `channel` attribute"""
         return self.channel
 
     @property
     def e(self):
+        """Shorthand for the `event_time` attribute"""
         return self.event_time
 
     @property
     def l(self):
+        """Shorthand for the `level` attribute"""
         return self.level
 
     @property
     def l0(self):
+        """Indices for the events of crossing threshold level 0"""
         return np.flatnonzero(self.level == 0)
 
     @property
     def l1(self):
+        """Indices for the events of crossing threshold level 1"""
         return np.flatnonzero(self.level == 1)
 
     @property
     def l2(self):
+        """Indices for the events of crossing threshold level 2"""
         return np.flatnonzero(self.level == 2)
 
     @property
     def l3(self):
+        """Indices for the events of crossing threshold level 3"""
         return np.flatnonzero(self.level == 3)
 
 
 class BGOCounterData(object):
+    """Class for analyzing event data from the BGO shields
+
+    Parameters
+    ----------
+    telemetry_file : str
+        The name of the telemetry file to analyze.  If None is specified, a save file must be specified.
+    save_file : str
+        The name of a save file from a telemetry file that was previously parsed.
+    """
     def __init__(self, telemetry_file=None, save_file=None):
         if telemetry_file is not None:
             self.filename = telemetry_file
@@ -166,11 +198,11 @@ def save(self, save_file=None):
         ----------
         save_file : str
             The name of the save file to create.  If none is provided, the default is the name of
-            the telemetry file with the extension ".bgo.pgz" appended.
+            the telemetry file with the extension ".bgoc.pgz" appended.
 
         """
         if save_file is None:
-            save_file = self.filename + ".bgc.pgz"
+            save_file = self.filename + ".bgoc.pgz"
 
         with gzip.open(save_file, 'wb') as f:
             pickle.dump({'filename' : self.filename,
@@ -182,20 +214,25 @@ def save(self, save_file=None):
 
     @property
     def t(self):
+        """Shorthand for the `counter_time` attribute"""
         return self.counter_time
 
     @property
     def tl(self):
+        """Shorthand for the `total_livetime` attribute"""
         return self.total_livetime
 
     @property
     def c(self):
+        """Shorthand for the `channel_count` attribute"""
         return self.channel_count
 
     @property
     def l(self):
+        """Shorthand for the `channel_livetime` attribute"""
         return self.channel_livetime
 
     @property
     def v(self):
+        """Shorthand for the `veto_count` attribute"""
         return self.veto_count