Skip to main content
`Ctrl`+`K`

# sigma_clip

astropy.stats.sigma_clipping.sigma_clip(data, sigma=3.0, sigma_lower=None, sigma_upper=None, maxiters=5, cenfunc='median', stdfunc='std', axis=None, masked=True, return_bounds=False, copy=True, grow=False)

  Perform sigma-clipping on the provided data.

  The data will be iterated over, each time rejecting values that are less or more than a specified number of standard deviations from a center value.

  Clipped (rejected) pixels are those where:

      data < center - (sigma_lower * std)
      data > center + (sigma_upper * std)

  where:

      center = cenfunc(data [, axis=])
      std = stdfunc(data [, axis=])

  Invalid data values (i.e., NaN or inf) are automatically clipped.

  For an object-oriented interface to sigma clipping, see `SigmaClip`.

  Note

  `scipy.stats.sigmaclip` provides a subset of the functionality in this class. Also, its input data cannot be a masked array and it does not handle data that contains invalid values (i.e., NaN or inf). Also note that it uses the mean as the centering function. The equivalent settings to `scipy.stats.sigmaclip` are:

      sigma_clip(sigma=4., cenfunc='mean', maxiters=None, axis=None,
      ...        masked=False, return_bounds=True)

  Parameters:
    data numpy:array_like or `MaskedArray`

      The data to be sigma clipped.

    sigma `python:float`, optional

      The number of standard deviations to use for both the lower and upper clipping limit. These limits are overridden by `sigma_lower` and `sigma_upper`, if input. The default is 3.

    sigma_lower `python:float` or `python:None`, optional

      The number of standard deviations to use as the lower bound for the clipping limit. If `None` then the value of `sigma` is used. The default is `None`.

    sigma_upper `python:float` or `python:None`, optional

      The number of standard deviations to use as the upper bound for the clipping limit. If `None` then the value of `sigma` is used. The default is `None`.

    maxiters `python:int` or `python:None`, optional

      The maximum number of sigma-clipping iterations to perform or `None` to clip until convergence is achieved (i.e., iterate until the last iteration clips nothing). If convergence is achieved prior to `maxiters` iterations, the clipping iterations will stop. The default is 5.

    cenfunc{‘median’, ‘mean’} or `python:callable()`, optional

      The statistic or callable function/object used to compute the center value for the clipping. If using a callable function/object and the `axis` keyword is used, then it must be able to ignore NaNs (e.g., `numpy.nanmean`) and it must have an `axis` keyword to return an array with axis dimension(s) removed. The default is `'median'`.

    stdfunc{‘std’, ‘mad_std’} or `python:callable()`, optional

      The statistic or callable function/object used to compute the standard deviation about the center value. If using a callable function/object and the `axis` keyword is used, then it must be able to ignore NaNs (e.g., `numpy.nanstd`) and it must have an `axis` keyword to return an array with axis dimension(s) removed. The default is `'std'`.

    axis `python:None` or `python:int` or `python:tuple` of `python:int`, optional

      The axis or axes along which to sigma clip the data. If `None`, then the flattened data will be used. `axis` is passed to the `cenfunc` and `stdfunc`. The default is `None`.

    masked bool, optional

      If `True`, then a `MaskedArray` is returned, where the mask is `True` for clipped values. If `False`, then a `ndarray` is returned. The default is `True`.

    return_bounds bool, optional

      If `True`, then the minimum and maximum clipping bounds are also returned.

    copy bool, optional

      If `True`, then the `data` array will be copied. If `False` and `masked=True`, then the returned masked array data will contain the same array as the input `data` (if `data` is a `ndarray` or `MaskedArray`). If `False` and `masked=False`, the input data is modified in-place. The default is `True`.

    grow `python:float` or `False`, optional

      Radius within which to mask the neighbouring pixels of those that fall outwith the clipping limits (only applied along `axis`, if specified). As an example, for a 2D image a value of 1 will mask the nearest pixels in a cross pattern around each deviant pixel, while 1.5 will also reject the nearest diagonal neighbours and so on.

  Returns:
    result numpy:array_like

      If `masked=True`, then a `MaskedArray` is returned, where the mask is `True` for clipped values and where the input mask was `True`.

      If `masked=False`, then a `ndarray` is returned.

      If `return_bounds=True`, then in addition to the masked array or array above, the minimum and maximum clipping bounds are returned.

      If `masked=False` and `axis=None`, then the output array is a flattened 1D `ndarray` where the clipped values have been removed. If `return_bounds=True` then the returned minimum and maximum thresholds are scalars.

      If `masked=False` and `axis` is specified, then the output `ndarray` will have the same shape as the input `data` and contain `np.nan` where values were clipped. In this case, integer-type `data` arrays will be converted to `float32`. If the input `data` was a masked array, then the output `ndarray` will also contain `np.nan` where the input mask was `True`. If `return_bounds=True` then the returned minimum and maximum clipping thresholds will be `ndarray`s.

  See also

  `SigmaClip`, `sigma_clipped_stats`, `SigmaClippedStats`

  Notes

  The best performance will typically be obtained by setting `cenfunc` and `stdfunc` to one of the built-in functions specified as a string. If one of the options is set to a string while the other has a custom callable, you may in some cases see better performance if you have the bottleneck package installed. To preserve accuracy, bottleneck is only used for float64 computations.

  Examples

  This example uses a data array of random variates from a Gaussian distribution. We clip all points that are more than 2 sample standard deviations from the median. The result is a masked array, where the mask is `True` for clipped data:

      >>> from astropy.stats import sigma_clip
      >>> from numpy.random import randn
      >>> randvar = randn(10000)
      >>> filtered_data = sigma_clip(randvar, sigma=2, maxiters=5)

  This example clips all points that are more than 3 sigma relative to the sample mean, clips until convergence, returns an unmasked `ndarray`, and does not copy the data:

      >>> from astropy.stats import sigma_clip
      >>> from numpy.random import randn
      >>> from numpy import mean
      >>> randvar = randn(10000)
      >>> filtered_data = sigma_clip(randvar, sigma=3, maxiters=None,
      ...                            cenfunc=mean, masked=False, copy=False)

  This example sigma clips along one axis:

      >>> from astropy.stats import sigma_clip
      >>> from numpy.random import normal
      >>> from numpy import arange, diag, ones
      >>> data = arange(5) + normal(0., 0.05, (5, 5)) + diag(ones(5))
      >>> filtered_data = sigma_clip(data, sigma=2.3, axis=0)

  Note that along the other axis, no points would be clipped, as the standard deviation is higher.

  The behavior of `masked=False` depends on whether `axis` is specified. When `axis=None` (the default), clipped values are removed from the output, so the returned array may be shorter than the input:

      >>> import numpy as np
      >>> from astropy.stats import sigma_clip
      >>> x = np.ones(10)
      >>> x[5] = 1000.0
      >>> clipped = sigma_clip(x, masked=False)
      >>> len(clipped)  # shorter than input: outlier was removed
      9

  When `axis` is specified, clipped values are replaced with `np.nan` instead:

      >>> clipped_nan = sigma_clip(x, masked=False, axis=0)
      >>> bool(np.isnan(clipped_nan[5]))  # outlier replaced with nan
      True