added last few docstrings to functions, localized matplotlib import s…

…tatements to just functions that need it

dendrocat/aperture.py

@@ -130,21 +130,86 @@ def from_region(region):
         Parameters
         ----------
         region : astropy regions region
-            
+            The region from which to make the new aperture object.
         """
 
 
 class Ellipse(Aperture):
-     
+
     def __init__(self, center, major, minor, pa, unit=None, frame='icrs', name=None):
        Aperture.__init__(self, center, major, minor, pa, unit=unit, name=name)
+    """    
+        Create an elliptical aperture, defined in either pixel (x, y) or sky 
+        (ra, dec) coordinates.
+        
+        Parameters
+        ----------
+        center : list or tuple, as scalar or astropy.units.quantity.Quantity
+            x and y (ra and dec) coordinates for the center of the ellipse.
+        major : scalar or astropy.units.quantity.Quantity
+            Major axis of the ellipse (i.e., longest diameter)
+        minor : scalar or astropy.units.quantity.Quantity
+            Minor axis of the ellipse (i.e., shortest diameter)
+        pa : scalar or astropy.units.quantity.Quantity
+            If scalar, assumed to be given in degrees. The position angle of 
+            the major axis of the ellipse, measured from the positive x-axis
+            toward the positive y-axis. Defined in the range 0 < pa <= 180.
+        unit : astropy.unit.Unit or str
+            The unit in which all other arguments are specified. Usually u.pix
+            or u.deg.
+        frame : str, optional
+            The coordinate frame in which (ra, dec) coordinates are specified.
+            Default is 'icrs'.
+        name : str, optional
+            The name used in the catalog column names when photometry is 
+            performed with this aperture.
+    """
+
     def place(self, image, wcs=None):
+        """
+        Place the aperture on an image.
+        
+        Parameters
+        ----------
+        image : array
+            The image upon which to place the aperture.
+        wcs : astropy.wcs.wcs.WCS object, optional
+            The world coordinate system for the image, used for coordinate 
+            transformations.
+        
+        Returns
+        ----------
+        numpy.ndarray
+            A boolean mask for the aperture with the same dimensions as `image`
+        """
        return Aperture.place(self, image, wcs=wcs)
 
 
 class Annulus(Aperture):
 
     def __init__(self, center, inner, outer, unit=None, frame='icrs', name=None):
+    """    
+        Create an annular aperture, defined in either pixel (x, y) or sky 
+        (ra, dec) coordinates.
+        
+        Parameters
+        ----------
+        center : list or tuple, as scalar or astropy.units.quantity.Quantity
+            x and y (ra and dec) coordinates for the center of the ellipse.
+        inner : scalar or astropy.units.quantity.Quantity
+            Inner radius of the annulus.
+        outer : scalar or astropy.units.quantity.Quantity
+            Outer radius of the annulus.
+        unit : astropy.unit.Unit or str
+            The unit in which all other arguments are specified. Usually u.pix
+            or u.deg.
+        frame : str, optional
+            The coordinate frame in which (ra, dec) coordinates are specified.
+            Default is 'icrs'.
+        name : str, optional
+            The name used in the catalog column names when photometry is 
+            performed with this aperture.
+    """
         if unit is None:
             try:
                 unit = inner.unit
@@ -168,15 +233,67 @@ def __init__(self, center, inner, outer, unit=None, frame='icrs', name=None):
         self.outer = ucheck(outer, self.unit)
 
     def place(self, image, wcs=None):
+        """
+        Place the aperture on an image.
+        
+        Parameters
+        ----------
+        image : array
+            The image upon which to place the aperture.
+        wcs : astropy.wcs.wcs.WCS object, optional
+            The world coordinate system for the image, used for coordinate 
+            transformations.
+        
+        Returns
+        ----------
+        numpy.ndarray
+            A boolean mask for the aperture with the same dimensions as `image`
+        """
         return (self.aperture_outer.place(image, wcs=wcs)
                 ^ self.aperture_inner.place(image, wcs=wcs))
 
 
 class Circle(Aperture):
 
     def __init__(self, center, radius, unit=None, frame='icrs', name=None):
+        """    
+        Create a circular aperture, defined in either pixel (x, y) or sky 
+        (ra, dec) coordinates.
+        
+        Parameters
+        ----------
+        center : list or tuple, as scalar or astropy.units.quantity.Quantity
+            x and y (ra and dec) coordinates for the center of the ellipse.
+        radius : scalar or astropy.units.quantity.Quantity
+            Radius of the circle.
+        unit : astropy.unit.Unit or str
+            The unit in which all other arguments are specified. Usually u.pix
+            or u.deg.
+        frame : str, optional
+            The coordinate frame in which (ra, dec) coordinates are specified.
+            Default is 'icrs'.
+        name : str, optional
+            The name used in the catalog column names when photometry is 
+            performed with this aperture.
+    """
         Aperture.__init__(self, center, radius, radius, 0, unit=unit, name=name)
         self.radius = ucheck(radius, self.unit)
 
     def place(self, image, wcs=None):
+        """
+        Place the aperture on an image.
+        
+        Parameters
+        ----------
+        image : array
+            The image upon which to place the aperture.
+        wcs : astropy.wcs.wcs.WCS object, optional
+            The world coordinate system for the image, used for coordinate 
+            transformations.
+        
+        Returns
+        ----------
+        numpy.ndarray
+            A boolean mask for the aperture with the same dimensions as `image`
+        """
         return Aperture.place(self, image, wcs=wcs)

dendrocat/mastercatalog.py

@@ -3,9 +3,6 @@
 import numpy as np
 import astropy.units as u
 from copy import deepcopy
-import matplotlib.pyplot as plt
-import matplotlib.gridspec as gs
-import matplotlib.ticker
 from astropy.coordinates import SkyCoord, Angle
 
 if __package__ == '':
@@ -17,7 +14,6 @@
 class ApertureError(Exception):
     pass
 
-
 class MasterCatalog:
     """
     An object to store combined data from two or more RadioSource objects.
