Merge pull request #97 from JuanCab/Filling_Gaps

Extensive revisions to docstrings throughout the stellarphot package

.gitignore

@@ -51,6 +51,7 @@ distribute-*.tar.gz
 
 # Other
 .cache
+.nova
 .tox
 .*.sw[op]
 *~

CHANGES.rst

@@ -1,16 +1,20 @@
-1.1.5 (2023-05-31)
+1.3.9 (Unreleased)
 ------------------
 
 New Features
 ^^^^^^^^^^^^
 
 Other Changes and Additions
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
-+ Most functions are now linked to the documentation (some still need docstrings). [#92]
++ Old and redundant notebooks have been purged and bad references to `glowing-waffles` instead of `stellarphot` [#94]
++ Most functions are now linked to the documentation. [#90]
++ Many functions and classes that had missing documentation have now had docstrings added.
 
 Bug Fixes
 ^^^^^^^^^
-+ Runs without errors on current numpy (1.24.3) and astropy (5.3).
+
++ Runs without errors on release version of astrowidgets (0.3.0) [#93]
++ Runs without errors on current numpy (1.24.3) and astropy (5.3). [#92]
 
 
 1.1.2 (2022-10-18)
@@ -19,7 +23,6 @@ Bug Fixes
 New Features
 ^^^^^^^^^^^^
 
-
 Other Changes and Additions
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

stellarphot/analysis/exotic.py

@@ -40,7 +40,15 @@
 
 class MyValid(ipw.Button):
     """
-    A more compact indicator of valid entries.
+    A class containing a more compact indicator of valid entries based on ipywidgets
+    buton value.
+
+    Attributes
+    ----------
+
+    value : bool
+        Current value of the indicator.
+
     """
     value = Bool(False, help="Bool value").tag(sync=True)
 
@@ -69,6 +77,13 @@ def get_tic_info(TIC_ID):
 
     TIC_ID : int
         9 or 10 digit TIC ID number.
+
+    Returns
+    -------
+
+    `astropy.table.Table`
+        Astropy table withinformation about the TIC object.
+
     """
     catalog_data = Catalogs.query_criteria(catalog="Tic", ID=TIC_ID)
     return catalog_data
@@ -124,6 +139,24 @@ def check_name(change):
 
 
 def validate_exposure_time(indicator_widget, value_widget):
+    """ Validates the exposure time input.
+
+    Parameters
+    ----------
+    indicator_widget : `MyValid` widget
+        The widget that indicates to the user whether or not the value is
+        reasonable.
+
+    value_widget: ipywidget
+        This widget should be generated by exotic_settings_widget.
+
+    Returns
+    -------
+    function
+        Function that will set the correct boolean value on the
+        indicator_widget to indicate if the value of the exposure time
+        is valid.  This can be used as an observer for an ipywidget
+    """
     def check_exposure(change):
         # Valid Exposure time is greater than zero
         if change['new'] > 0:
@@ -139,6 +172,21 @@ def populate_TIC_boxes(tic_info, value_widget):
     """
     Set the appropriate widget values given information pulled from
     MAST TIC.
+
+    Parameters
+    ----------
+
+    tic_info : dict
+        Dictionary of information about the TIC object.
+
+    value_widget: ipywidget
+        This widget should contain a 'candidate' key.
+
+    Returns
+    -------
+
+    None
+        Sets values of planetary parameters of `candidate` in ``value_widget`` in place.
     """
     # Match EXOTIC json keys to columns in the result returned from
     # astroquery
@@ -167,6 +215,21 @@ def populate_TOI_boxes(toi, exotic_widget):
     """
     Set the appropriate widget values given information pulled from
     MAST TIC.
+
+    Parameters
+    ----------
+
+    toi : stellarphot.io.tess.TOI
+        Information about the TIC object.
+
+    exotic_widget: ipywidget
+        This widget should be generated by exotic_settings_widget.
+
+    Returns
+    -------
+
+    None
+        Sets values of planetary parameters of `candidate` in ``exotic_widget`` in place.
     """
     # Match EXOTIC json keys to columns in the result returned from
     # astroquery
@@ -210,6 +273,17 @@ def populate_TOI_boxes(toi, exotic_widget):
 def exotic_settings_widget():
     """
     Generate a widget to enter (and store) settings for exotic.
+
+    Parameters
+    ----------
+
+    None
+
+    Returns
+    -------
+
+    ipywidget
+        Widget with settings for EXOTIC.
     """
 
     # We rely on some global variables:
@@ -330,6 +404,11 @@ def set_values_from_json_file(widget, json_file):
 
     json_file : str
         File with settings for the widget.
+
+    Returns
+    -------
+    None
+        Sets values of parameters of widget in place.
     """
     with open(json_file) as f:
         input_values = json.load(f)
@@ -353,6 +432,13 @@ def get_values_from_widget(exotic_widget, key=None):
     key : str, either "known" or "candidate", optional
         Indicates which case to use for EXOTIC. If ``None``, use the ``planet_type``
         attribute of the ``exotic_widget``.
+
+    Returns
+    -------
+
+    dict
+        Value of modified template_json[key], where template_json is a global variable.
+
     """
     if not key:
         key = exotic_widget.planet_type.value
@@ -378,6 +464,10 @@ def generate_json_file_name(exotic_widget, key=None):
         Indicates which case to use for EXOTIC. If ``None``, use the ``planet_type``
         attribute of the ``exotic_widget``.
 
+    Returns
+    -------
+    str
+        Name of file to save settings to.
     """
     if not key:
         key = exotic_widget.planet_type.value

stellarphot/analysis/transit_fitting.py

@@ -33,8 +33,8 @@
 
 class VariableArgsFitter(LevMarLSQFitter):
     """
-    Allow fitting of functions with arbitrary number of positional
-    parameters.
+    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,6 +89,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.
+
+    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.
+
+    data : array-like
+        Observed fluxes. Must be set before fitting.
+
+    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.
+
+    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):
         self._batman_params = batman.TransitParams()
         self._set_default_batman_params()
@@ -309,12 +358,27 @@ def setup_model(self, t0=0, depth=0, duration=0,
         duration : float
             Duration of the transit,in the same units as ``t0`` and
             ``period``.
+
         period : float
             Period of the planet. Should be in the same units as ``t0``
             and times used for fitting.
 
         inclination : float
             Inclination of the orbit, in degrees.
+
+        airmass_trend : float, optional
+            Coefficient for a linear trend in airmass.
+
+        width_trend : float
+            Coefficient for a linear trend in stellar width.
+
+        spp_trend : float
+            Coefficient for a linear trend in sky per pixel.
+
+        Returns
+        -------
+        None
+            Sets values for the model parameters.
         """
         self._setup_transit_model()
 
@@ -433,6 +497,22 @@ 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
+            Model light curve.
         """
         zeros = np.zeros_like(self.times)
         airmass = self.airmass if self.airmass is not None else zeros

stellarphot/core.py

@@ -4,7 +4,47 @@
 
 
 class Camera:
-    """docstring for Camera"""
+    """
+    A class to represent a CCD-based camera.
+
+    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`.
+
+    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.
+
+    Notes
+    -----
+    The gain, read noise, and dark current are all assumed to be constant
+    across the entire CCD.
+
+    Examples
+    --------
+    >>> from astropy import units as u
+    >>> from stellarphot import Camera
+    >>> camera = Camera(gain=1.0 * u.electron / u.adu,
+    ...                 read_noise=1.0 * u.electron,
+    ...                 dark_current=0.01 * u.electron / u.second)
+    >>> camera.gain
+    <Quantity 1. electron / adu>
+    >>> camera.read_noise
+    <Quantity 1. electron>
+    >>> camera.dark_current
+    <Quantity 0.01 electron / s>
+
+    """
     def __init__(self, gain=1.0 * u.electron / u.adu,
                  read_noise=1.0 * u.electron,
                  dark_current=0.01 * u.electron / u.second):