Misc docs updates

docs/getting_started/performance_tips.rst

@@ -31,14 +31,14 @@ is currently limited to input arrays with ``float64`` data types and
 Bottleneck acceleration is used internally by the following Photutils
 packages:
 
-* `~photutils.background` — background and background RMS estimation
+* `~photutils.background`: background and background RMS estimation
   (e.g., `~photutils.background.Background2D`)
-* `~photutils.detection` — source detection peak finding
-* `~photutils.profiles` — radial-profile and curve-of-growth
+* `~photutils.detection`: source detection peak finding
+* `~photutils.profiles`: radial-profile and curve-of-growth
   calculations
-* `~photutils.psf` — ePSF building
+* `~photutils.psf`: ePSF building
   (e.g., `~photutils.psf.EPSFBuilder`)
-* `~photutils.segmentation` — source detection and deblending
+* `~photutils.segmentation`: source detection and deblending
 
 To install Bottleneck::
 

docs/user_guide/aperture.rst

@@ -644,7 +644,7 @@ one of four values:
   Pixels belonging to neighboring sources (labeled, but not the target
   source) are excluded.
 * ``'source_only'``:
-  Only pixels belonging to the target source are included; both
+  Only pixels belonging to the target source are included. Both
   neighboring sources and background pixels are excluded.
 * ``'correct'``:
   Pixels belonging to neighboring sources are replaced by the values of
@@ -847,7 +847,7 @@ used, for example, to compute a sigma-clipped median of pixels in an
 annulus aperture to estimate the local background level. Sigma clipping
 is applied independently on the "center" and ``sum_method`` footprints
 described above, so the sum-related properties are also computed from
-sigma-clipped data; see :ref:`aperture_flags` for how this affects the
+sigma-clipped data. See :ref:`aperture_flags` for how this affects the
 ``flags`` property.
 
 Here is a simple example using a circular aperture at one position.

docs/user_guide/isophote.rst

@@ -6,7 +6,7 @@ Introduction
 
 The `~photutils.isophote` package provides tools to fit elliptical
 isophotes to a galaxy image.  The isophotes in the image are measured
-using an iterative method described by `Jedrzejewski (1987; MNRAS 226,
+using an iterative method described by `Jedrzejewski (1987, MNRAS 226,
 747)
 <https://ui.adsabs.harvard.edu/abs/1987MNRAS.226..747J/abstract>`_.
 See the documentation of the :class:`~photutils.isophote.Ellipse`

docs/user_guide/isophote_faq.rst

@@ -9,7 +9,7 @@ Isophote Frequently Asked Questions
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The basic elliptical isophote fitting algorithm, as described in
-`Jedrzejewski (1987; MNRAS 226, 747)
+`Jedrzejewski (1987, MNRAS 226, 747)
 <https://ui.adsabs.harvard.edu/abs/1987MNRAS.226..747J/abstract>`_,
 computes corrections for the current ellipse's geometrical parameters
 by essentially "projecting" the fitted harmonic amplitudes onto the
@@ -65,7 +65,7 @@ by the fitting algorithm. As can be seen from the above formulae,
 small :math:`I'` values lead to large values for the correction terms.
 Thus, :math:`I'` errors may lead to large fluctuations in these terms,
 when :math:`I'` itself is small.  This usually happens at the fainter,
-outer regions of galaxy images.  `Busko (1996; ASPC 101, 139)
+outer regions of galaxy images.  `Busko (1996, ASPC 101, 139)
 <https://ui.adsabs.harvard.edu/abs/1996ASPC..101..139B/abstract>`_
 found by numerical experiments that the precision to which a given
 ellipse can be fitted is related to the relative error in the local
@@ -124,7 +124,7 @@ computed by standard error propagation. Errors in the ellipse geometry
 parameters, on the other hand, cannot be estimated in the same way,
 since these parameters are not computed directly but result from a
 number of updates from a starting guess value. An error analysis based
