pypeit.core.combine module

Module for image combining

pypeit.core.combine.broadcast_lists_of_weights(weights, shapes)

Utility routine to broadcast weights to be the size of image stacks specified by shape

Parameters:

• weights (list) –

  List containing the weights to use. The length of weights must be nimgs, the number of images that are being combined. The options for the date type/shape for the individual elements of weights are:

  • float: a single weight per image in the stack

  • numpy.ndarray with shape (nspec,): wavelength dependent weights per image in the stack

  • numpy.ndarray with shape (nspec, nspat): weights input with the shape of each image stack and will be simply be returned

• shapes (list) – List with length of nimgs containing the tuples which are the shapes (nspec, nspat) of each image in the stack that should have their weights broadcast.

Returns:

weights_list – Weight images where each image in the list has shape that was input via the shapes input parameter.

Return type:

list of numpy.ndarray objects

pypeit.core.combine.broadcast_weights(weights, shape)

Utility routine to broadcast weights to be the size of image stacks specified by shape

Parameters:

• weights (numpy.ndarray) –

  Weights to use. Options for the shape of weights are:

  • (nimgs,) – a single weight per image in the stack

  • (nimgs, nspec) – wavelength dependent weights per image

  • (nimgs, nspec, nspat) – weights already have the shape of the image stack and are simply returned

• shape (tuple) – Shape of the image stacks for weighted coadding. This is either (nimgs, nspec) for 1d extracted spectra or (nimgs, nspec, nspat) for 2d spectrum images

Returns:

Weights for the stack images with output shape described in the Args above.

Return type:

numpy.ndarray

pypeit.core.combine.img_list_error_check(sci_list, var_list)

Utility routine for dealing with lists of image stacks for weighted_combine(). This routine checks that the images sizes are correct and routines the shape of the image stacks.

Parameters:

• sci_list (list) – List of float numpy.ndarray images (each being an image stack with shape (nimgs, nspec, nspat)) which are to be combined with the weights, mask, and possibly sigma clipping.

• var_list (list) – List of float numpy.ndarray variance images (each being an image stack with shape (nimgs, nspec, nspat)) which are to be combined with proper erorr propagation, i.e. using the weights squared, mask, and possibly sigma clipping.

Returns:

shape – The shapes of the image stacks – (nimgs, nspec, nspat)

Return type:

tuple

pypeit.core.combine.weighted_combine(weights, sci_list, var_list, inmask_stack, sigma_clip=False, sigma_clip_stack=None, sigrej=None, maxiters=5)

Combine multiple sets of images, all using the same weights and mask.

The multiple sets of images and variances to combine must have the same shape — (nimgs, nspec, nspat) — and this shape must match the provided single mask set (inmask_stack). The provided weights are broadcast to the necessary shape (see below), where one can provide one weight per image, one weight per image spatial coordinate (i.e., wavelength-dependent weights), or independent weights for each pixel.

Optionally, the image stack can be sigma-clipped by setting sigma_clip=True. If sigma-clipping is requested and no sigma-rejection thresholds are provided (sigrej is None), the sigma-rejection thresholds are set automatically depending on the number of images to combine. The default rejection thresholds are 1.1, 1.3, 1.6, 1.9, or 2.0 for, respectively, 3, 4, 5, 6, or \(\geq 7\) images. Sigma-clipping cannot be performed if there are fewer than 3 images. The pixel rejection is based on a single image stack provided by sigma_clip_stack, which does not necessarily need to be any of the image stacks provided by sci_list. Pixels rejected by sigma-clipping the sigma_clip_stack array are applied to all image stacks in sci_list.

The combined images are collected into the returned image list, where the order of the list is identical to the input sci_list. The returned mask and pixel accounting array is identical for all stacked images.

Parameters:

• weights (numpy.ndarray) –

  Weights to use. Options for the shape of weights are:

  • (nimgs,): a single weight per image in the stack

  • (nimgs, nspec): wavelength dependent weights per image in the stack

  • (nimgs, nspec, nspat): weights input with the shape of the image stack

  Note that the weights are distinct from the mask, which is dealt with via the inmask_stack argument, meaning there should not be any weights that are set to zero (although in principle this would still work).

• sci_list (list) – List of floating-point numpy.ndarray image groups to stack. Each image group must have the same shape: (nimgs, nspec, nspat).

• var_list (list) – List of floating-point numpy.ndarray images providing the variance for each image group. The number of image groups and the shape of each group must match sci_list. These are used to propagate the error in the combined images.

• inmask_stack (numpy.ndarray, boolean, shape (nimgs, nspec, nspat)) – Good-pixel mask (True=Good, False=Bad) for the input image stacks. This single group of good-pixel masks is applied to all input image groups.

• sigma_clip (bool, optional, default = False) – Combine with a mask by sigma clipping the image stack. Stacks can only be sigma-clipped if there are 3 or more images.

• sigma_clip_stack (numpy.ndarray, float, shape (nimgs, nspec, nspat), optional, default = None) – The image stack to be used for the sigma clipping. For example, if the list of images to be combined with the weights is [sciimg_stack, waveimg_stack, tilts_stack] and you want to clip based on sciimg_stack, you would set sigma_clip_stack=sciimg_stack.

• sigrej (int, float, optional, default = None) – Rejection threshold for sigma clipping. If None and sigma_clip is True, the rejection threshold is set based on the number of images to combine; see above. This value is passed directly to astropy.stats.SigmaClip as its sigma parameter.

• maxiters (int, optional, default=5) – Maximum number of rejection iterations; see astropy.stats.SigmaClip.

Returns:

• sci_list_out (list) – The list of ndarray float combined images with shape (nspec, nspat).

• var_list_out (list) – The list of ndarray propagated variance images with shape (nspec, nspat).

• gpm (boolean numpy.ndarray, shape (nspec, nspat)) – Good pixel mask for combined image (True=Good, False=Bad).

• nused (integer numpy.ndarray, shape (nspec, nspat)) – Number of pixels combined at each location in the stacked images.