Merge pull request #156 from sot/numpydocs

Convert docstrings to numpydocs format and add dark_model API docs

chandra_aca/aca_image.py

@@ -279,12 +279,18 @@ def centroid_fm(self, bgd=None, pix_zero_loc="center", norm_clip=None):
         Note that the returned ``norm`` is the sum of the background-subtracted 6x6
         mousebitten image, not the entire image.
 
-        :param bgd: background to subtract, scalar or NxN ndarray (float)
-        :param pix_zero_loc: row/col coords are integral at 'edge' or 'center'
-        :param norm_clip: clip image norm at this min value (default is None and
-                          implies Exception for non-positive norm)
-
-        :returns: row, col, norm float
+        Parameters
+        ----------
+        bgd
+            background to subtract, scalar or NxN ndarray (float)
+        pix_zero_loc
+            row/col coords are integral at 'edge' or 'center'
+        norm_clip : clip image norm at this min value (default is None and
+            implies Exception for non-positive norm)
+
+        Returns
+        -------
+        row, col, norm float
         """
         row, col, norm = centroid_fm(
             self, bgd=bgd, pix_zero_loc=pix_zero_loc, norm_clip=norm_clip
@@ -364,10 +370,14 @@ def flicker_init(self, flicker_mean_time=10000, flicker_scale=1.0, seed=None):
 
         The model was reviewed and approved at SS&AWG on 2019-05-22.
 
-        :param flicker_mean_time: mean flickering time (sec, default=10000)
-        :param flicker_scale: multiplicative factor beyond model default for
-               flickering amplitude (default=1.0)
-        :param seed: random seed for reproducibility (default=None => no seed)
+        Parameters
+        ----------
+        flicker_mean_time
+            mean flickering time (sec, default=10000)
+        flicker_scale : multiplicative factor beyond model default for
+            flickering amplitude (default=1.0)
+        seed
+            random seed for reproducibility (default=None => no seed)
         """
         if not hasattr(self, "flicker_cdf_bins"):
             self._read_flicker_cdfs()
@@ -424,8 +434,12 @@ def flicker_update(self, dt, use_numba=True):
         to use the numba-based version which is about 6 times faster.  The
         vectorized version is left in for reference.
 
-        :param dt: time (secs) to propagate image
-        :param use_numba: use the numba version of updating (default=True)
+        Parameters
+        ----------
+        dt
+            time (secs) to propagate image
+        use_numba
+            use the numba version of updating (default=True)
         """
         if not hasattr(self, "flicker_times"):
             self.flicker_init()
@@ -603,13 +617,20 @@ def centroid_fm(img, bgd=None, pix_zero_loc="center", norm_clip=None):
     (0.0, 0.0) at the center (for pix_zero_loc='center') or the lower-left edge
     (for pix_zero_loc='edge').
 
-    :param img: NxN ndarray
-    :param bgd: background to subtract, float of NXN ndarray
-    :param pix_zero_loc: row/col coords are integral at 'edge' or 'center'
-    :param norm_clip: clip image norm at this min value (default is None and
-                      implies Exception for non-positive norm)
-
-    :returns: row, col, norm float
+    Parameters
+    ----------
+    img
+        NxN ndarray
+    bgd
+        background to subtract, float of NXN ndarray
+    pix_zero_loc
+        row/col coords are integral at 'edge' or 'center'
+    norm_clip : clip image norm at this min value (default is None and
+        implies Exception for non-positive norm)
+
+    Returns
+    -------
+    row, col, norm float
     """
     # Cast to an ndarray (without copying)
     img = img.view(np.ndarray)
