Merge pull request #1990 from larrybradley/starfinder-peakmax

Starfinder peakmax

CHANGES.rst

@@ -65,6 +65,10 @@ API Changes
     and ``peakmax``) are now included in the returned table of detected
     sources by ``DAOStarFinder`` and ``IRAFStarFinder``. [#1978]
 
+  - Detected sources that match the maximum peak value (``peakmax``)
+    are now included in the returned table of detected sources by
+    ``StarFinder``. [#1990]
+
 - ``photutils.morphology``
 
   - The ``gini`` function now returns zero instead of NaN if the

photutils/detection/daofinder.py

@@ -86,16 +86,20 @@ class DAOStarFinder(StarFinderBase):
         (2.0*sqrt(2.0*log(2.0)))``].
 
     sharplo : float, optional
-        The lower bound on sharpness for object detection.
+        The lower bound on sharpness for object detection. Objects
+        with sharpness less than ``sharplo`` will be rejected.
 
     sharphi : float, optional
-        The upper bound on sharpness for object detection.
+        The upper bound on sharpness for object detection. Objects
+        with sharpness greater than ``sharphi`` will be rejected.
 
     roundlo : float, optional
-        The lower bound on roundness for object detection.
+        The lower bound on roundness for object detection. Objects
+        with roundness less than ``roundlo`` will be rejected.
 
     roundhi : float, optional
-        The upper bound on roundness for object detection.
+        The upper bound on roundness for object detection. Objects
+        with roundness greater than ``roundhi`` will be rejected.
 
     exclude_border : bool, optional
         Set to `True` to exclude sources found within half the size of
@@ -108,13 +112,13 @@ class DAOStarFinder(StarFinderBase):
         will be selected.
 
     peakmax : float, None, optional
-        The maximum allowed peak pixel value in an object. Only objects
-        whose peak pixel values are strictly smaller than ``peakmax``
-        will be selected. This may be used, for example, to exclude
-        saturated sources. If the star finder is run on an image that is
-        a `~astropy.units.Quantity` array, then ``peakmax`` must have
-        the same units. If ``peakmax`` is set to `None`, then no peak
-        pixel value filtering will be performed.
+        The maximum allowed peak pixel value in an object. Objects with
+        peak pixel values greater than ``peakmax`` will be rejected.
+        This keyword may be used, for example, to exclude saturated
+        sources. If the star finder is run on an image that is a
+        `~astropy.units.Quantity` array, then ``peakmax`` must have the
+        same units. If ``peakmax`` is set to `None`, then no peak pixel
+        value filtering will be performed.
 
     xycoords : `None` or Nx2 `~numpy.ndarray`, optional
         The (x, y) pixel coordinates of the approximate centroid
@@ -318,30 +322,34 @@ class _DAOStarFinderCatalog:
         to create the ``convolved_data``.
 
     sharplo : float, optional
-        The lower bound on sharpness for object detection.
+        The lower bound on sharpness for object detection. Objects
+        with sharpness less than ``sharplo`` will be rejected.
 
     sharphi : float, optional
-        The upper bound on sharpness for object detection.
+        The upper bound on sharpness for object detection. Objects
+        with sharpness greater than ``sharphi`` will be rejected.
 
     roundlo : float, optional
-        The lower bound on roundness for object detection.
+        The lower bound on roundness for object detection. Objects
+        with roundness less than ``roundlo`` will be rejected.
 
     roundhi : float, optional
-        The upper bound on roundness for object detection.
+        The upper bound on roundness for object detection. Objects
+        with roundness greater than ``roundhi`` will be rejected.
 
     brightest : int, None, optional
         The number of brightest objects to keep after sorting the source
         list by flux. If ``brightest`` is set to `None`, all objects
         will be selected.
 
     peakmax : float, None, optional
-        The maximum allowed peak pixel value in an object. Only objects
-        whose peak pixel values are strictly smaller than ``peakmax``
-        will be selected. This may be used, for example, to exclude
-        saturated sources. If the star finder is run on an image that is
-        a `~astropy.units.Quantity` array, then ``peakmax`` must have
-        the same units. If ``peakmax`` is set to `None`, then no peak
-        pixel value filtering will be performed.
+        The maximum allowed peak pixel value in an object. Objects with
+        peak pixel values greater than ``peakmax`` will be rejected.
+        This keyword may be used, for example, to exclude saturated
+        sources. If the star finder is run on an image that is a
+        `~astropy.units.Quantity` array, then ``peakmax`` must have the
+        same units. If ``peakmax`` is set to `None`, then no peak pixel
+        value filtering will be performed.
     """
 
     def __init__(self, data, convolved_data, xypos, threshold, kernel, *,
@@ -738,7 +746,8 @@ def apply_filters(self):
             warnings.warn('No sources were found.', NoDetectionsWarning)
             return None
 
-        # filter based on sharpness, roundness, and peakmax
+        # keep sources that are within the sharpness, roundness, and
+        # peakmax (inclusive) bounds
         mask = ((newcat.sharpness >= newcat.sharplo)
                 & (newcat.sharpness <= newcat.sharphi)
                 & (newcat.roundness1 >= newcat.roundlo)

photutils/detection/irafstarfinder.py

@@ -57,16 +57,20 @@ class IRAFStarFinder(StarFinderBase):
         values may result in long run times.
 
     sharplo : float, optional
-        The lower bound on sharpness for object detection.
+        The lower bound on sharpness for object detection. Objects
+        with sharpness less than ``sharplo`` will be rejected.
 
     sharphi : float, optional
-        The upper bound on sharpness for object detection.
+        The upper bound on sharpness for object detection. Objects
+        with sharpness greater than ``sharphi`` will be rejected.
 
     roundlo : float, optional
-        The lower bound on roundness for object detection.
+        The lower bound on roundness for object detection. Objects
+        with roundness less than ``roundlo`` will be rejected.
 
     roundhi : float, optional
-        The upper bound on roundness for object detection.
+        The upper bound on roundness for object detection. Objects
+        with roundness greater than ``roundhi`` will be rejected.
 
     exclude_border : bool, optional
         Set to `True` to exclude sources found within half the size of
@@ -79,13 +83,13 @@ class IRAFStarFinder(StarFinderBase):
         will be selected.
 
     peakmax : float, None, optional
-        The maximum allowed peak pixel value in an object. Only objects
-        whose peak pixel values are strictly smaller than ``peakmax``
-        will be selected. This may be used, for example, to exclude
-        saturated sources. If the star finder is run on an image that is
-        a `~astropy.units.Quantity` array, then ``peakmax`` must have
-        the same units. If ``peakmax`` is set to `None`, then no peak
-        pixel value filtering will be performed.
+        The maximum allowed peak pixel value in an object. Objects with
+        peak pixel values greater than ``peakmax`` will be rejected.
+        This keyword may be used, for example, to exclude saturated
+        sources. If the star finder is run on an image that is a
+        `~astropy.units.Quantity` array, then ``peakmax`` must have the
+        same units. If ``peakmax`` is set to `None`, then no peak pixel
+        value filtering will be performed.
 
     xycoords : `None` or Nx2 `~numpy.ndarray`, optional
         The (x, y) pixel coordinates of the approximate centroid
@@ -283,30 +287,34 @@ class _IRAFStarFinderCatalog:
         to create the ``convolved_data``.
 
     sharplo : float, optional
-        The lower bound on sharpness for object detection.
+        The lower bound on sharpness for object detection. Objects
+        with sharpness less than ``sharplo`` will be rejected.
 
     sharphi : float, optional
-        The upper bound on sharpness for object detection.
+        The upper bound on sharpness for object detection. Objects
+        with sharpness greater than ``sharphi`` will be rejected.
 
     roundlo : float, optional
-        The lower bound on roundness for object detection.
+        The lower bound on roundness for object detection. Objects
+        with roundness less than ``roundlo`` will be rejected.
 
     roundhi : float, optional
-        The upper bound on roundness for object detection.
+        The upper bound on roundness for object detection. Objects
+        with roundness greater than ``roundhi`` will be rejected.
 
     brightest : int, None, optional
         The number of brightest objects to keep after sorting the source
         list by flux. If ``brightest`` is set to `None`, all objects
         will be selected.
 
     peakmax : float, None, optional
-        The maximum allowed peak pixel value in an object. Only objects
-        whose peak pixel values are strictly smaller than ``peakmax``
-        will be selected. This may be used, for example, to exclude
-        saturated sources. If the star finder is run on an image that is
-        a `~astropy.units.Quantity` array, then ``peakmax`` must have
-        the same units. If ``peakmax`` is set to `None`, then no peak
-        pixel value filtering will be performed.
+        The maximum allowed peak pixel value in an object. Objects with
+        peak pixel values greater than ``peakmax`` will be rejected.
+        This keyword may be used, for example, to exclude saturated
+        sources. If the star finder is run on an image that is a
+        `~astropy.units.Quantity` array, then ``peakmax`` must have the
+        same units. If ``peakmax`` is set to `None`, then no peak pixel
+        value filtering will be performed.
     """
 
     def __init__(self, data, convolved_data, xypos, kernel, *, sharplo=0.2,
@@ -576,7 +584,8 @@ def apply_filters(self):
             warnings.warn('No sources were found.', NoDetectionsWarning)
             return None
 
-        # filter based on sharpness, roundness, and peakmax
+        # keep sources that are within the sharpness, roundness, and
+        # peakmax (inclusive) bounds
         mask = ((newcat.sharpness >= newcat.sharplo)
                 & (newcat.sharpness <= newcat.sharphi)
                 & (newcat.roundness >= newcat.roundlo)

photutils/detection/starfinder.py

@@ -51,13 +51,13 @@ class StarFinder(StarFinderBase):
         will be selected.
 
     peakmax : float, None, optional
-        The maximum allowed peak pixel value in an object. Only objects
-        whose peak pixel values are strictly smaller than ``peakmax``
-        will be selected. This may be used, for example, to exclude
-        saturated sources. If the star finder is run on an image that is
-        a `~astropy.units.Quantity` array, then ``peakmax`` must have
-        the same units. If ``peakmax`` is set to `None`, then no peak
-        pixel value filtering will be performed.
+        The maximum allowed peak pixel value in an object. Objects with
+        peak pixel values greater than ``peakmax`` will be rejected.
+        This keyword may be used, for example, to exclude saturated
+        sources. If the star finder is run on an image that is a
+        `~astropy.units.Quantity` array, then ``peakmax`` must have the
+        same units. If ``peakmax`` is set to `None`, then no peak pixel
+        value filtering will be performed.
 
     See Also
     --------
@@ -186,13 +186,13 @@ class _StarFinderCatalog:
         will be selected.
 
     peakmax : float, None, optional
-        The maximum allowed peak pixel value in an object. Only objects
-        whose peak pixel values are strictly smaller than ``peakmax``
-        will be selected. This may be used, for example, to exclude
-        saturated sources. If the star finder is run on an image that is
-        a `~astropy.units.Quantity` array, then ``peakmax`` must have
-        the same units. If ``peakmax`` is set to `None`, then no peak
-        pixel value filtering will be performed.
+        The maximum allowed peak pixel value in an object. Objects with
+        peak pixel values greater than ``peakmax`` will be rejected.
+        This keyword may be used, for example, to exclude saturated
+        sources. If the star finder is run on an image that is a
+        `~astropy.units.Quantity` array, then ``peakmax`` must have the
+        same units. If ``peakmax`` is set to `None`, then no peak pixel
+        value filtering will be performed.
     """
 
     def __init__(self, data, xypos, shape, *, brightest=None, peakmax=None):
@@ -416,9 +416,9 @@ def apply_filters(self):
             warnings.warn('No sources were found.', NoDetectionsWarning)
             return None
 
-        # filter based on peakmax
+        # keep sources with peak pixel values less than or equal to peakmax
         if newcat.peakmax is not None:
-            mask = (newcat.max_value < newcat.peakmax)
+            mask = (newcat.max_value <= newcat.peakmax)
             newcat = newcat[mask]
 
         if len(newcat) == 0:

photutils/detection/tests/test_starfinder.py

@@ -94,6 +94,24 @@ def test_peakmax(self, data, kernel):
             tbl = starfinder(data)
             assert tbl is None
 
+    def test_peakmax_limit(self):
+        """
+        Test that the peakmax limit is inclusive.
+        """
+        data = np.zeros((11, 11))
+        x = 5
+        y = 6
+        kernel = np.array([[0.1, 0.6, 0.1],
+                           [0.6, 0.8, 0.6],
+                           [0.1, 0.6, 0.1]])
+        data[y - 1: y + 2, x - 1: x + 2] = kernel
+
+        finder = StarFinder(threshold=0, kernel=kernel, peakmax=0.8)
+        tbl = finder.find_stars(data)
+
+        assert len(tbl) == 1
+        assert tbl[0]['max_value'] == 0.8
+
     def test_brightest(self, data, kernel):
         finder = StarFinder(1, kernel, brightest=10)
         tbl = finder(data)