@@ -28,9 +28,47 @@ they can be accessed by importing them::
2828A full list of the different tools are provided below. Please see the
2929documentation for their different usages. For example, sigma clipping,
3030which is a common way to estimate the background of an image, can be
31- performed with the :func: `~astropy.stats.sigma_clip ` function. By
32- default, the function returns a masked array where outliers are
33- masked.
31+ performed with the :func: `~astropy.stats.sigma_clip ` function.
32+ By default, the function returns a masked array, a type of Numpy array
33+ used for handling missing or invalid entries. Masked arrays retain the
34+ original data but also store another Boolean array of the same shape
35+ where ``True `` indicates that the value is masked.Most Numpy ufuncs
36+ will understand masked arrays and treat them appropriately.
37+ For example, consider the following dataset with a clear outlier::
38+
39+ >>> import numpy as np
40+ >>> from astropy.stats import sigma_clip
41+ >>> x = np.array([1, 0, 0, 1, 99, 0, 0, 1, 0])
42+
43+ The mean is skewed by the outlier::
44+
45+ >>> x.mean()
46+ 11.333333333333334
47+
48+ Sigma-clipping (3 sigma by default) returns a masked array,
49+ and so functions like ``mean `` will ignore the outlier::
50+
51+ >>> clipped = sigma_clip(x)
52+ >>> clipped
53+ masked_array(x = [1 0 0 1 -- 0 0 1 0],
54+ mask = [False False False False True False False False False],
55+ fill_value = 999999)
56+ >>> clipped.mean()
57+ 0.375
58+
59+ If you need to access the original data directly, you can use the ``.data ``
60+ property. Combined with the ``.mask `` property, you can get the original
61+ outliers, or the values that were not clipped::
62+
63+ >>> outliers = clipped.data[clipped.mask]
64+ >>> outliers
65+ array([99])
66+ >>> valid = clipped.data[~clipped.mask]
67+ >>> valid
68+ array([1, 0, 0, 1, 0, 0, 1, 0])
69+
70+ For more information on masked arrays, including see the
71+ `Numpy documentation<https://numpy.org/doc/stable/reference/maskedarray.generic.html> `_.
3472
3573Examples
3674--------
0 commit comments