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,
    diagnostics=None,
    sigscale=0.1,
    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 : {'mean', 'median', 'lmedian', 'sum', 'min', 'max', 'variance'} = 'mean': Combine method. Supported aliases are "mean", "average", "avg", "median", "med", "lmedian", "lmed", "sum", "min", "max", "variance", and "var".
reject : {'minmax', 'pclip', 'sigclip', 'ccdclip'} or None = None: 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'} or None = None: 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 read noise in electrons, used by "ccdclip".
gain : float = 1.0: CCD gain in electrons per DN (ADU), used by "ccdclip". Must be finite and positive when validation is enabled.
snoise : float = 0.0: Fractional sensitivity-noise coefficient used by "ccdclip". It models multiplicative uncertainty, such as flat-field noise, through the (snoise * signal)^2 variance term.
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: Optional per-plane weights for mean/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 expands all entries in the returned rejection mask, including input masks, threshold exclusions, and non-finite samples.
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.
sigscale : float = 0.1: IRAF scale gate for "ccdclip" noise corrections. Resolved per-image zero/scale vectors are used only when a scale differs from one by more than sigscale; 0.0 disables the correction.
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". 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 retained extrema before growth, not the clipping thresholds. mask_rej.sum(axis=0) counts all marked samples, including prior masks, non-finite inputs, and growth. Use sample_flags with full diagnostics to distinguish causes. 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 clipping spread for sigma clipping and the reference noise for CCD clipping, not the uncertainty of the combined image.
: 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.