Merge pull request #1669 from larrybradley/docstring-fixes

Docstring fixes

photutils/background/background_2d.py

@@ -669,7 +669,7 @@ def plot_meshes(self, *, ax=None, marker='+', markersize=None,
             The marker to use to mark the center of the boxes.  Default
             is '+'.
 
-        markersize: float, optional
+        markersize : float, optional
             The marker size in points**2. The default is
             ``matplotlib.rcParams['lines.markersize'] ** 2``. If set to
             0, then the box center markers will not be plotted.

photutils/background/interpolators.py

@@ -34,7 +34,7 @@ class BkgZoomInterpolator:
 
     cval : float, optional
         The value used for points outside the boundaries of the input if
-        ``mode='constant'``. Default is 0.0
+        ``mode='constant'``. Default is 0.0.
 
     grid_mode : bool, optional
         If `True` (default), the samples are considered as the centers

photutils/detection/daofinder.py

@@ -299,7 +299,7 @@ class _DAOStarFinderCatalog:
     convolved_data : 2D `~numpy.ndarray`
         The convolved 2D image.
 
-    xypos: Nx2 `numpy.ndarray`
+    xypos : Nx2 `numpy.ndarray`
         A Nx2 array of (x, y) pixel coordinates denoting the central
         positions of the stars.
 
@@ -315,6 +315,8 @@ class _DAOStarFinderCatalog:
         calculate the source peak value, flux, and magnitude.  The
         default is 0.
 
+    References
+    ----------
     .. _DAOFIND: https://iraf.net/irafhelp.php?val=daofind
     """
 

photutils/detection/irafstarfinder.py

@@ -39,17 +39,17 @@ class IRAFStarFinder(StarFinderBase):
         The full-width half-maximum (FWHM) of the 2D circular Gaussian
         kernel in units of pixels.
 
+    sigma_radius : float, optional
+        The truncation radius of the Gaussian kernel in units of sigma
+        (standard deviation) [``1 sigma = FWHM /
+        2.0*sqrt(2.0*log(2.0))``].
+
     minsep_fwhm : float, optional
         The separation (in units of ``fwhm``) for detected objects. The
         minimum separation is calculated as ``int((fwhm * minsep_fwhm) +
         0.5)`` and is clipped to a minimum value of 2. Note that large
         values may result in long run times.
 
-    sigma_radius : float, optional
-        The truncation radius of the Gaussian kernel in units of sigma
-        (standard deviation) [``1 sigma = FWHM /
-        2.0*sqrt(2.0*log(2.0))``].
-
     sharplo : float, optional
         The lower bound on sharpness for object detection.
 
@@ -100,6 +100,10 @@ class IRAFStarFinder(StarFinderBase):
         overrides ``minsep_fwhm``. Note that large values may result in
         long run times.
 
+    See Also
+    --------
+    DAOStarFinder
+
     Notes
     -----
     For the convolution step, this routine sets pixels beyond the image
@@ -125,10 +129,6 @@ class IRAFStarFinder(StarFinderBase):
     * `~photutils.detection.IRAFStarFinder` calculates the objects'
       centroid, roundness, and sharpness using image moments.
 
-    See Also
-    --------
-    DAOStarFinder
-
     References
     ----------
     .. [1] https://iraf.net/irafhelp.php?val=starfind
@@ -277,7 +277,7 @@ class _IRAFStarFinderCatalog:
     convolved_data : 2D `~numpy.ndarray`
         The convolved 2D image.
 
-    xypos: Nx2 `numpy.ndarray`
+    xypos : Nx2 `numpy.ndarray`
         A Nx2 array of (x, y) pixel coordinates denoting the central
         positions of the stars.
 

photutils/detection/starfinder.py

@@ -55,16 +55,16 @@ class StarFinder(StarFinderBase):
             pixel values are negative. Therefore, setting ``peakmax`` to
             a non-positive value would result in excluding all objects.
 
+    See Also
+    --------
+    DAOStarFinder, IRAFStarFinder
+
     Notes
     -----
     For the convolution step, this routine sets pixels beyond the image
     borders to 0.0.
 
     The source properties are calculated using image moments.
-
-    See Also
-    --------
-    DAOStarFinder, IRAFStarFinder
     """
 
     def __init__(self, threshold, kernel, min_separation=5.0,
@@ -169,11 +169,11 @@ class _StarFinderCatalog:
     data : 2D `~numpy.ndarray`
         The 2D image.
 
-    xypos: Nx2 `numpy.ndarray`
+    xypos : Nx2 `numpy.ndarray`
         A Nx2 array of (x, y) pixel coordinates denoting the central
         positions of the stars.
 
-    shape:  tuple of int
+    shape :  tuple of int
         The shape of the stars cutouts. The shape in both dimensions
         must be odd and match the shape of the smoothing kernel.
     """

photutils/isophote/ellipse.py

@@ -49,7 +49,7 @@ class Ellipse:
         prematurely. Note that once the object centerer runs
         successfully, the (x, y) coordinates in the ``geometry``
         attribute (an `~photutils.isophote.EllipseGeometry` instance)
-        are modified in place.  The default is 0.1
+        are modified in place.  The default is 0.1.
 
     Notes
     -----

photutils/isophote/isophote.py

@@ -304,7 +304,7 @@ def _compute_errors(self):
         """
         Compute parameter errors based on the diagonal of the covariance
         matrix of the four harmonic coefficients for harmonics n=1 and
-        n=2.0
+        n=2.0.
         """
         try:
             coeffs, covariance = fit_first_and_second_harmonics(
@@ -760,6 +760,13 @@ def to_table(self, columns='main'):
         Convert an `~photutils.isophote.IsophoteList` instance to a
         `~astropy.table.QTable` with the main isophote parameters.
 
+        Parameters
+        ----------
+        columns : list of str
+            A list of properties to export from the isophote list. If
+            ``columns`` is 'all' or 'main', it will pick all or few of the
+            main properties.
+
         Returns
         -------
         result : `~astropy.table.QTable`
@@ -812,7 +819,7 @@ def _isophote_list_to_table(isophote_list, columns='main'):
         A list of isophotes.
 
     columns : list of str
-        A list of properties to export from the isophote_list. If
+        A list of properties to export from the ``isophote_list``. If
         ``columns`` is 'all' or 'main', it will pick all or few of the
         main properties.
 

photutils/isophote/sample.py

@@ -38,7 +38,7 @@ class EllipseSample:
         is 0.1.
     eps : float, optional
         The ellipticity of the ellipse.  The default is 0.2.
-    pa : float, optional
+    position_angle : float, optional
         The position angle of ellipse in relation to the positive x axis
         of the image array (rotating towards the positive y axis).  The
         default is 0.

photutils/psf/epsf.py

@@ -46,7 +46,7 @@ class EPSFFitter:
         must have odd values and be greater than or equal to 3 for both
         axes. If `None`, the fitter will use the entire star image.
 
-    fitter_kwargs : dict-like, optional
+    **fitter_kwargs : dict-like, optional
         Any additional keyword arguments (except ``x``, ``y``, ``z``, or
         ``weights``) to be passed directly to the ``__call__()`` method
         of the input ``fitter``.

photutils/psf/epsf_stars.py

@@ -276,7 +276,7 @@ class EPSFStars:
 
     Parameters
     ----------
-    star_list : list of `EPSFStar` or `LinkedEPSFStar` objects
+    stars_list : list of `EPSFStar` or `LinkedEPSFStar` objects
         A list of `EPSFStar` and/or `LinkedEPSFStar` objects.
     """
 
@@ -434,7 +434,7 @@ class LinkedEPSFStar(EPSFStars):
 
     Parameters
     ----------
-    star_list : list of `EPSFStar` objects
+    stars_list : list of `EPSFStar` objects
         A list of `EPSFStar` objects for the same physical star.  Each
         `EPSFStar` object must have a valid ``wcs_large`` attribute to
         convert between pixel and sky coordinates.

photutils/psf/griddedpsfmodel.py

@@ -76,7 +76,7 @@ def plot_grid(self, *, ax=None, vmax_scale=None, peak_norm=False,
             'gray_r' colormap for plotting the ePSF difference data
             (``deltas=True``).
 
-        show_dividers : bool, optional
+        dividers : bool, optional
             Whether to show divider lines between the ePSFs.
 
         divider_color, divider_ls : str, optional

photutils/psf/groupstars.py

@@ -78,15 +78,15 @@ class DAOGroup(GroupStarsBase):
         Distance, in units of pixels, such that any two stars separated by
         less than this distance will be placed in the same group.
 
+    See Also
+    --------
+    photutils.detection.DAOStarFinder
+
     Notes
     -----
     Assuming the psf fwhm to be known, ``crit_separation`` may be set to
     k*fwhm, for some positive real k.
 
-    See Also
-    --------
-    photutils.detection.DAOStarFinder
-
     References
     ----------
     [1] Stetson, Astronomical Society of the Pacific, Publications,
@@ -191,19 +191,14 @@ class DBSCANGroup(GroupStarsBase):
         by less than this distance will be placed in the same group.
     min_samples : int, optional (default=1)
         Minimum number of stars necessary to form a group.
-    metric : string or callable (default='euclidean')
+    metric : str or callable (default='euclidean')
         The metric to use when calculating distance between each pair of
         stars.
     algorithm : {'auto', 'ball_tree', 'kd_tree', 'brute'}, optional
         The algorithm to be used to actually find nearest neighbors.
     leaf_size : int, optional (default = 30)
         Leaf size passed to BallTree or cKDTree.
 
-    References
-    ----------
-    [1] Scikit Learn DBSCAN.
-        https://scikit-learn.org/stable/modules/generated/sklearn.cluster.DBSCAN.html#sklearn.cluster.DBSCAN
-
     Notes
     -----
     * The attribute ``crit_separation`` corresponds to ``eps`` in
@@ -216,6 +211,11 @@ class DBSCANGroup(GroupStarsBase):
       `photutils.psf.DBSCANGroup` when ``min_samples=1`` and
       ``metric=euclidean``.  Additionally, `photutils.psf.DBSCANGroup`
       may be faster than `photutils.psf.DAOGroup`.
+
+    References
+    ----------
+    [1] Scikit Learn DBSCAN.
+        https://scikit-learn.org/stable/modules/generated/sklearn.cluster.DBSCAN.html#sklearn.cluster.DBSCAN
     """
 
     def __init__(self, crit_separation, *, min_samples=1, metric='euclidean',

photutils/psf/models.py

@@ -189,9 +189,11 @@ def _compute_raw_image_norm(self):
     def _compute_normalization(self, normalize=True):
         r"""
         Helper function that computes (corrected) normalization factor
-        of the original image data. This quantity is computed as the
-        inverse "raw image norm" (or total "flux" of model's image)
-        corrected by the ``normalization_correction``:
+        of the original image data.
+
+        This quantity is computed as the inverse "raw image norm"
+        (or total "flux" of model's image) corrected by the
+        ``normalization_correction``:
 
         .. math::
             N = 1/(\Phi * C),
@@ -260,7 +262,9 @@ def normalization_constant(self):
     @property
     def normalization_status(self):
         """
-        Get normalization status. Possible status values are:
+        Get normalization status.
+
+        Possible status values are:
 
         - 0: **Performed**. Model has been successfully normalized at
              user's request.
@@ -364,6 +368,8 @@ def fill_value(self, fill_value):
 
     def _store_interpolator_kwargs(self, **kwargs):
         """
+        Store interpolator keyword arguments.
+
         This function should be called in a subclass whenever model's
         interpolator is (re-)computed.
         """
@@ -700,7 +706,7 @@ class IntegratedGaussianPRF(Fittable2DModel):
     sigma : float
         Width of the Gaussian PSF.
     flux : float, optional
-        Total integrated flux over the entire PSF
+        Total integrated flux over the entire PSF.
     x_0 : float, optional
         Position of the peak in x direction.
     y_0 : float, optional
@@ -774,7 +780,7 @@ class PRFAdapter(Fittable2DModel):
     Parameters
     ----------
     psfmodel : a 2D model
-        The model to assume as representative of the PSF
+        The model to assume as representative of the PSF.
     renormalize_psf : bool
         If True, the model will be integrated from -inf to inf and
         re-scaled so that the total integrates to 1.  Note that this

photutils/psf/utils.py

@@ -519,7 +519,9 @@ def get_grouped_psf_model(template_psf_model, star_group, pars_to_set):
 def _extract_psf_fitting_names(psf):
     """
     Determine the names of the x coordinate, y coordinate, and flux from
-    a model.  Returns (xname, yname, fluxname)
+    a model.
+
+    Returns (xname, yname, fluxname).
     """
     if hasattr(psf, 'xname'):
         xname = psf.xname
@@ -572,7 +574,7 @@ def subtract_psf(data, psf, posflux, *, subshape=None):
     Returns
     -------
     subdata : same shape and type as ``data``
-        The image with the PSF subtracted
+        The image with the PSF subtracted.
     """
     if data.ndim != 2:
         raise ValueError(f'{data.ndim}-d array not supported. Only 2-d '

photutils/segmentation/catalog.py

@@ -134,15 +134,6 @@ class SourceCatalog:
         values (NaN and inf) in the input ``data`` are automatically
         masked.
 
-
-        The 2D kernel used to filter the data prior to calculating
-        the source centroid and morphological parameters. The
-        kernel should be the same one used in defining the
-        source segments, i.e., the detection image (e.g., see
-        :func:`~photutils.segmentation.detect_sources`). If `None`, then
-        the unfiltered ``data`` will be used instead. This keyword is
-        ignored if ``convolved_data`` is input (recommended).
-
     background : float, 2D `~numpy.ndarray`, or `~astropy.units.Quantity`, optional
         The background level that was *previously* present in the input
         ``data``. ``background`` may either be a scalar value or a 2D
@@ -666,7 +657,7 @@ def remove_extra_properties(self, names):
 
         Parameters
         ----------
-        name : list of str
+        names : list of str
             The names of the properties to remove.
         """
         names = np.atleast_1d(names)
@@ -840,7 +831,8 @@ def _cutout_total_masks(self):
     @lazyproperty
     def _moment_data_cutouts(self):
         """
-        A list of 2D `~numpy.ndarray` cutouts from the (convolved) data
+        A list of 2D `~numpy.ndarray` cutouts from the (convolved) data.
+
         The following pixels are set to zero in these arrays:
 
             * pixels outside of the source segment

photutils/segmentation/core.py

@@ -1313,7 +1313,7 @@ def plot_patches(self, *, ax=None, origin=(0, 0), scale=1.0, labels=None,
         scale : float, optional
             The scale factor applied to the polygon vertices.
 
-        labels: int or array of int, optional
+        labels : int or array of int, optional
             The label numbers whose polygons are to be plotted. If
             `None`, the polygons for all labels will be plotted.
 
@@ -1480,7 +1480,7 @@ def imshow_map(self, ax=None, figsize=None, dpi=None, cmap=None,
             are applied pixel by pixel, and alpha must have the same
             shape as the segmentation image.
 
-        max_labels: int, optional
+        max_labels : int, optional
             The maximum number of labels to display in the colorbar. If
             the number of labels is greater than ``max_labels``, then
             the colorbar will not be displayed.

photutils/utils/_misc.py

@@ -41,7 +41,7 @@ def _get_date(utc=False):
 
     Parameters
     ----------
-    utz : bool, optional
+    utc : bool, optional
         Whether to use the UTC timezone instead of the local timezone.
 
     Returns