Skip to main content

kernels.ccdclip_combine

kernels.ccdclip_combine(
    arr,
    *,
    mask=None,
    combine,
    sigma=(3.0, 3.0),
    maxiters=5,
    ddof=0,
    nkeep=1,
    maxrej=None,
    cenfunc='median',
    clip_cen=None,
    revert_on_nkeep=True,
    rdnoise=0.0,
    gain=1.0,
    snoise=0.0,
    scales=None,
    zeros=None,
    validate=True,
)

CCD noise-model clipping (output-only variant).

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.

combine : {'mean', 'median'}

Output combine method evaluated after rejection. Fused combine kernels support "mean", "average", "avg", "median", and "med".

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.

rdnoise : float = 0.0

Read noise in electrons.

gain : float = 1.0

Positive CCD gain in electrons per DN (ADU).

snoise : float = 0.0

Fractional sensitivity-noise coefficient for multiplicative sensitivity (for example, flat-field) uncertainty. It adds (snoise * signal)^2 to the CCD variance.

scales : array - like or None = None

Noise-model vectors with one value per image. Scales must be finite and positive; zeros must be finite. See Notes for units.

zeros : array - like or None = None

Noise-model vectors with one value per image. Scales must be finite and positive; zeros must be finite. See Notes for units.

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

combined : (ndarray, shape(*spatial))

Per-output mean or median after applying the input mask, finite-value filtering, and this rejection algorithm.

Notes

Let c be the cenfunc center of the finite, unmasked values, g the gain, r the read noise, and q the fractional sensitivity noise. For image i, the CCD model is::

S_i = max(0, s_i * (c + z_i))
d_i = sqrt(max((r/g)**2, v_floor) + S_i/g + (q*S_i)**2) / s_i

Here v_floor = 1e4 / 3.402823466e38 is IRAF’s read-variance floor. The direct-kernel vectors satisfy raw_i = s_i * (x_i + z_i): x_i is the supplied sample, s_i is scales[i], and z_i is zeros[i] in normalized units. They describe already normalized input; this kernel does not normalize data. For x_i = (raw_i - raw_zero_i) / s_i, pass z_i = raw_zero_i / s_i. An omitted scale or zero vector defaults to ones or zeros, respectively.

Scan each sorted tail inward, rejecting while (c-x_i)/d_i > sigma_lower or (x_i-c)/d_i > sigma_upper, using the two sigma multipliers. Each side stops at its first retained value; with unequal noise, this can shield an interior sample. Recompute c after accepted passes, subject to nkeep, maxrej, and maxiters.

ddof does not affect this noise model. clip_cen selects the center for the unscaled reference noise reported as std; a non-finite reference variance stops the iteration. Rejection residuals use cenfunc. This diagnostic is neither the individual d_i nor the combined-image uncertainty. When requested, low/upp report retained extrema. For derivations and worked examples, see the Rejection Methods tutorial.