<commit_before># Licensed under a 3-clause BSD style license - see LICENSE.rst
from __future__ import (absolute_import, division, print_function,
                        unicode_literals)
import numpy as np
from ..extern.imageutils import sigmaclip_stats


__all__ = ['detect_sources', 'find_peaks']


def detect_sources(data, npixels, snr_threshold=5.0, threshold=None,
                   filter_fwhm=None, background=None, error=None,
                   mask=None, mask_val=None, sigclip_sigma=3.0,
                   sigclip_iters=None, connectivity=8):
    """
    Detect sources above a specified signal-to-noise ratio or threshold
    value in an image and return a segmentation image.

    This function does not deblend overlapping sources.

    Parameters
    ----------
    data : array_like
        The 2D array of the image.

    npixels : int
        The number of connected pixels, each greater than the threshold
        defined by either ``snr_threshold`` or ``threshold``, that an
        object must have to be detected.  Must be a positive integer.

    snr_threshold : float
        The signal-to-noise ratio per pixel above the ``background`` for
        which to consider a pixel as possibly being part of a source.
        Detected sources must have ``npixels`` connected pixels that are
        greater than the threshold level.  ``snr_threshold`` is ignored
        if ``threshold`` is input.  The default is 5.0.

    threshold : float, optional
        The image value to be used as the detection threshold.  Detected
        sources must have ``npixels`` connected pixels that are greater
        than the threshold value.  If ``threshold`` is input, then
        ``snr_threshold`` is ignored.

    filter_fwhm : float, optional
        The FWHM of a circular 2D Gaussian filter that is applied to the
        input image before it is thresholded.  Filtering the image will
        maximize detectability of objects with a FWHM similar to
        ``filter_fwhm``.  Set to `None` (the default) to turn off image
        filtering.

    background : float or array_like, optional
        The background level of the input ``data``.  ``background`` may
        either be a scalar value or a 2D image with the same shape as
        the input ``data``.  If the input ``data`` has been
        background-subtracted, then set ``background`` to ``0.0``.  If
        `None`, then the background will be estimated using
        sigma-clipped statistics (see the ``mask``, ``mask_val``,
        ``sigclip_sigma`` and ``sigclip_iters`` parameters).  If
        ``background`` and ``error`` are input, then ``mask``,
        ``mask_val``, ``sigclip_sigma``, and ``sigclip_iters`` are
        ignored.

    error : array_like, optional
        The 2D array of the 1-sigma Gaussian errors of the input
        ``data``.  ``error`` should include all sources of "background"
        error but *exclude* the Poission error of the sources.  If
        `None`, then the background rms error will be estimated using
        sigma-clipped statistics (see the ``mask``, ``mask_val``,
        ``sigclip_sigma`` and ``sigclip_iters`` parameters).  If
        ``background`` and ``error`` are input, then ``mask``,
        ``mask_val``, ``sigclip_sigma``, and ``sigclip_iters`` are
        ignored.

    mask : array_like, bool, optional
        A boolean mask with the same shape as ``data``, where a `True`
        value indicates the corresponding element of ``data`` is masked.
        Masked pixels are ignored when computing the image background
        statistics.

    mask_val : float, optional
        An image data value (e.g., ``0.0``) that is ignored when
        computing the image background statistics.  ``mask_val`` will be
        ignored if ``mask`` is input.

    sigclip_sigma : float, optional
        The number of standard deviations to use as the clipping limit
        when calculating the image background statistics.

    sigclip_iters : float, optional
       The number of iterations to perform sigma clipping, or `None` to
       clip until convergence is achieved (i.e., continue until the last
       iteration clips nothing) when calculating the image background
       statistics.

    connectivity : int, optional
        The type of pixel connectivity used in determining how pixels
        are grouped into a detected source.  The options are 4 or 8
        (default).  4-connected pixels touch along their edges.
        8-connected pixels touch along their edges or corners.  For
        reference, SExtractor uses 8-connected pixels.

    Returns
    -------
    segment_image :  `numpy.ndarray`
        A 2D segmentation image, with the same shape as ``data``, where
        sources are marked by different positive integer values.  A
        value of zero is reserved for the background.
    """<commit_msg>Add example plot for detect_sources<commit_after># Licensed under a 3-clause BSD style license - see LICENSE.rst
from __future__ import (absolute_import, division, print_function,
                        unicode_literals)
import numpy as np
from ..extern.imageutils import sigmaclip_stats


__all__ = ['detect_sources', 'find_peaks']


