Merge pull request #100 from JuanCab/Further_doc_edits

Cleanup after second pass through stellarphot.io documentation.

stellarphot/__init__.py

@@ -17,6 +17,10 @@
 
 
 class UnsupportedPythonError(Exception):
+    """
+    Wraps an exception to raise if a user tries to use stellarphot
+    with an unsupported version of Python.
+    """
     pass
 
 

stellarphot/analysis/exotic.py

@@ -99,7 +99,7 @@ def make_checker(indicator_widget, value_widget):
     Parameters
     ----------
 
-    indicator_widget : MyCheck widget
+    indicator_widget : `~stellarphot.analysis.MyValid` widget
         The widget that indicates to the user whether or not the value is
         reasonable.
 
@@ -143,7 +143,7 @@ def validate_exposure_time(indicator_widget, value_widget):
 
     Parameters
     ----------
-    indicator_widget : `MyValid` widget
+    indicator_widget : `~stellarphot.analysis.MyValid` widget
         The widget that indicates to the user whether or not the value is
         reasonable.
 
@@ -219,10 +219,10 @@ def populate_TOI_boxes(toi, exotic_widget):
     Parameters
     ----------
 
-    toi : stellarphot.io.tess.TOI
+    toi : `~stellarphot.io.tess.TOI`
         Information about the TIC object.
 
-    exotic_widget: ipywidget
+    exotic_widget:  ipywidget
         This widget should be generated by exotic_settings_widget.
 
     Returns

stellarphot/analysis/transit_fitting.py

@@ -33,8 +33,10 @@
 
 class VariableArgsFitter(LevMarLSQFitter):
     """
-    A callable class that can be used to fit functions with arbitrary number of positional parameters.
-    This is a modified version of the astropy.modeling.fitting.LevMarLSQFitter fitter.
+    A callable class that can be used to fit functions with arbitrary number of
+    positional parameters.  This is a modified version of the
+    astropy.modeling.fitting.LevMarLSQFitter fitter.
+
     """
     def __init__(self):
         super().__init__()
