ndcombine

ndcombine(
    arr,
    mask=None,
    thresholds=None,
    combine='mean',
    reject=None,
    sigma=(3.0, 3.0),
    cenfunc='median',
    clip_cen=None,
    maxiters=5,
    ddof=0,
    nkeep=1,
    maxrej=None,
    n_minmax=(1, 1),
    rdnoise=0.0,
    gain=1.0,
    snoise=0.0,
    pclip=-0.5,
    zero=None,
    scale=None,
    zero_to_0th=True,
    scale_to_0th=True,
    zero_sigclip_kwargs=None,
    scale_sigclip_kwargs=None,
    weight=None,
    revert_on_nkeep=True,
    grow=None,
    full=False,
    diagnostics=None,
    scale_ref=1.0,
    zero_ref=0.0,
    validate=True,
)

Combine an image stack with optional normalization and rejection.

This is the compact ndcombine() wrapper for call sites that prefer one function over an explicit :class:Combiner workflow. A pure combine="lmedian" or combine="lmed" call with no mask, rejection, zero, scale, or weight preserves accepted integer input dtypes. Any path that needs masking, rejection, normalization, or weights uses the normal floating workspace.

Parameters

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

Image stack. Accepted dtypes are uint8, uint16, int16, int32, float32, and float64. uint8, uint16, and int16 are promoted to float32; int32 is promoted to float64; float32 and float64 are preserved. Other dtypes, including int64 and float128, are not silently cast. If your data use an unsupported dtype, cast them explicitly before calling ndcombine; there is no full-precision int64 combine path because the package does not provide a float128 workspace. Inputs with more than 3 dimensions are flattened internally; all outputs are reshaped back to the original trailing spatial dimensions.

mask : ndarray of bool = None

Input mask with the same shape as arr; True means masked.

thresholds : tuple of float or None = None

Inclusive lower and upper retained-value bounds applied before zero/scale, rejection, and combination. Values below the lower bound or above the upper bound are recorded in mask_thresh when diagnostics are requested and are treated as masked for later stages. For CCD images, a typical choice is thresholds=(0, satlevel) to remove bad/cold pixels and saturated pixels, or thresholds=(0, 0.99 * satlevel) to also exclude near-saturated pixels that are usually not useful for normalization, rejection, or final combination.

combine : str = 'mean'

Combine method. Supported aliases are "mean", "average", "avg", "median", "med", "lmedian", "lmed", "sum", "min", "max", "variance", "var", "weighted_average" and "wvg".

reject : ('minmax', 'pclip', 'sigclip', 'ccdclip') = "minmax"

Rejection algorithm to apply before combining. None disables rejection.

sigma : float or tuple of float = (3.0, 3.0)

Lower and upper sigma thresholds for "sigclip" and "ccdclip".

cenfunc : ('median', 'lmedian', 'mean') = "median"

Center estimator used by iterative rejection.

clip_cen : ('median', 'lmedian', 'mean') = "median"

Center used to compute the spread for iterative rejection. None uses cenfunc. lmedian accepts the alias lmed.

maxiters : int = 5

Maximum number of rejection iterations.

ddof : int = 0

Delta degrees of freedom for spread estimates and for combine="variance". Variance is computed from final valid values after input mask and rejection are applied.

nkeep : int = 1

Minimum number of unmasked values to preserve at each pixel. 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.

n_minmax : tuple of int or float = (1, 1)

Number or fraction of low and high values rejected by "minmax". Values greater than or equal to 1 are frame counts; values in [0, 1) are fractions of the original stack size.

rdnoise : float = 0.0

CCD noise-model parameters used by "ccdclip". gain must be finite and positive when validation is enabled.

gain : float = 0.0

CCD noise-model parameters used by "ccdclip". gain must be finite and positive when validation is enabled.

snoise : float = 0.0

CCD noise-model parameters used by "ccdclip". gain must be finite and positive when validation is enabled.

pclip : float = -0.5

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

zero : array-like, str, callable, or None = None

