Skip to main content

sigclip_restored_flags

sigclip_restored_flags(
    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,
    validate=True,
)

Return per-sample restored-candidate flags for sigma clipping.

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.

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

restored_flags : ndarray of uint8, same shape as input

Per-sample rollback bits: 64 for nkeep, 128 for maxrej.

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.