SigClip

SigClip(
    sigma=(3.0, 3.0),
    maxiters=5,
    cenfunc='median',
    clip_cen=None,
    stdfunc='std',
    ddof=0,
    nkeep=1,
    maxrej=None,
    revert_on_nkeep=True,
    grow=None,
)

Iterative sigma-clipping rejection.

Parameters

sigma : float or tuple of float = (3.0, 3.0)

User-supplied clipping multiplier, not the measured data spread itself. Values are clipped when their residual from the clipping center exceeds sigma * spread. A scalar applies the same multiplier to both tails; a 2-tuple (sigma_lower, sigma_upper) clips asymmetrically. Thresholds must be finite and non-negative.

maxiters : int = 5

Maximum number of clipping iterations per pixel.

ddof : int = 0

Delta degrees of freedom for the per-pixel spread estimator.

nkeep : int = 1

Minimum number of unmasked values to preserve at each pixel. An iteration that would drop below this count is reverted in full. The default, 1, prevents clipping from rejecting every finite sample in a per-output stack. Set 0 only when all samples may be rejected.

maxrej : int or None = None

Maximum number of values that may be rejected at each pixel. None means no limit.

cenfunc : {'median', 'lmedian', 'mean'} = 'median'

Center estimator used each iteration. lmedian accepts the alias lmed and uses the lower of the two middle samples for even valid counts.

clip_cen : {'median', 'lmedian', 'mean'} or None = None

Center used when computing the spread for iterative rejection. None uses the same center as cenfunc. Choices are "median", "lmedian", "lmed", and "mean".

revert_on_nkeep : bool = True

If True, an iteration that would leave fewer than nkeep usable samples at a pixel is reverted in full for that pixel. Input masks, threshold masks, and non-finite samples remain excluded. The default is True. If False, clipping is strict and may leave fewer than nkeep samples.

stdfunc : {'std', 'mad'} = 'std'

Spread estimator used by sigma clipping. "std" uses the standard deviation. "mad" uses 1.4826 * median(abs(x - clip_cen)) as a robust sigma estimate and ignores ddof.

grow : float or None = None

Optional radius in pixels used to grow mask_rej spatially after rejection. Axis 0 is the stack axis and is never grown across. None disables growth and skips the extra calculation.

Notes

For the current finite, unmasked samples, let c be the cenfunc center, a the clip_cen center, and n the sample count. Retain::

c - sigma_lower * d <= x <= c + sigma_upper * d

x is a sample value; sigma=(sigma_lower, sigma_upper) sets the two multipliers, or a scalar uses the same multiplier for both tails. The spread is d = sqrt(sum((x - a)**2) / (n - ddof)) for stdfunc="std", or d = 1.4826 * median(abs(x - a)) for stdfunc="mad". MAD ignores ddof; standard deviation is undefined when n <= ddof. clip_cen=None uses the same center as cenfunc.

Equality is retained. Recompute center and spread after each accepted pass; stop when no new samples are rejected, the spread is undefined, a safeguard reverts the pass, or maxiters is reached. Earlier rejections remain excluded. When requested, std describes the clipping spread, not the uncertainty of the combined output; low and upp report the final retained extrema.

For derivations and worked examples, see the Rejection Methods tutorial.

Methods

Name	Description
apply	Apply SigClip to an image stack.

apply

SigClip.apply(arr, mask=None, *, validate=True)

Apply SigClip to an image stack.

Parameters

arr : (ndarray, shape(N, *spatial))

Image stack. Inputs with more than 3 dimensions are flattened internally; output shapes match the trailing spatial dimensions of the input.

mask : ndarray of bool = None

Input mask; True means already masked. Must have the same shape as arr before any internal flattening.

validate : bool = True

If True, validate inputs before calling the kernel.

Returns

: mask_rej, std, low, upp, nit, output_flags : tuple of ndarray

Rejection mask and diagnostics from :func:imcombiners.kernels.sigclip. std is the per-pixel clipping spread for SigClip, reference noise for CCDClip, and None for algorithms without a spread diagnostic.

Notes

For the current finite, unmasked samples, let c be the cenfunc center, a the clip_cen center, and n the sample count. Retain::

c - sigma_lower * d <= x <= c + sigma_upper * d

x is a sample value; sigma=(sigma_lower, sigma_upper) sets the two multipliers, or a scalar uses the same multiplier for both tails. The spread is d = sqrt(sum((x - a)**2) / (n - ddof)) for stdfunc="std", or d = 1.4826 * median(abs(x - a)) for stdfunc="mad". MAD ignores ddof; standard deviation is undefined when n <= ddof. clip_cen=None uses the same center as cenfunc.

Equality is retained. Recompute center and spread after each accepted pass; stop when no new samples are rejected, the spread is undefined, a safeguard reverts the pass, or maxiters is reached. Earlier rejections remain excluded. When requested, std describes the clipping spread, not the uncertainty of the combined output; low and upp report the final retained extrema.

For derivations and worked examples, see the Rejection Methods tutorial.