clip_and_stack

The purpose of the clip_and_stack utility is to combine a set of input images into a single master frame.

Before combining the frames, any outlying pixel values found in the individual frames to be stacked are ‘clipped’. These outlying pixels are identified as those with a value straying too far (defined by the recipe parameter stacked-clipping-sigma) from the ‘typical’ pixel value.

Using the median pixel value as the ‘typical’ value and the median absolute deviation (MAD) as a proxy for the standard deviation, we can accurately identify rogue pixels. For any given set of pixel values:

\[ MAD = \frac{1}{N}\sum_{i=0}^N |x_i - \text{median}(x)|. \]

The clipping is done iteratively so newly found deviant pixels are masked, median values are recalculated and clipping repeated. The iterative process stops whenever either no more bad-pixels are to be found or the maximum number of iterations has been reached (defined by the recipe parameter stacked-clipping-iterations).

After the clipping has been completed individual frames are mean-combined, ignoring pixels in the individual bad-pixel masks. If a pixel is flagged as ‘bad’ in all individual masks it is added to the combined frame bad-pixel mask.

Fig. 54 The algorithm used whenever a set of images is to be combined into a single master frame. This utility is used repeatedly throughout the pipeline.

Utility API

clip_and_stack(frames, recipe, ignore_input_masks=False, post_stack_clipping=True)[source]

mean combine input frames after sigma-clipping outlying pixels using a median value with median absolute deviation (mad) as the deviation function

Key Arguments:

  • frames – an ImageFileCollection of the frames to stack or a list of CCDData objects

  • recipe – the name of recipe needed to read the correct settings from the yaml files

  • ignore_input_masks – ignore the input masks during clip and stacking?

  • post_stack_clipping – allow cross-plane clipping on combined frame. Clipping settings in setting file. Default True.

Return:

  • combined_frame – the combined master frame (with updated bad-pixel and uncertainty maps)

Usage:

This snippet can be used within the recipe code to combine individual (using bias frames as an example):

combined_bias_mean = self.clip_and_stack(
    frames=self.inputFrames, recipe="soxs_mbias", ignore_input_masks=False, post_stack_clipping=True)