@@ -41,6 +37,19 @@ def __init__(self, *args, catalog=None):
 
 
     def grab(self, name, skip_rejects=False):
+        """
+        Grab a source or sources by name.
+
+        Parameters
+        ----------
+        name : str or list
+            String or list of strings to search the catalog "_name" header for.       
+        skip_rejects : bool, optional
+            If enabled, rejected sources will not be queried. Disabled by 
+            default.
+        """
+
+
         if skip_rejects:
             catalog = self.accepted
         else: 
@@ -59,6 +68,15 @@ def grab(self, name, skip_rejects=False):
 
 
     def add_objects(self, *args):
+        """
+        Add a new `~dendrocat.RadioSource` object to the existing master
+        catalog.
+        
+        Parameters
+        ----------
+        *args : '~dendrocat.RadioSource` objects
+            RadioSource objects to add to the master catalog.
+        """
         for obj in args:
             if isinstance(obj, MasterCatalog):
                 for key, value in obj.__dict__.items():
@@ -89,7 +107,10 @@ def photometer(self, *args, catalog=None):
         
         Parameters
         ----------
-        args : dendrocat.aperture
+        args : `~dendrocat.Aperture` objects
+            The apertures to use for photometry. Can be given as either 
+            instances or objects, to use fixed or variable aperture widths, 
+            respectively.
             
         catalog : astropy.table.Table object
             The catalog from which to extract source coordinates and ellipse
@@ -188,6 +209,40 @@ def photometer(self, *args, catalog=None):
     def ffplot(self, rsobj1, rsobj2, apertures=[], bkg_apertures=[], 
                alphas=None, peak=False, label=False, log=True, outfile=None):
 
