LinearClip

LinearClip(
    low_scale=1.0,
    low=0.0,
    upp_scale=1.0,
    upp=0.0,
    maxiters=1,
    cenfunc='median',
    nkeep=1,
    maxrej=None,
    revert_on_nkeep=True,
    grow=None,
)

Center-relative linear clipping.

Parameters

low_scale : float = 1.0

Multiplier for the per-pixel center used in the lower retained bound.

low : float = 0.0

Non-negative margin subtracted from low_scale * center.

upp_scale : float = 1.0

Multiplier for the per-pixel center used in the upper retained bound.

upp : float = 0.0

Non-negative margin added to upp_scale * center.

maxiters : int = 1

Maximum number of clipping iterations per pixel. 1 performs one clipping pass.

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.

nkeep : int = 1

Minimum number of unmasked values to preserve at each pixel.

maxrej : int or None = None

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

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.

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

Compute c with cenfunc from the current finite, unmasked values. Retain values within the inclusive interval::

low_scale * c - low <= x <= upp_scale * c + upp

For example, low_scale=upp_scale=1, low=2, upp=3 retains values from c - 2 through c + 3. Recompute c after each accepted pass until no new samples are rejected, a safeguard reverts the pass, or maxiters is reached. maxiters=1 makes a single pass. No spread is estimated.

Default behavior differs by entry point: LinearClip() and stack linearclip() explicitly disable clipping for (low_scale, low, upp_scale, upp) = (1, 0, 1, 0); they return an all-false rejection mask, NaN bounds, and zero iterations. linearclip_1d() applies the equation even for these defaults, retaining only values equal to c unless a safeguard reverts the pass. low/upp outputs are the last accepted interval bounds, or NaN if no pass was accepted.

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

Methods

Name	Description
apply	Apply LinearClip to an image stack.

apply

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

Apply LinearClip 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 this rejection algorithm. std is the per-pixel clipping spread for SigClip, reference noise for CCDClip, and None for algorithms without a spread diagnostic.

Notes

Compute c with cenfunc from the current finite, unmasked values. Retain values within the inclusive interval::

low_scale * c - low <= x <= upp_scale * c + upp

For example, low_scale=upp_scale=1, low=2, upp=3 retains values from c - 2 through c + 3. Recompute c after each accepted pass until no new samples are rejected, a safeguard reverts the pass, or maxiters is reached. maxiters=1 makes a single pass. No spread is estimated.

Default behavior differs by entry point: LinearClip() and stack linearclip() explicitly disable clipping for (low_scale, low, upp_scale, upp) = (1, 0, 1, 0); they return an all-false rejection mask, NaN bounds, and zero iterations. linearclip_1d() applies the equation even for these defaults, retaining only values equal to c unless a safeguard reverts the pass. low/upp outputs are the last accepted interval bounds, or NaN if no pass was accepted.

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