def detect_sources(data, npixels, snr_threshold=5.0, threshold=None,
                   filter_fwhm=None, background=None, error=None,
                   mask=None, mask_val=None, sigclip_sigma=3.0,
                   sigclip_iters=None, connectivity=8):
    """
    Detect sources above a specified signal-to-noise ratio or threshold
    value in an image and return a segmentation image.

    This function does not deblend overlapping sources.

    Parameters
    ----------
    data : array_like
        The 2D array of the image.

    npixels : int
        The number of connected pixels, each greater than the threshold
        defined by either ``snr_threshold`` or ``threshold``, that an
        object must have to be detected.  Must be a positive integer.

    snr_threshold : float
        The signal-to-noise ratio per pixel above the ``background`` for
        which to consider a pixel as possibly being part of a source.
        Detected sources must have ``npixels`` connected pixels that are
        greater than the threshold level.  ``snr_threshold`` is ignored
        if ``threshold`` is input.  The default is 5.0.

    threshold : float, optional
        The image value to be used as the detection threshold.  Detected
        sources must have ``npixels`` connected pixels that are greater
        than the threshold value.  If ``threshold`` is input, then
        ``snr_threshold`` is ignored.

    filter_fwhm : float, optional
        The FWHM of a circular 2D Gaussian filter that is applied to the
        input image before it is thresholded.  Filtering the image will
        maximize detectability of objects with a FWHM similar to
        ``filter_fwhm``.  Set to `None` (the default) to turn off image
        filtering.

    background : float or array_like, optional
        The background level of the input ``data``.  ``background`` may
        either be a scalar value or a 2D image with the same shape as
        the input ``data``.  If the input ``data`` has been
        background-subtracted, then set ``background`` to ``0.0``.  If
        `None`, then the background will be estimated using
        sigma-clipped statistics (see the ``mask``, ``mask_val``,
        ``sigclip_sigma`` and ``sigclip_iters`` parameters).  If
        ``background`` and ``error`` are input, then ``mask``,
        ``mask_val``, ``sigclip_sigma``, and ``sigclip_iters`` are
        ignored.

    error : array_like, optional
        The 2D array of the 1-sigma Gaussian errors of the input
        ``data``.  ``error`` should include all sources of "background"
        error but *exclude* the Poission error of the sources.  If
        `None`, then the background rms error will be estimated using
        sigma-clipped statistics (see the ``mask``, ``mask_val``,
        ``sigclip_sigma`` and ``sigclip_iters`` parameters).  If
        ``background`` and ``error`` are input, then ``mask``,
        ``mask_val``, ``sigclip_sigma``, and ``sigclip_iters`` are
        ignored.

    mask : array_like, bool, optional
        A boolean mask with the same shape as ``data``, where a `True`
        value indicates the corresponding element of ``data`` is masked.
        Masked pixels are ignored when computing the image background
        statistics.

    mask_val : float, optional
        An image data value (e.g., ``0.0``) that is ignored when
        computing the image background statistics.  ``mask_val`` will be
        ignored if ``mask`` is input.

    sigclip_sigma : float, optional
        The number of standard deviations to use as the clipping limit
        when calculating the image background statistics.

    sigclip_iters : float, optional
       The number of iterations to perform sigma clipping, or `None` to
       clip until convergence is achieved (i.e., continue until the last
       iteration clips nothing) when calculating the image background
       statistics.

    connectivity : int, optional
        The type of pixel connectivity used in determining how pixels
        are grouped into a detected source.  The options are 4 or 8
        (default).  4-connected pixels touch along their edges.
        8-connected pixels touch along their edges or corners.  For
        reference, SExtractor uses 8-connected pixels.

    Returns
    -------
    segment_image :  `numpy.ndarray`
        A 2D segmentation image, with the same shape as ``data``, where
        sources are marked by different positive integer values.  A
        value of zero is reserved for the background.

    See Also
    --------
    segment_photometry, segment_properties

    Examples
    --------

    .. plot::
        :include-source:

        # make a table of Gaussian sources
        from astropy.table import Table
        table = Table()
        table['amplitude'] = [50, 70, 150, 210]
        table['x_mean'] = [160, 25, 150, 90]
        table['y_mean'] = [70, 40, 25, 60]
        table['x_stddev'] = [15.2, 5.1, 3., 8.1]
        table['y_stddev'] = [2.6, 2.5, 3., 4.7]
        table['theta'] = np.array([145., 20., 0., 60.]) * np.pi / 180.

        # make an image of the sources with Gaussian noise
        from photutils.datasets import make_gaussian_sources
        from photutils.datasets import make_noise_image
        shape = (100, 200)
        sources = make_gaussian_sources(shape, table)
        noise = make_noise_image(shape, type='gaussian', mean=0.,
                                 stddev=5., random_state=12345)
        image = sources + noise

        # detect the sources
        from photutils import detect_sources
        segm_image = detect_sources(image, npixels=5, snr_threshold=3.,
                                    filter_fwhm=3.)

        # plot the image and the segmentation image
        import matplotlib.pyplot as plt
        fig, (ax1, ax2) = plt.subplots(2, 1, figsize=(8, 8))
        ax1.imshow(image, origin='lower', interpolation='nearest')
        ax2.imshow(segm_image, origin='lower', interpolation='nearest')
    """
{'fraction_non_alphanumeric': 0.08451710890735281, 'fraction_numerical': 0.011078352541767176, 'mean_word_length': 2.541284403669725, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '940098', 'n_tokens_mistral': 3049, 'n_tokens_neox': 2894, 'n_words': 1259}