sigma_clipped_stats#
- astropy.stats.sigma_clipped_stats(data: ArrayLike, mask: NDArray | None = None, mask_value: float | None = None, sigma: float = 3.0, sigma_lower: float | None = None, sigma_upper: float | None = None, maxiters: int | None = 5, cenfunc: Literal['median', 'mean'] | Callable = 'median', stdfunc: Literal['std', 'mad_std'] | Callable = 'std', std_ddof: int = 0, axis: int | tuple[int, ...] | None = None, grow: float | Literal[False] | None = False) tuple[float, float, float] [source]#
Calculate sigma-clipped statistics on the provided data.
- Parameters:
- dataarray_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 aTrue
value indicates the corresponding element ofdata
is masked. Masked pixels are excluded when computing the statistics.- mask_value
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 inputmask
.- sigma
float
, optional The number of standard deviations to use for both the lower and upper clipping limit. These limits are overridden by
sigma_lower
andsigma_upper
, if input. The default is 3.- sigma_lower
float
orNone
, optional The number of standard deviations to use as the lower bound for the clipping limit. If
None
then the value ofsigma
is used. The default isNone
.- sigma_upper
float
orNone
, optional The number of standard deviations to use as the upper bound for the clipping limit. If
None
then the value ofsigma
is used. The default isNone
.- maxiters
int
orNone
, 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 tomaxiters
iterations, the clipping iterations will stop. The default is 5.- cenfunc{‘median’, ‘mean’} or
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 anaxis
keyword to return an array with axis dimension(s) removed. The default is'median'
.- stdfunc{‘std’, ‘mad_std’} or
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 anaxis
keyword to return an array with axis dimension(s) removed. The default is'std'
.- std_ddof
int
, optional The delta degrees of freedom for the standard deviation calculation. The divisor used in the calculation is
N - std_ddof
, whereN
represents the number of elements. For a population standard deviation where you have data for the entire population, usestd_ddof=0
. For a sample standard deviation where you have a sample of the population, usestd_ddof=1
. The default is 0.- axis
None
orint
ortuple
ofint
, 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 thecenfunc
andstdfunc
. The default isNone
.- grow
float
orFalse
, 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.
- dataarray_like or
- Returns:
- mean, median, stddev
float
The mean, median, and standard deviation of the sigma-clipped data.
- mean, median, stddev
See also
Notes
The best performance will typically be obtained by setting
cenfunc
andstdfunc
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.