@@ -707,14 +728,24 @@ def get_psf_image(
         Get interpolated ACA PSF image that corresponds to pixel location
         ``row``, ``col``.
 
-        :param row: (float) row value of PSF centroid
-        :param col: (float) col value of PSF centroid
-        :param norm: (float) summed intensity of PSF image
-        :param pix_zero_loc: row/col coords are integral at 'edge' or 'center'
-        :param interpolation: 'nearest' | 'bilinear' (default)
-        :param aca_image: return ACAImage if True, else return ndarray
-
-        :returns: ACAImage if (aca_image is True) else (ndarray image, row0, col0)
+        Parameters
+        ----------
+        row
+            (float) row value of PSF centroid
+        col
+            (float) col value of PSF centroid
+        norm
+            (float) summed intensity of PSF image
+        pix_zero_loc
+            row/col coords are integral at 'edge' or 'center'
+        interpolation
+            'nearest' | 'bilinear' (default)
+        aca_image
+            return ACAImage if True, else return ndarray
+
+        Returns
+        -------
+        ACAImage if (aca_image is True) else (ndarray image, row0, col0)
         """
         drc = self.drc
 

chandra_aca/attitude.py

@@ -32,13 +32,20 @@ def calc_roll(yag, zag, yag_obs, zag_obs, sigma=None):
     star inputs then one can supply an array of sigma values corresponding
     to each star.
 
-    :param yag: reference yag (list or array)
-    :param zag: reference zag (list or array)
-    :param yag_obs: observed yag (list or array)
-    :param zag_obs: observed zag (list or array)
-
-    :returns: roll (deg)
-
+    Parameters
+    ----------
+    yag
+        reference yag (list or array)
+    zag
+        reference zag (list or array)
+    yag_obs
+        observed yag (list or array)
+    zag_obs
+        observed zag (list or array)
+
+    Returns
+    -------
+    roll (deg)
     """
     yag = np.asarray(yag)
     zag = np.asarray(zag)
@@ -80,14 +87,22 @@ def calc_roll_pitch_yaw(yag, zag, yag_obs, zag_obs, sigma=None):
     [[cos(th) -sin(th)], [sin(th), cos(th)]] to [[1, -th], [th, 1]].
     In practice anything below 1.0 degree is fine.
 
-    :param yag: reference yag (list or array, arcsec)
-    :param zag: reference zag (list or array, arcsec)
-    :param yag_obs: observed yag (list or array, arcsec)
-    :param zag_obs: observed zag (list or array, arcsec)
-    :param sigma: centroid uncertainties (None or list or array, arcsec)
-
-    :returns: roll, pitch, yaw (degrees)
-
+    Parameters
+    ----------
+    yag
+        reference yag (list or array, arcsec)
+    zag
+        reference zag (list or array, arcsec)
+    yag_obs
+        observed yag (list or array, arcsec)
+    zag_obs
+        observed zag (list or array, arcsec)
+    sigma
+        centroid uncertainties (None or list or array, arcsec)
+
+    Returns
+    -------
+    roll, pitch, yaw (degrees)
     """
     yag = np.array(yag)
     zag = np.array(zag)
@@ -208,15 +223,24 @@ def calc_att(att, yag, zag, yag_obs, zag_obs, sigma=None):
     [[cos(th) -sin(th)], [sin(th), cos(th)]] to [[1, -th], [th, 1]].
     In practice anything below 1.0 degree is fine.
 
-    :param att: reference attitude (Quat-compatible)
-    :param yag: reference yag (list or array, arcsec)
-    :param zag: reference zag (list or array, arcsec)
-    :param yag_obs: observed yag (list or array, arcsec)
-    :param zag_obs: observed zag (list or array, arcsec)
-    :param sigma: centroid uncertainties (None or list or array, arcsec)
-
-    :returns: Quat or list of Quat
-
+    Parameters
+    ----------
+    att
+        reference attitude (Quat-compatible)
+    yag
+        reference yag (list or array, arcsec)
+    zag
+        reference zag (list or array, arcsec)
+    yag_obs
+        observed yag (list or array, arcsec)
+    zag_obs
+        observed zag (list or array, arcsec)
+    sigma
+        centroid uncertainties (None or list or array, arcsec)
+
+    Returns
+    -------
+    Quat or list of Quat
     """
     from Quaternion import Quat
 

chandra_aca/centroid_resid.py

@@ -94,10 +94,16 @@ def set_centroids(self, source, slot, alg=8, apply_dt=True):
 
         yag, zag, yag_times an zag_times can also be set directly without use of this method.
 
-        :param source: 'ground' | 'obc'
-        :param slot: ACA slot
-        :param alg: for ground processing, use centroids from this algorithm.
-        :param apply_dt: apply centroid time offsets via 'set_offsets'
+        Parameters
+        ----------
+        source
+            'ground' | 'obc'
+        slot
+            ACA slot
+        alg
+            for ground processing, use centroids from this algorithm.
+        apply_dt
+            apply centroid time offsets via 'set_offsets'
         """
         self.centroid_source = source
         self.centroid_dt = None

chandra_aca/dark_model.py

@@ -74,11 +74,18 @@ def dark_temp_scale(t_ccd, t_ccd_ref=-19.0, scale_4c=None):
       >>> dark_temp_scale(t_ccd=-18, t_ccd_ref=-10, scale_4c=2.0)
       4.0
 
-    :param t_ccd: actual temperature (degC)
-    :param t_ccd_ref: reference temperature (degC, default=-19.0)
-    :param scale_4c: increase in dark current per 4 degC increase (default=1.0 / 0.7)
-
-    :returns: scale factor
+    Parameters
+    ----------
+    t_ccd
+        actual temperature (degC)
+    t_ccd_ref
+        reference temperature (degC, default=-19.0)
+    scale_4c
+        increase in dark current per 4 degC increase (default=1.0 / 0.7)
+
+    Returns
+    -------
+    scale factor
     """
     if scale_4c is None:
         scale_4c = DARK_SCALE_4C
@@ -90,10 +97,16 @@ def get_dark_hist(date, t_ccd):
     """
     Return the dark current histogram corresponding to ``date`` and ``t_ccd``.
 
-    :param date: date in any DateTime format
-    :param t_ccd: CCD temperature (deg C)
+    Parameters
+    ----------
+    date
+        date in any DateTime format
+    t_ccd
+        CCD temperature (deg C)
 
-    :returns: bin_centers, bins, darkhist
+    Returns
+    -------
+    bin_centers, bins, darkhist
     """
     pars = get_sbp_pars(date)
     x = darkbins.bin_centers
@@ -193,8 +206,14 @@ def get_sbp_pars(dates):
 
     This is only accurate for dates > 2007.0.
 
-    :param dates: one or a list of date(s) in DateTime compatible format
-    :returns: one or a list of parameter lists [g1, g2, g3, x_b, ampl]
+    Parameters
+    ----------
+    dates
+        one or a list of date(s) in DateTime compatible format
+
+    Returns
+    -------
+    one or a list of parameter lists [g1, g2, g3, x_b, ampl]
     """
     dates, is_scalar = as_array(dates)
 
@@ -231,10 +250,18 @@ def get_warm_fracs(warm_threshold, date="2013:001:12:00:00", T_ccd=-19.0):
     Calculate fraction of pixels in modeled dark current distribution
     above warm threshold(s).
 
-    :param warm_threshold: scalar or list of threshold(s) in e-/sec
-    :param date: date to use for modeled dark current distribution/histogram
-    :param T_ccd: temperature (C) of modeled dark current distribution
-    :returns: list or scalar of warm fractions (depends on warm_threshold type)
+    Parameters
+    ----------
+    warm_threshold
+        scalar or list of threshold(s) in e-/sec
+    date
+        date to use for modeled dark current distribution/histogram
+    T_ccd
+        temperature (C) of modeled dark current distribution
+
+    Returns
+    -------
+    list or scalar of warm fractions (depends on warm_threshold type)
     """
 
     x, xbins, y = get_dark_hist(date, T_ccd)
@@ -268,8 +295,12 @@ def synthetic_dark_image(date, t_ccd_ref=None):
     Generate a synthetic dark current image corresponding to the specified
     ``date`` and ``t_ccd``.
 
-    :param date: (DateTime compatible)
-    :param t_ccd_ref: ACA CCD temperature
+    Parameters
+    ----------
+    date
+        (DateTime compatible)
+    t_ccd_ref
+        ACA CCD temperature
     """
 
     from mica.archive.aca_dark import get_dark_cal_image