Skip to main content

kernels.linearclip

kernels.linearclip(
    arr,
    *,
    mask=None,
    low_scale=1.0,
    low=0.0,
    upp_scale=1.0,
    upp=0.0,
    maxiters=1,
    nkeep=1,
    maxrej=None,
    cenfunc='median',
    revert_on_nkeep=True,
    grow=None,
    validate=True,
)

Center-relative linear clipping.

Parameters

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

Image stack. Accepted dtypes are uint8, uint16, int16, int32, float32, and float64. Integer inputs are promoted to the package’s floating workspace when validate is True. 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.

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.

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.

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.

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.

validate : bool = True

If True, check dimensionality and normalize dtype/contiguity before entering the Rust kernel. If False, callers must provide inputs that satisfy the compiled kernel assumptions.

Returns

mask_rej : ndarray of bool, shape (N, *spatial)

True for excluded samples, including input masks and non-finite values. LinearClip excludes input-mask entries; its disabled default returns an all-false mask (see Notes). Thus mask_rej.sum(axis=0) need not count only newly rejected samples.

std : (ndarray, shape(*spatial) or None)

Clipping spread for SigClip; reference noise for CCDClip (see Notes). None for rejection algorithms without a spread diagnostic.

low : (ndarray, shape(*spatial))

Minimum retained value before growth. LinearClip instead reports its last accepted lower interval bound. Use mask_rej to identify survivors.

upp : (ndarray, shape(*spatial))

Maximum retained value before growth. LinearClip instead reports its last accepted upper interval bound. Use mask_rej to identify survivors.

nit : ndarray of uint8, shape (*spatial)

Iteration-count map.

output_flags : ndarray of uint8, shape (*spatial)

Bit-coded status. 0 means normal completion; bit 1 means at least one pre-masked sample at this output element; bit 16 means grow added at least one rejected sample at this output element. Iterative kernels also use bit 2 for maxiters, bit 4 for nkeep, and bit 8 for maxrej. Bits are OR-ed. output_flags is a per-output diagnostic; use mask_rej to inspect individual samples.

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.