Per-plane values to subtract before scaling. Strings select per-plane statistics: plain ("mean", "median", "sum", "min", "max" and common aliases) or sigma-clipped ("sigclip_mean" / "mean_sc" and "sigclip_median" / "median_sc" / "med_sc", using sigma=3, maxiters=5 by default). Callables are evaluated once per image plane.

scale : array-like, str, callable, or None = None

Per-plane values used as divisors after zero subtraction. The same string and callable rules as zero apply, including the sigma-clipped variants. Scale values must be finite and non-zero when validation is enabled.

zero_to_0th : bool = True

If True, subtract the first zero value from all zero values. True is the default behavior to follow IRAF. Setting this to True makes only a small subtraction happen, so real pixel values change only slightly and Poisson-noise calculations remain well behaved.

scale_to_0th : bool = True

If True, divide all scale values by the first scale value. True is the default behavior to follow IRAF. Setting this to True makes only a small division happen, so real pixel values change only slightly and Poisson-noise calculations remain well behaved.

zero_sigclip_kwargs : dict or None = None

Keyword arguments used only when zero or scale is a sigma-clipped statistic alias such as "mean_sc" or "med_sc". Supported keys are sigma, maxiters, cenfunc, clip_cen, and ddof.

scale_sigclip_kwargs : dict or None = None

Keyword arguments used only when zero or scale is a sigma-clipped statistic alias such as "mean_sc" or "med_sc". Supported keys are sigma, maxiters, cenfunc, clip_cen, and ddof.

weight : (ndarray, shape(N)) = None

Per-plane weights required by weighted-average combine.

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.

grow : float or None = None

Non-negative 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. Growth applies only to samples rejected by reject, not to input masks or threshold masks.

full : bool = False

Legacy alias for diagnostics="simple". Prefer diagnostics.

diagnostics : (None, 'simple', 'full') = None

Diagnostic product level. None returns only the combined image and keeps the fused output-only fast paths. "simple" returns the combined image plus the existing per-output-element diagnostics. "full" returns the "simple" products plus a stack-shaped uint8 sample_flags array.

scale_ref : float = 1.0

Reference scale and zero-point parameters for "ccdclip".

zero_ref : float = 1.0

Reference scale and zero-point parameters for "ccdclip".

validate : bool = True

If True, validate public-boundary inputs. If False, callers must provide arrays with correct dimensionality, contiguity, dtype, mask shape, finite scale values, and valid rejection parameters.

Returns

combined : (ndarray, shape(*spatial))

Combined image, returned when diagnostics is None.

: combined, mask_rej, mask_thresh, std, low, upp, nit, output_flags : tuple

Returned when diagnostics="simple" or legacy full=True. Rejection diagnostics are None when reject is None; mask_thresh is None when thresholds is None. mask_rej and mask_thresh have shape (N, *spatial); low, upp, nit, and output_flags have shape (*spatial,). std has shape (*spatial,) for sigma/CCD clipping and is None for rejection algorithms without a spread diagnostic. low and upp are inclusive rejection bounds: values equal to a bound are retained. mask_rej.sum(axis=0) is the number rejected by that rejection step, including any samples added by grow. The number actually used for combining is the count of finite samples after input mask and rejection mask are applied. output_flags bit 16 marks output elements where growth added at least one rejected sample; low, upp, nit, and std still describe the underlying clipping calculation. std is the per-pixel spread used by sigma/CCD clipping, and None for rejection algorithms without a spread diagnostic.

: combined, …, sample_flags : tuple

Returned when diagnostics="full". sample_flags has dtype uint8 and shape (N, *spatial). Its bits are 1=input mask/BPM, 2=non-finite, 4=threshold mask, 8=final algorithm rejection, 16=added by grow, and 32=already masked before this rejection step; iterative sigma/CCD clipping can also set 64=tentatively rejected then restored by nkeep and 128=tentatively rejected then restored by maxrej. The per-output-element output_flags map uses a separate bit namespace.