-on numerical experiments (`Busko 1996; ASPC 101, 139
+on numerical experiments (`Busko 1996, ASPC 101, 139
 <https://ui.adsabs.harvard.edu/abs/1996ASPC..101..139B/abstract>`_)
 showed that the best error estimators for these geometrical parameters
 can be found by simply "projecting" the harmonic amplitude errors that
@@ -142,7 +142,7 @@ it produces sensible error estimators in practice.
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 When sampling is done using elliptical sectors (mean or median modes),
-the algorithm described in `Jedrzejewski (1987; MNRAS 226, 747)
+the algorithm described in `Jedrzejewski (1987, MNRAS 226, 747)
 <https://ui.adsabs.harvard.edu/abs/1987MNRAS.226..747J/abstract>`_
 uses an elaborate, high-precision scheme to take into account partial
 pixels that lie along elliptical sector boundaries. In the current

docs/user_guide/psf_matching.rst

@@ -10,12 +10,12 @@ The `photutils.psf_matching` subpackage contains tools to generate
 kernels for matching point spread functions (PSFs). It provides two
 functions for computing PSF-matching kernels in the Fourier domain:
 
-* :func:`~photutils.psf_matching.make_kernel` — Uses the ratio of
+* :func:`~photutils.psf_matching.make_kernel` uses the ratio of
   Fourier transforms with a hard amplitude threshold to regularize
-  the division (see e.g., `Gordon et al. 2008`_; `Aniano et al.
+  the division (see e.g., `Gordon et al. 2008`_ and `Aniano et al.
   2011`_).
 
-* :func:`~photutils.psf_matching.make_wiener_kernel` — Uses Wiener
+* :func:`~photutils.psf_matching.make_wiener_kernel` uses Wiener
   regularization, which smoothly suppresses noise amplification at
   spatial frequencies where the source response is weak.
 
@@ -307,8 +307,8 @@ The `Tukey window
 cosine taper. The ``alpha`` parameter controls the fraction of the array
 that is tapered: smaller ``alpha`` preserves more data but provides less
 artifact suppression, while larger ``alpha`` tapers more aggressively.
-When ``alpha=0`` it becomes a `~photutils.psf_matching.TopHatWindow`;
-when ``alpha=1`` it becomes a `~photutils.psf_matching.HanningWindow`.
+When ``alpha=0`` it becomes a `~photutils.psf_matching.TopHatWindow`.
+When ``alpha=1`` it becomes a `~photutils.psf_matching.HanningWindow`.
 This window provides a good balance and is a solid general-purpose
 choice.
 

photutils/aperture/_batch_outside.pyx

@@ -8,7 +8,7 @@ The outside-weight scan of the batch aperture photometry driver.
 is clipped by a data edge, whether the aperture has a nonzero-fraction
 pixel outside the data. The scan lives in its own extension module so
 that the per-shape pixel-overlap helpers of ``_batch_overlap.pxd``
-keep a single call site in the driver's translation unit: with more
+keep a single call site in the driver's translation unit. With more
 call sites the C compiler stops inlining the larger helpers into the
 driver's per-pixel loop, which measured up to 30% slower.
 
@@ -157,7 +157,7 @@ cdef bint outside_weight(const _ShapeSpec *sp, bint inside_any,
     enormous) bounding-box area.
 
     Otherwise every outside pixel is tested until one has a nonzero
-    fraction: the center and subpixel methods sample the shape at
+    fraction. The center and subpixel methods sample the shape at
     pixel or subpixel centers, for which the ring argument does not
     hold, and an aperture with no weight inside the data may lie
     entirely in the clipped-away part of its bounding box (that scan

photutils/aperture/_batch_overlap.pxd

@@ -148,15 +148,15 @@ cdef inline int _classify_seg_pixel(const Py_ssize_t *segmentation,
         One of the ``_SEG_*`` codes:
 
         * ``_SEG_SOURCE``: not a neighbor-source pixel (or the method
-          is disabled); the pixel contributes its own value
+          is disabled). The pixel contributes its own value
         * ``_SEG_EXCLUDED``: a background pixel excluded by method 2
           (not a neighbor-source pixel)
         * ``_SEG_NEIGHBOR``: a neighbor-source pixel excluded by method
           1 or 2
         * ``_SEG_CORRECTED``: a neighbor-source pixel replaced by the
           mirror pixel written to ``(siy[0], six[0])`` (method 3)
         * ``_SEG_UNCORRECTED``: a neighbor-source pixel whose mirror
-          pixel is unavailable (method 3); the pixel is excluded
+          pixel is unavailable (method 3). The pixel is excluded
     """
     cdef Py_ssize_t seg_val = segmentation[iy * nx_data + ix]
     cdef Py_ssize_t xm, ym, mseg
@@ -210,7 +210,7 @@ cdef inline bint _seg_pixel_contributes(const Py_ssize_t *segmentation,
     -------
     contributes : bint
         `True` if the pixel contributes to the measurement (reading its
-        value from ``(siy[0], six[0])``); `False` if it is excluded.
+        value from ``(siy[0], six[0])``) and `False` if it is excluded.
     """
     cdef int code = _classify_seg_pixel(segmentation, mask, nx_data,
                                         seg_method, label, ix, iy, ix0,
@@ -253,7 +253,7 @@ cdef inline bint _resolve_seg_pixel(const Py_ssize_t *segmentation,
     -------
     contributes : bint
         `True` if the pixel contributes to the aperture (reading its
-        value from ``(siy[0], six[0])``); `False` if it is excluded.
+        value from ``(siy[0], six[0])``) and `False` if it is excluded.
     """
     cdef int code = _classify_seg_pixel(segmentation, mask, nx_data,
                                         seg_method, label, ix, iy, ix0,
@@ -543,7 +543,7 @@ cdef inline double _circular_annulus_pixel_frac(double pxmin, double pymin,
     -------
     frac : double
         The fraction (0 to 1) of the pixel's area that overlaps the
-        annulus. The result is clamped at zero: an annulus overlap can
+        annulus. The result is clamped at zero. An annulus overlap can
         never be negative, but subtracting the inner overlap from the
         outer overlap can otherwise yield a tiny negative value from
         floating-point noise.
@@ -586,7 +586,7 @@ cdef inline double _ellipse_frac_core(double pxmin, double pymin,
     This is the shared core used by both ``_ellipse_pixel_frac`` and
     ``_elliptical_annulus_pixel_frac``, given the precomputed pixel
     center ``pxcen``/``pycen``. The caller is responsible for the
-    bounding-box check; none is performed here.
+    bounding-box check. None is performed here.
 
     Parameters
     ----------
@@ -629,7 +629,7 @@ cdef inline double _ellipse_frac_core(double pxmin, double pymin,
 
     # Quadratic-form coefficients and fast-path thresholds. These are
     # kept inline (rather than calling ``ellipse_quadratic_coeffs``) so
-    # they stay in registers in this per-pixel hot path; the shared
+    # they stay in registers in this per-pixel hot path. The shared
     # decision core ``ellipse_frac_from_rpix2`` does the fast path and
     # exact/subpixel dispatch.
     cxx = cos_theta * cos_theta * inv_rx2 + sin_theta * sin_theta * inv_ry2
@@ -893,8 +893,8 @@ cdef inline double _rect_pixel_frac(double pxmin, double pymin,
     ``theta`` (given as ``cos_theta``/``sin_theta``) and centered on
     the origin.
 
-    This replicates the per-pixel logic of ``rectangular_overlap_grid``:
-    the exact mode uses an interior/exterior fast path and skips pixels
+    This replicates the per-pixel logic of ``rectangular_overlap_grid``.
+    The exact mode uses an interior/exterior fast path and skips pixels
     outside the axis-aligned bounding box of the rotated rectangle, so
     the result is identical to the grid function.
 

photutils/aperture/_batch_photometry.pyx

@@ -405,8 +405,8 @@ def batch_aperture_sums(const double[:, ::1] data, const double[:, ::1] error,
     cdef double poly_x_out[4]
     cdef double poly_y_out[4]
 
-    # Scratch buffers for the polygon clipping (rectangular apertures);
-    # these are local to this call, so this function is thread safe.
+    # Scratch buffers for the polygon clipping (rectangular apertures).
+    # These are local to this call, so this function is thread safe.
     cdef double buf_a_x[32]
     cdef double buf_a_y[32]
     cdef double buf_b_x[32]
@@ -502,7 +502,7 @@ def batch_aperture_sums(const double[:, ::1] data, const double[:, ::1] error,
                 poly_x[pk] = params[2 * pk]
                 poly_y[pk] = params[2 * pk + 1]
 
-            # One-time convexity test; convex polygons use an
+            # One-time convexity test. Convex polygons use an
             # interior/exterior fast path in ``_polygon_pixel_frac``.
             is_poly_convex = convex_edge_normals(poly_x, poly_y, n_poly,
                                                  pedge_nx, pedge_ny, pedge_c)
@@ -567,7 +567,7 @@ def batch_aperture_sums(const double[:, ::1] data, const double[:, ::1] error,
 
     # Pass 1 (only when emitting the packed member buffers): size and
     # offset the packed buffers from the per-source clipped bounding-box
-    # areas. This performs only bounding-box arithmetic; it does not
+    # areas. This performs only bounding-box arithmetic. It does not
     # iterate over or evaluate individual pixels.
     if emit_sum:
         with nogil:
@@ -619,7 +619,7 @@ def batch_aperture_sums(const double[:, ::1] data, const double[:, ::1] error,
                     ccy = _round_half_away(cy)
 
             # Bounding box, overlap test, and pixel grid, replicated
-            # from the mask-based path (see ``_source_grid_setup``); the
+            # from the mask-based path (see ``_source_grid_setup``). The
             # sums stay NaN when there is no overlap.
             if not _source_grid_setup(cx, cy, ext_x, ext_y, off_x, off_y,
                                       nx_data, ny_data, &gxmin, &gymin,
@@ -658,7 +658,7 @@ def batch_aperture_sums(const double[:, ::1] data, const double[:, ::1] error,
                     pxmin = gxmin + (ix - ixmin) * dx
 
                     # The shape dispatch is inlined over the local
-                    # variables here; the outside-weight scan carries
+                    # variables here. The outside-weight scan carries
                     # the same dispatch in ``_batch_outside``, kept in
                     # a separate extension module so that each shape
                     # helper has a single call site in this one (see

photutils/aperture/_batch_stats.pyx

@@ -115,10 +115,10 @@ cdef void _heapsort(double *a, Py_ssize_t lo, Py_ssize_t hi) noexcept nogil:
 cdef void _introsort(double *a, Py_ssize_t lo, Py_ssize_t hi,
                      int depth) noexcept nogil:
     """
-    Sort ``a[lo:hi]`` ascending in place by introsort: median-of-three
-    quicksort with Bentley-McIlroy three-way partitioning, heapsort
-    when the recursion depth budget is exhausted, and insertion sort
-    for short ranges.
+    Sort ``a[lo:hi]`` ascending in place by introsort. This is a
+    median-of-three quicksort with Bentley-McIlroy three-way
+    partitioning, heapsort when the recursion depth budget is
+    exhausted, and insertion sort for short ranges.
 
     The three-way partition keeps the two scanning indices of a Hoare
     partition (so distinct keys sort as fast) but parks the elements
@@ -247,7 +247,7 @@ cdef inline void _sort_doubles(double *a, Py_ssize_t n) noexcept nogil:
     This replaces the C library ``qsort`` (whose comparison callback
     cannot be inlined and costs an indirect call per comparison) with
     an introsort whose comparisons compile to plain branches. The
-    values must be finite: the ordering of NaN values is unspecified.
+    values must be finite. The ordering of NaN values is unspecified.
     """
     cdef int depth = 0
     cdef Py_ssize_t m = n
@@ -303,7 +303,7 @@ cdef inline void _sigma_clip_bounds(double *s, double *work, Py_ssize_t n,
     Compute the converged sigma-clip bounds for one source.
 
     This reproduces `astropy.stats.SigmaClip` for the no-axis, no-grow
-    case: it iteratively narrows the kept range and returns the final
+    case. It iteratively narrows the kept range and returns the final
     lower and upper value bounds. A source survives the clip if its
     value ``v`` satisfies ``not (v < out_min) and not (v > out_max)``,
     so NaN bounds keep every value, matching astropy's degenerate
@@ -459,7 +459,7 @@ def batch_aperture_gather(const double[:, ::1] data,
 
     The "center" aperture mask method (``use_exact=0``, ``subpixels=1``)
     selects the unmasked pixel values used for the order and moment
-    statistics; each survivor is packed into a contiguous buffer. The
+    statistics. Each survivor is packed into a contiguous buffer. The
     ``sum_method`` aperture sum, error, and area are computed separately
     by `~photutils.aperture._batch_photometry.batch_aperture_sums`.
 
@@ -705,7 +705,7 @@ def batch_aperture_gather(const double[:, ::1] data,
     # Pass 1: size and offset the packed value buffer from the
     # per-source clipped bounding-box areas (an upper bound on the
     # number of "center"-method survivors). This performs only
-    # bounding-box arithmetic; it does not iterate over or evaluate
+    # bounding-box arithmetic. It does not iterate over or evaluate
     # individual pixels.
     with nogil:
         total = _presize_packed_offsets(positions, ext_x, ext_y, off_x, off_y,
@@ -842,7 +842,7 @@ def batch_aperture_gather(const double[:, ::1] data,
             # Whether the bounding box is clipped by a data edge. The
             # caller resolves this to the precise outside-weight test
             # (nonzero aperture weights outside the data) only for these
-            # sources; unclipped interior sources are exactly 0.
+            # sources. Unclipped interior sources are exactly 0.
             ixmax_full = <Py_ssize_t>ceil(cx + off_x + ext_x + 0.5)
             iymax_full = <Py_ssize_t>ceil(cy + off_y + ext_y + 0.5)
             if (ixmin < ix0 or ixmax_full > ix1
@@ -1296,7 +1296,7 @@ def batch_gini(const double[::1] values,
     ----------
     values : 1D ndarray of float64
         The packed pixel values (see ``batch_aperture_gather``). The
-        values need not be sorted; the absolute values are sorted
+        values need not be sorted. The absolute values are sorted
         internally.
 
     starts, counts : 1D ndarray of intp
@@ -1601,7 +1601,7 @@ cdef inline double _biweight_location_range(double *s, Py_ssize_t lo,
         The half-open index range of the values to use.
 
     anchor : double
-        The location anchor (``M``; the median if not input).
+        The location anchor ``M`` (the median if not input).
 
     c : double
         The tuning constant.
@@ -1652,7 +1652,7 @@ cdef inline double _biweight_midvar_range(double *s, Py_ssize_t lo,
         The half-open index range of the values to use.
 
     anchor : double
-        The location anchor (``M``; the median if not input).
+        The location anchor ``M`` (the median if not input).
 
     c : double
         The tuning constant.
@@ -1691,7 +1691,7 @@ def batch_sigma_clip_stats(double[:, ::1] sorted_data, double sigma_lower,
     Compute fused sigma-clipped statistics for each row of a 2D array.
 
     For each row, the finite values are sigma-clipped following
-    `astropy.stats.SigmaClip` (no-axis, no-grow case; see
+    `astropy.stats.SigmaClip` (no-axis, no-grow case, as in
     ``_sigma_clip_bounds``), and the mean, median, and population
     standard deviation of the surviving values are computed directly,
     without generating a clipped copy of the input. Optionally, the
@@ -1796,7 +1796,7 @@ def batch_sigma_clip_stats(double[:, ::1] sorted_data, double sigma_lower,
 
     with nogil:
         for k in range(n_rows):
-            # The finite values are s[0:n]; NaN values sort last
+            # The finite values are s[0:n] because NaN values sort last
             n = n_cols
             while n > 0:
                 v = sorted_data[k, n - 1]

photutils/aperture/_common.py

@@ -241,7 +241,7 @@ def batch_mask_plane(data, mask, *, mask_nonfinite):
     Build the uint8 mask plane used by the batch Cython kernels.
 
     Bit 1 (value 1) marks input-masked pixels and bit 2 (value 2) marks
-    non-finite ``data`` pixels; any nonzero value excludes the pixel.
+    non-finite ``data`` pixels. Any nonzero value excludes the pixel.
     Folding the non-finite pixels into the plane lets the caller exclude
     them from the sum, area, and valid-pixel count while still flagging
     them as ``non_finite_data`` rather than ``masked_pixels``.

photutils/aperture/circle.py

@@ -41,7 +41,7 @@ def _circular_polygon_offsets(r, n_vertices):
     using ``n_vertices`` equally spaced vertices.
 
     ``r`` may be a plain number (pixel offsets) or a
-    `~astropy.units.Quantity` (angular offsets); the returned offsets
+    `~astropy.units.Quantity` (angular offsets). The returned offsets
     carry the same type.
 
     Parameters