Combiner

Combiner(arr, mask=None, *, copy=True, validate=True)

Stateful pipeline holder for (scale/zero, reject, combine) workflows.

Use Standard Combiner with rejectors=... and diagnostics=None for production reductions. Use Chained Combiner calls when you need retained masks, rejection diagnostics, or step-by-step inspection.

Parameters

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

Image stack. Accepted public input 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. Combiner is intended for workflows that may apply masking, rejection, zero, or scale. Inputs with more than 3 dimensions are flattened to (N, prod(spatial), 1) for internal processing; all outputs (from :meth:combine and :attr:last_reject) are reshaped back to the original trailing dimensions.

mask : ndarray of bool = None

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

copy : bool = True

If True, copy arr and mask into owned workspace arrays. If False, keep references to normalized inputs when possible.

validate : bool = True

If True, validate shape, dtype, mask compatibility, and contiguity. If False, callers must provide a 3-D contiguous stack with a dtype accepted by the compiled kernels and a same-shape boolean mask.

Attributes

arr : ndarray

Working stack (after any zero_scale), always 3-D internally. Owned, may be modified.

mask : ndarray of bool or None

Combined mask (union of input, threshold, and rejection masks), 3-D. None until one is set.

mask_thresh : ndarray of bool or None

Threshold mask from :meth:threshold, shaped like the original input stack. None until thresholding has been applied.

last_reject : tuple or None

(mask_rej, std, low, upp, nit, output_flags) from the most recent :meth:reject call, shaped to match the original trailing spatial dimensions. If grow was used, mask_rej is the grown rejection mask; low, upp, nit, and std still describe the underlying clipping calculation, and output_flags bit 16 marks output elements where growth added at least one rejected sample. None until :meth:reject has been called.

last_sample_flags : ndarray of uint8 or None

Stack-shaped per-sample flags from the most recent :meth:reject call made with diagnostics="full". This is stage-local like :attr:last_reject; samples already masked before the rejection step are marked with sample bit 32 rather than replaying earlier-stage causes. Iterative sigma/CCD/linear clipping can also mark samples tentatively rejected and then restored by nkeep or maxrej.

Methods

Name	Description
combine	Combine the (possibly masked) stack along axis 0 and return the result.
copy	Return an independent copy of this pipeline state.
reject	Apply a rejector, OR-merging its mask into self.mask.
threshold	Mask values outside inclusive threshold bounds.
variance	Return variance of final valid values along axis 0.
zero_scale	Apply per-image offset / scale: (arr - zero) / scale.

combine

Combiner.combine(
    method='mean',
    *,
    weight=None,
    ddof=0,
    zero=None,
    scale=None,
    zero_to_0th=True,
    scale_to_0th=True,
    zero_sigclip_kwargs=None,
    scale_sigclip_kwargs=None,
    thresholds=None,
    rejectors=None,
    full=False,
    diagnostics=None,
)

Combine the (possibly masked) stack along axis 0 and return the result.

Masked pixels are NaN-filled before combining so the kernels skip them. Passing combine-call thresholds or rejectors with diagnostics=None is the Standard Combiner style; supported single-rejector mean/median calls can use fused kernels without storing rejection diagnostics. Calling :meth:threshold, :meth:zero_scale, and :meth:reject before :meth:combine is the Chained Combiner style; it preserves masks and rejection diagnostics for inspection. Since Combiner works on its normalized workspace, lmedian here follows that workspace dtype. Integer-preserving pure lower median is available through :func:imcombiners.kernels.lmedian or pure :func:imcombiners.ndcombine calls.

Parameters

method : str = 'mean'

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

weight : ndarray of shape (N,) = None

Required for method="weighted_average".

ddof : int = 0

Delta degrees of freedom for method="variance". Ignored by other combine methods.

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

Per-plane values to subtract before scaling, after any thresholds passed to this combine call and before combine-call rejection. Accepts the same forms as :meth:zero_scale.

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

Per-plane values used as divisors after zero subtraction. Accepts the same forms as :meth:zero_scale.

zero_to_0th : bool = True

Whether per-plane zero or scale values are rebased to the zeroth frame before application, matching :meth:zero_scale defaults.

scale_to_0th : bool = True

Whether per-plane zero or scale values are rebased to the zeroth frame before application, matching :meth:zero_scale defaults.

zero_sigclip_kwargs : dict or None = None

Keyword arguments used only when zero or scale is a sigma-clipped statistic alias.

scale_sigclip_kwargs : dict or None = None

Keyword arguments used only when zero or scale is a sigma-clipped statistic alias.