+        """
+        Produce a flux-flux plot for two `~dendrocat.RadioSource` objects.
+        
+        Parameters
+        ----------
+        rsobj1 : `~dendrocat.RadioSource` object
+            One of two radio source objects from which to make a flux-flux 
+            plot.
+        rsobj2 : `~dendrocat.RadioSource` object
+            The other of two radio source objects from which to make a 
+            flux-flux plot.
+        apertures : list
+            List of `~dendrocat.Aperture` objects to use for source apertures.
+        bkg_apertures : list
+            List of `~dendrocat.Aperture` objects to use for background 
+            apertures.
+        alphas : list, optional
+            Spectral indices to overplot on top of the flux-flux data. 1, 2, 
+            and 3 will be used by default.
+        peak : bool, optional
+            If enabled, peak flux inside the aperture is used instead of 
+            aperture sum. Disabled by default.
+        label : bool, optional
+            If enabled, labels will be printed on the plot to identify sources.
+            Disabled by default.
+        log : bool, optional
+            If enabled, results will be shown on log-log axes. Enabled by 
+            default.
+        outfile : str, optional
+            If provided, output plot will be saved to this file path.
+        """
+
+        import matplotlib.pyplot as plt
+
         if type(apertures) != list:
             apertures = list([apertures])
 

dendrocat/radiosource.py

@@ -7,8 +7,6 @@
 from astropy.nddata.utils import Cutout2D, NoOverlapError
 from astropy.table import Column, Table, vstack
 from astrodendro import Dendrogram, pp_catalog
-import matplotlib.gridspec as gs
-import matplotlib.pyplot as plt
 import regions
 import pickle
 from copy import deepcopy
@@ -434,9 +432,11 @@ def get_snr(self, source=None, background=None, catalog=None, data=None,
         data: array-like
             Image data for the sources in the catalog.
         cutouts:
-            For developer use
+            For debugging. Provides a specific set of cutouts instead of 
+            letting the function generate them.
         cutout_data:
-            For developer use
+            For debugging. Provides a specific set of cutout data instead of 
+            letting the function generate it.
         peak : bool, optional
             Use peak flux of source pixels as 'signal'. Default is True.
         save : bool, optional
@@ -520,6 +520,9 @@ def plot_grid(self, catalog=None, data=None, cutouts=None, cutout_data=None,
             If enabled, don't plot rejected sources. Default is True.
         """
 
+        import matplotlib.gridspec as gs
+        import matplotlib.pyplot as plt
+
         if catalog is None:
             try:
                 catalog = self.catalog
@@ -729,6 +732,11 @@ def grab(self, name, skip_rejects=False):
     def dump(self, outfile):
         """
         Dump the `~dendrocat.RadioSource` object via pickle.
+
+        Parameters
+        ----------
+        outfile : str
+            Desired output file path.
         """
         outfile = outfile.split('.')[0]+'.pickle'
         with open(outfile, 'wb') as output:

dendrocat/utils.py

@@ -42,22 +42,46 @@ def get_index_masked(table):
 
 
 def specindex(nu1, nu2, f1, alpha):
-    return f1*(nu2/nu1)**(alpha) 
+    """
+    Calculate some flux given two wavelengths, one flux, and the spectral
+    index.
+    """
+    return f1*(nu2/nu1)**(alpha)
 
 def findrow(idx, catalog):
+    """
+    Find a specific row of a catalog by '_idx' number.
+    """
     idx = int(idx)
     return catalog[np.where(catalog['_idx'] == idx)]
 
 def rms(x):
+    """
+    Calculate the root mean squared of some x.
+    """
     return (np.absolute(np.mean(x**2) - (np.mean(x))**2))**0.5
 
 def load(infile):
+    """
+    Load a pickle file.
+    """
     filename = infile.split('.')[0]+'.pickle'
     with open(filename, 'rb') as f:
         return pickle.load(f)
 
 def ucheck(quantity, unit):
+    """
+    Check if a quantity already has units, and attempt conversion if so.
 
+    Parameters
+    ----------
+    quantity : scalar, array, or `~astropy.units.Unit`
+        The quantity to check for units. If scalar, units will assumed to be
+        the same as in the "unit" argument.
+    unit : `~astropy.units.Unit`
+        The unit to check against. If the "quantity" argument already has an
+        associated unit, a conversion will be attempted.
+    """
     if isinstance(quantity, Column):
         name = quantity.name
         if quantity.unit is None: