PClip

PClip(frac=-0.5, sigma=3.0, nkeep=1, grow=None)

IRAF-style percentile clipping.

Parameters

frac : float = -0.5

IRAF pclip value. Values with abs(frac) < 1 are converted to an integer sorted-rank offset using half of the input image count.

sigma : float or tuple of float = 3.0

User-supplied lower and upper clipping multipliers applied to the pclip-estimated spread.

nkeep : int = 1

Minimum number of unmasked samples to retain after pclip rejection.

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

Sort the finite, unmasked samples and let m be their median. frac selects an offset rank r below (negative) or above (positive) the median; it is not a percentage of samples to reject. For abs(frac) < 1, scale by max(N // 2, 1) for the original image count N and truncate to an integer, with a minimum offset magnitude of one. Estimate::

d = sign(frac) * (x_sorted[r] - m)

Reject sorted endpoints while (m-x)/d >= sigma_lower or (x-m)/d >= sigma_upper, using the two sigma multipliers. Unlike sigma/CCD clipping, equality is rejected. The center and spread are computed once. If needed, restore the least-extreme rejected endpoints to satisfy nkeep, including IRAF’s residual-tie handling. With fewer than three usable samples, at most nkeep usable samples, or d == 0, no additional samples are rejected. In diagnostic calls, std is None and low/upp report retained extrema. The tutorial specifies the full rank convention.

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

Methods

Name	Description
apply	Apply PClip to an image stack.

apply

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

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

Notes

Sort the finite, unmasked samples and let m be their median. frac selects an offset rank r below (negative) or above (positive) the median; it is not a percentage of samples to reject. For abs(frac) < 1, scale by max(N // 2, 1) for the original image count N and truncate to an integer, with a minimum offset magnitude of one. Estimate::

d = sign(frac) * (x_sorted[r] - m)

Reject sorted endpoints while (m-x)/d >= sigma_lower or (x-m)/d >= sigma_upper, using the two sigma multipliers. Unlike sigma/CCD clipping, equality is rejected. The center and spread are computed once. If needed, restore the least-extreme rejected endpoints to satisfy nkeep, including IRAF’s residual-tie handling. With fewer than three usable samples, at most nkeep usable samples, or d == 0, no additional samples are rejected. In diagnostic calls, std is None and low/upp report retained extrema. The tutorial specifies the full rank convention.

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