thresholds : tuple or sequence of tuple = None

Inclusive threshold bounds to apply before any rejectors passed to this combine call. Passing these to combine does not mutate the combiner unless a diagnostics level is requested. Combine-call zero/scale follows these thresholds.

rejectors : Rejector or sequence of Rejector = None

Rejection steps to apply as part of this combine call. With diagnostics=None, a single supported rejector may use a fused output-only kernel and no rejection diagnostics are stored.

full : bool = False

Legacy alias for diagnostics="simple".

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

Diagnostic level for this combine call. None returns only the combined image without mutating state. "simple" applies thresholds/rejectors to this combiner and retains last_reject. "full" also records sample_flags for the most recent rejection step.

Returns

combined : (ndarray, shape(*spatial))

Combined image, shaped to match the trailing spatial dimensions of the array passed to :meth:__init__.

copy

Combiner.copy()

Return an independent copy of this pipeline state.

Returns

combiner : Combiner

New combiner with copied arr and mask. last_reject is shared by reference because it is diagnostic data from a completed step.

reject

Combiner.reject(rejector, *, grow=None, diagnostics='simple')

Apply a rejector, OR-merging its mask into self.mask.

rejector is any :class:~imcombiners._rejectors.Rejector subclass (SigClip, CcdClip, LinearClip, MinMaxClip, PClip). If grow is not None, the rejection mask is grown spatially within each input plane before it is merged into the running mask. After a rejection step, self.mask_rej.sum(axis=0) is the number rejected by that step at each output element, including any grown samples. The number actually used by later combine calls is np.sum(np.isfinite(self.arr) & ~self.mask, axis=0) after all input and rejection masks have been merged.

Parameters

rejector : Rejector

Rejection object to apply.

grow : float or None = None

Non-negative radius in pixels used to grow this rejection mask over the original spatial axes. Axis 0 is the stack axis and is never grown across. None disables mask growth and avoids the extra calculation.

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

Rejection diagnostic level. None and "simple" keep the current last_reject products. "full" also records stack-shaped sample_flags for this rejection step.

Returns

combiner : Combiner

This object, after updating mask and last_reject.

threshold

Combiner.threshold(low=-np.inf, upp=np.inf)

Mask values outside inclusive threshold bounds.

Thresholding is a pre-rejection mask stage. Values survive when low <= value <= upp; values below low or above upp are recorded in :attr:mask_thresh and OR-merged into the running mask. Later zero_scale statistics, rejection, and combination ignore these thresholded pixels.

A common CCD-image pattern is low=0 to remove bad/cold pixels and upp=satlevel or upp=0.99 * satlevel to remove saturated or near-saturated pixels before they influence normalization or rejection.

Parameters

low : float = -np.inf

Inclusive lower and upper retained-value bounds.

upp : float = -np.inf

Inclusive lower and upper retained-value bounds.

Returns

combiner : Combiner

This object, after updating mask and mask_thresh.

variance

Combiner.variance(ddof=1, return_mean=False)

Return variance of final valid values along axis 0.

Valid values are finite inputs not masked by the input mask and not rejected by previous :meth:reject calls. This is equivalent to::

arr_eff = np.where(mask | rejected, np.nan, stack)
var = np.nanvar(arr_eff, axis=0, ddof=ddof)

Parameters

ddof : int = 1

Delta degrees of freedom. Pixels with nvalid <= ddof return NaN. Default is 1, i.e., Sample variance. Use ddof=0 for population variance.

return_mean : bool = False

If True, also return the per-pixel mean computed from the same final valid values and the same Rust accumulation pass.

Returns

variance : (ndarray, shape(*spatial))

Per-pixel variance. Use np.sqrt(var) if an error or standard-deviation map is needed.

mean : (ndarray, shape(*spatial))

Returned only when return_mean=True.

zero_scale

Combiner.zero_scale(
    zero=None,
    scale=None,
    *,
    zero_to_0th=True,
    scale_to_0th=True,
    zero_sigclip_kwargs=None,
    scale_sigclip_kwargs=None,
)

Apply per-image offset / scale: (arr - zero) / scale.

Either or both may be None. Modifies self.arr in place and returns self for chaining.

Parameters

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

Per-plane values to subtract before scaling. Array-like inputs must be scalar or length N. Strings select a per-plane statistic: plain ("mean", "median", "sum", "min", "max" plus 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 and must return a scalar. Current masks, including threshold masks, are applied before string statistics are computed.

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 before applying them. 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 before applying them. 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.

Returns

combiner : Combiner

This object, after updating its working stack.