sigclip

sigclip(
    arr,
    *,
    mask=None,
    sigma=(3.0, 3.0),
    maxiters=5,
    ddof=0,
    nkeep=0,
    maxrej=None,
    cenfunc='median',
    clip_cen=None,
    stdfunc='std',
    revert_on_nkeep=False,
    grow=None,
    validate=True,
)

Sigma-clipping rejection.

Parameters

arr : (ndarray, shape(N, *spatial)): Samples along axis 0; at least two dimensions.
mask : ndarray or None = None: Same shape as the input; True excludes a sample. Default None.
sigma : float or (float, float) = (3.0, 3.0): Finite, nonnegative lower and upper multipliers; default (3.0, 3.0). Samples exactly on a threshold survive.
maxiters : int = 5: Maximum attempted passes; default 5. 0 applies initial exclusions only.
ddof : int = 0: Divide squared deviations by n - ddof; default 0. Ignored for MAD. Undefined statistics stop the current pass without changing the mask.
nkeep : int = 0: Rollback minimum, active only with revert_on_nkeep=True; default 0. This is not a final minimum-count requirement.
maxrej : int or None = None: Roll back a pass if total exclusions exceed this count. Counts input masks and nonfinite samples as well as clipping; default None (unlimited).
cenfunc : str = 'median': Rejection center: "median" (default), "lmedian", or "mean".
clip_cen : str or None = None: Dispersion center: "mean", "median", "lmedian", or "cenfunc" to use the computed rejection center directly. None follows cenfunc’s estimator, preserving its arithmetic; default None.
stdfunc : str = 'std': "std" (default) or "mad" (median absolute deviation times 1.4826).
revert_on_nkeep : bool = False: Enable whole-pass survivor rollback; default False. Earlier accepted rejections and initial exclusions remain after rollback.
grow : float or None = None: Nonnegative Euclidean dilation radius within each plane. Axis 0 is never grown across; default None.
validate : bool = True: Validate/promote arrays; default True. With False, supply a C-contiguous 3-D float32/float64 stack and same-shape boolean mask.

Returns

mask_rej : ndarray of bool, same shape as input: Final exclusions, including input masks and nonfinite samples.
: std, low, upp : scalars or ndarrays: Last valid attempted spread and final retained extrema. Extrema are not clipping bounds. Scalars for vectors; arrays of shape (*spatial,) in workspace dtype for stacks.
: nit, output_flags : scalars or ndarrays: Legacy counter and flags; uint8 arrays for stacks. Starts at one and saturates at 255. Bits: 1 input mask, 2 iteration limit, 4 nkeep rollback, 8 maxrej rollback, 16 added growth.

Notes

NaN, infinities, and input masks are excluded before clipping. Inputs are never modified. Accepted rejections accumulate. Empty/all-excluded inputs have all-excluded masks, NaN extrema/spread, and NaN fused reductions.

With validate=True, float32 and float64 are preserved; uint8, uint16, and int16 use float32, and int32 uses float64. Other dtypes are rejected. Noncontiguous input is copied only when needed. Centers and MAD round to the input dtype before threshold comparisons. Squared residuals and limits can overflow or underflow.

Growth includes input masks and nonfinite values. Scalar diagnostics describe clipping before growth.