@@ -89,56 +91,55 @@ def __call__(self, model, *args, weights=None,
 
 
 class TransitModelFit:
-    """Transit model fits to observed light curves.
-
-    Parameters
-    ----------
-    batman_params : batman.TransitParams
-        Parameters for the batman transit model. If not provided, the
-        default parameters will be used.
+    """
+    Transit model fits to observed light curves.
 
     Attributes
     ----------
-    times : array-like
-        Times at which the light curve is observed. Must be set before
-        fitting.
-
     airmass : array-like
         Airmass at each time. Must be set before fitting.
 
-    width : array-like
-        Width of the star in pixels at each time. Must be set before fitting.
-
-    spp : array-like
-        Sky per pixel at each time. Must be set before fitting.
+    BIC : float
+        Bayesian Information Criterion for the fit. This is calculated
+        after the fit is performed.
 
     data : array-like
         Observed fluxes. Must be set before fitting.
 
-    model : astropy.modeling.Model
+    model : `astropy.modeling.Model`
         The model used for fitting. This is a combination of the batman
         transit model and any other trends that are included in the fit.
         This is set up when the ``setup_model`` method is called.
 
+    n_fit_parameters : int
+        Number of parameters that were fit. This is calculated after the
+        fit is performed.
+
+    spp : array-like
+        Sky per pixel at each time. Must be set before fitting.
+
+    times : array-like
+        Times at which the light curve is observed. Must be set before
+        fitting.
+
+    width : array-like
+        Width of the star in pixels at each time. Must be set before fitting.
+
     weights : array-like
         Weights to use for fitting. If not provided, all weights are
         set to 1.
 
-    detrend_parameters : set
-        Set of parameters to detrend by. This is set when the ``airmass``,
-        ``width``, or ``spp`` attributes are set. If all three are set,
-        then all three are used for detrending. If ``None`` of them are
-        set, then no detrending is done.
-
-    BIC : float
-        Bayesian Information Criterion for the fit. This is calculated
-        after the fit is performed.
-
-    n_fit_parameters : int
-        Number of parameters that were fit. This is calculated after the
-        fit is performed.
     """
     def __init__(self, batman_params=None):
+        """
+        Initialize the transit model fit.
+
+        Parameters
+        ----------
+        batman_params : batman.TransitParams
+            Parameters for the batman transit model. If not provided, the
+            default parameters will be used.
+        """
         self._batman_params = batman.TransitParams()
         self._set_default_batman_params()
         self._times = None
@@ -486,6 +487,28 @@ def _detrend(self, model, detrend_by):
         return detrended
 
     def data_light_curve(self, data=None, detrend_by=None):
+        """
+        Function to return data light curve, optionally detrended by one or
+        more parameters.
+
+        Parameters
+        ----------
+
+        data : array-like, optional
+            Data to use for calculating the light curve. If not provided,
+            the data used for fitting will be used.
+
+        detrend_by : str or list of str
+            Parameter(s) to detrend by. If ``None``, no detrending is
+            done. If ``'all'``, all parameters that are set will be
+            used for detrending.
+
+        Returns
+        -------
+
+        data : array-like
+            Data light curve, detrended if requested.
+        """
         data = data if data is not None else self.data
 
         if detrend_by is not None:
@@ -497,18 +520,18 @@ def model_light_curve(self, at_times=None, detrend_by=None):
         """
         Calculate the light curve corresponding to the model, optionally
         detrended by one or more parameters.
-        
+
         Parameters
         ----------
         at_times : array-like
             Times at which to calculate the model. If not provided, the
             times used for fitting will be used.
-            
+
         detrend_by : str or list of str
             Parameter(s) to detrend by. If ``None``, no detrending is
             done. If ``'all'``, all parameters that are set will be
             used for detrending.
-            
+
         Returns
         -------
         model : array-like

stellarphot/core.py

@@ -7,23 +7,19 @@ class Camera:
     """
     A class to represent a CCD-based camera.
 
-    Parameters
+    Attributes
     ----------
+
     gain : `astropy.quantity.Quantity`
-        The gain of the camera in units such that the unit of the product `gain` times the image data matches the unit of the `read_noise`.
+        The gain of the camera in units such that the unit of the product
+        `gain` times the image data matches the unit of the `read_noise`.
+
     read_noise : `astropy.quantity.Quantity`
         The read noise of the camera in units of electrons.
-    dark_current : `astropy.quantity.Quantity`
-        The dark current of the camera in units such that, when multiplied by exposure time, the unit matches the unit of the `read_noise`.
 
-    Attributes
-    ----------
-    gain : float times u.electron / u.adu,
-        The gain of the camera in units of electrons per ADU.
-    read_noise : float times u.electron
-        The read noise of the camera in units of electrons.
-    dark_current : float times u.electron / u.second
-        The dark current of the camera in units of electrons per second.
+    dark_current : `astropy.quantity.Quantity`
+        The dark current of the camera in units such that, when multiplied
+        by exposure time, the unit matches the unit of the `read_noise`.
 
     Notes
     -----
@@ -48,6 +44,22 @@ class Camera:
     def __init__(self, gain=1.0 * u.electron / u.adu,
                  read_noise=1.0 * u.electron,
                  dark_current=0.01 * u.electron / u.second):
+        """
+        Initializes a Camera object instance.
+
+        Parameters
+        ----------
+        gain : `astropy.quantity.Quantity`
+            The gain of the camera in units such that the unit of the product `gain`
+            times the image data matches the unit of the `read_noise`.
+
+        read_noise : `astropy.quantity.Quantity`
+            The read noise of the camera in units of electrons.
+
+        dark_current : `astropy.quantity.Quantity`
+            The dark current of the camera in units such that, when multiplied by
+            exposure time, the unit matches the unit of the `read_noise`.
+        """
         super().__init__()
         self.gain = gain
         self.read_noise = read_noise

stellarphot/differential_photometry/aij_rel_fluxes.py

@@ -37,19 +37,19 @@ def calc_aij_relative_flux(star_data, comp_stars,
         the `star_data` and the position in the `comp_stars` table
         is too large.
 
-    in_place : ``bool``, optional
+    in_place : bool,  optional
         If ``True``, add new columns to input table. Otherwise, return
         new table with those columns added.
 
-    coord_column : ``str``, optional
+    coord_column : str,  optional
         If provided, use this column to match comparison stars to coordinates.
         If not provided, the coordinates are generated with SkyCoord.
 
-    flux_column_name : ``str``, optional
+    flux_column_name : str,  optional
         If provided, use this column to find flux.
         If not provided, the column 'aperture_net_flux' is used.
 
-    star_id_column : ``str``, optional
+    star_id_column : str,  optional
         Name of the column that provides a unique identifier for each
         comparison star.
 

stellarphot/differential_photometry/catalog_search.py

@@ -26,9 +26,9 @@ def in_frame(frame_wcs, coordinates, padding=0):
     Parameters
     ----------
 
-    frame_wcs : astropy WCS object
+    frame_wcs : `astropy.wcs.WCS`
         WCS for the image.
-    coordinates : astropy.coordinates.SkyCoord
+    coordinates : `astropy.coordinates.SkyCoord`
         Coordinate(s) whose position will be checked to see if they are in the
         field of view.
     padding : int, optional
@@ -39,7 +39,7 @@ def in_frame(frame_wcs, coordinates, padding=0):
     Returns
     -------
 
-    numpy.ndarray of bool
+    `numpy.ndarray` of bool
         One value for each input coordinate; values are ``True`` if the
         coordinate was in the field of view, ``False`` otherwise.
 
@@ -63,7 +63,7 @@ def catalog_search(frame_wcs_or_center, shape, desired_catalog,
     Parameters
     ----------
 
-    frame_wcs : astropy.wcs.WCS
+    frame_wcs : `astropy.wcs.WCS`
         WCS of the image of interest.
 
     shape : tuple of int
@@ -95,7 +95,7 @@ def catalog_search(frame_wcs_or_center, shape, desired_catalog,
     Returns
     -------
 
-    astropy.table.Table
+    `astropy.table.Table`
         Table of catalog information for stars in the field of view.
 
     """
@@ -133,10 +133,12 @@ def catalog_clean(catalog, remove_rows_with_mask=True,
     Parameters
     ----------
 
-    catalog : astropy.Table
+    catalog : `astropy.table.Table`
         Table of catalog information. There are no restrictions on the columns.
+
     remove_rows_with_mask : bool, optional
         If ``True``, remove rows in which one or more of the values is masked.
+
     other_restrictions: dict, optional
         Key/value pairs in which the key is the name of a column in the
         catalog and the value is the criteria that values in that column
@@ -147,7 +149,7 @@ def catalog_clean(catalog, remove_rows_with_mask=True,
     Returns
     -------
 
-    astropy.table.Table
+    `astropy.table.Table`
         Table of catalog information for stars in the field of view.
 
     """
@@ -191,7 +193,7 @@ def find_apass_stars(image_or_center,
     Get APASS data from Vizer.
 
     Parameters
-    ---------
+    ----------
 
     image_or_center : `astropy.nddata.CCDData` or `astropy.coordinates.SkyCoord`
         Either an image with a WCS (from which the RA/Dec will be extracted) or coordinate of
@@ -239,7 +241,8 @@ def find_apass_stars(image_or_center,
 
 
 def find_known_variables(image):
-    '''Get any known variable stars in image field from the VSX catalog.
+    """
+    Get any known variable stars in image field from the VSX catalog.
 
     Parameters
     ----------
@@ -252,7 +255,7 @@ def find_known_variables(image):
 
     vsx : `astropy.table.Table`
         Table of known variable stars in the field of view.
-    '''
+    """
     try:
         vsx = catalog_search(image.wcs, image.shape, 'B/vsx/vsx',
                              ra_column='RAJ2000', dec_column='DEJ2000')
@@ -270,7 +273,7 @@ def filter_catalog(catalog, **kwd):
     Parameters
     ----------
 
-    catalog : astropy Table
+    catalog : `astropy.table.Table`
         Table whose values are to be filtered.
 
     kwd : key/value pairs, e.g. ``e_r_mag=0.1``
@@ -280,7 +283,7 @@ def filter_catalog(catalog, **kwd):
     Returns
     -------
 
-    numpy.ndarray of bool
+    `numpy.ndarray` of bool
         One value for each row in the catalog; values are ``True`` if the
         row meets the criteria, ``False`` otherwise.
     """