Skip to main content
`Ctrl`+`K`

# sigma_clipped_stats

astropy.stats.sigma_clipped_stats(data, mask=None, mask_value=None, sigma=3.0, sigma_lower=None, sigma_upper=None, maxiters=5, cenfunc='median', stdfunc='std', std_ddof=0, axis=None, grow=False)

  Calculate sigma-clipped statistics on the provided data.

  Parameters:
    data numpy:array_like or `MaskedArray`

      Data array or object that can be converted to an array.

    mask `numpy.ndarray` (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 excluded when computing the statistics.

    mask_value `python:float`, optional

      A data value (e.g., `0.0`) that is ignored when computing the statistics. `mask_value` will be masked in addition to any input `mask`.

    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'`.

    std_ddof `python:int`, optional

      The delta degrees of freedom for the standard deviation calculation. The divisor used in the calculation is `N - std_ddof`, where `N` represents the number of elements. For a population standard deviation where you have data for the entire population, use `std_ddof=0`. For a sample standard deviation where you have a sample of the population, use `std_ddof=1`. The default is 0.

    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`.

    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:
    mean, median, stddev `python:float`

      The mean, median, and standard deviation of the sigma-clipped data.

  See also

  `SigmaClippedStats`, `SigmaClip`, `sigma_clip`

  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.