kernels.pclip_1d

kernels.pclip_1d(
    values,
    *,
    mask=None,
    frac=-0.5,
    sigma=3.0,
    nkeep=1,
    validate=True,
)

IRAF-style percentile clipping at each pixel (1-D variant).

Parameters

values : (ndarray, shape(N))

One-dimensional value vector. Accepted dtypes are uint8, uint16, int16, int32, float32, and float64. Integer inputs are promoted to the package’s floating workspace when validate is True.

mask : ndarray of bool = None

Input mask; True means already masked. Must have shape (N,).

frac : float = -0.5

IRAF pclip value. If abs(frac) < 1, it is converted to an integer rank offset using half of the input image count. Positive values estimate sigma from the high side of the sorted median; negative values estimate sigma from the low side.

sigma : float or tuple of float = 3.0

User-supplied lower and upper clipping multipliers applied to the pclip-estimated spread. This maps to IRAF lsigma and hsigma.

nkeep : int = 1

Minimum number of unmasked samples to retain after pclip rejection.

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,)

True where a value was rejected by this kernel.

std : scalar or None

Spread used by sigma/CCD clipping. None for rejection algorithms without a spread diagnostic.

low : scalar

Lower retained-value bound. Bounds are inclusive: values equal to low are retained.

upp : scalar

Upper retained-value bound. Bounds are inclusive: values equal to upp are retained.

nit : scalar

Iteration count.

output_flags : scalar

Bit-coded status using the same bit meanings as the stack kernel.

Notes

This follows IRAF imcombine pclip semantics: choose a sorted rank offset from the median, use that sample’s distance from the median as sigma, then apply lower and upper sigma thresholds.