pypeit.coadd2d module

Module for performing two-dimensional coaddition of spectra.

class pypeit.coadd2d.CoAdd2D(spec2d, spectrograph, par, det=1, only_slits=None, exclude_slits=None, sn_smooth_npix=None, bkg_redux=False, find_negative=False, show=False, show_peaks=False, debug_offsets=False, debug=False)

Bases: object

Main driver for two-dimensional spectral coaddition.

This class coordinates loading a set of reduced spec2d products, selecting the slits or orders to combine, determining relative offsets and weights among the input exposures, rectifying the input images onto a common coordinate grid, and reducing the resulting pseudo-image into final coadded products.

The base class provides the shared machinery used by both multislit and echelle coadds. Subclasses specialize the handling of reference objects, offset determination, weighting, and wavelength-grid construction for their respective reduction modes.

Notes

The overall workflow is:

1. Load the per-exposure data products into a CoAdd2dStack.

2. Determine the subset of slits or orders that are valid for coaddition.

3. Compute relative offsets among the exposures.

4. Compute the weights used during coaddition.

5. Rectify and coadd the input images slit-by-slit or order-by-order.

6. Build a pseudo-image from the coadd outputs.

7. Run the extraction and bookkeeping steps needed to write the coadded products to disk.

See also

MultiSlitCoAdd2D

Multislit and longslit implementation.

EchelleCoAdd2D

Echelle implementation.

_get_weights(indx=None)

Return the weights appropriate for a given slit or order.

Parameters:

indx (int, optional) – Slit or order index for which to return the weights.

Returns:

List of weights, one per exposure.

Return type:

list

check_input(input, type)

Normalize a coadd configuration input to an internal representation.

Parameters:

• input (object) – User-supplied value to validate and normalize.

• type (str) – Expected input type or semantic category.

Returns:

Validated and normalized value.

Return type:

object

Raises:

PypeItError – Raised if the input does not conform to the expected type or format.

coadd(interp_dspat=True)

Perform the two-dimensional coaddition.

This routine loops over the selected good slits or orders, rectifies the input images for each one onto a common coordinate system, and combines the resulting rebinned images using the previously determined offsets and weights.

Parameters:

interp_dspat (bool, optional) – If True, interpolate the spatial sampling when constructing the coadd grids.

Returns:

List of per-slit or per-order coadd products. Each element contains the data needed by create_pseudo_image() to build the final pseudo-image.

Return type:

list

Notes

The exact contents of the returned list depend on the pypeline-specific coaddition implementation, but each entry represents one coadded slit or order.

compute_offsets()

Determine the relative offsets among the input exposures.

Notes

This base-class method is intended to be overridden by subclasses that define how offsets are determined for specific reduction modes.

compute_weights()

Determine the exposure weights used in the coadd.

Notes

This base-class method is intended to be overridden by subclasses that define how weights are determined for specific reduction modes.

create_pseudo_image(coadd_list)

Assemble the per-slit or per-order coadds into a pseudo-image.

Parameters:

coadd_list (list) – List of coadded slit or order products produced by coadd().

Returns:

Dictionary containing the pseudo-image and associated metadata needed for downstream reduction and output writing.

Return type:

dict

Notes

The pseudo-image is the rectified, stacked image representation consumed by the later extraction steps.

Todo

THIS UNDOCUMENTED CODE PROBABLY SHOULD GENERATE AND RETURN STANDARD PYPEIT OBJCTS INSTEAD OF SOME UNDEFINED DICT

static default_basename(spec2d_files)

Construct the default basename for a coadded spec2d product.

Parameters:

spec2d_files (list) – List of input spec2d filenames.

Returns:

Basename used when writing the coadded output products.

Return type:

str

static default_par(spectrograph, inp_cfg=None, det=None, only_slits=None, exclude_slits=None)

Construct the default parameter set for two-dimensional coaddition.

Parameters:

• spectrograph (str) – PypeIt spectrograph name.

• inp_cfg (dict, optional) – Existing configuration dictionary to update.

• det (list, str, or tuple, optional) – Detector or mosaic selection to place in the returned configuration.

• only_slits (list or str, optional) – Slit or order identifiers to include in the coadd.

• exclude_slits (list or str, optional) – Slit or order identifiers to exclude from the coadd.

Returns:

Dictionary with the default coadd2d configuration entries.

Return type:

dict

get_brightest_obj(specobjs_list, spat_ids)

Identify the brightest reference object in each exposure.

Parameters:

• specobjs_list (list) – List of SpecObjs containers, one per exposure.

• spat_ids (numpy.ndarray) – Slit or order identifiers used to constrain the object selection.

Returns:

Information describing the selected brightest objects.

Return type:

tuple

Notes

This base-class method is intended to be overridden by subclasses because the object identifiers differ between multislit and echelle reductions.

classmethod get_instance(spec2dfiles, spectrograph, par, det=1, only_slits=None, exclude_slits=None, sn_smooth_npix=None, bkg_redux=False, find_negative=False, show=False, show_peaks=False, debug_offsets=False, debug=False)

Instantiate the appropriate CoAdd2D subclass for a spectrograph.

The subclass is selected by matching the spectrograph pypeline name to a child class of CoAdd2D.

Parameters:

• spec2dfiles (list) – List of input spec2d files or already-instantiated Spec2DObj objects.

• spectrograph (Spectrograph) – Spectrograph object describing the instrument and reduction mode.

• par (ParSet) – Parameter set controlling the coaddition.

• det (int or tuple, optional) – Detector number or detector mosaic identifier to process.

• only_slits (list, optional) – List of slit or order identifiers to include.

• exclude_slits (list, optional) – List of slit or order identifiers to exclude.

• sn_smooth_npix (int, optional) – Number of pixels used when smoothing S/N estimates for weight determination.

• bkg_redux (bool, optional) – Flag indicating that the science images have already been background subtracted.

• find_negative (bool, optional) – If True, search for and mask negative traces produced by image differencing.

• show (bool, optional) – If True, display intermediate results.

• show_peaks (bool, optional) – If True, show QA plots for peak finding.

• debug_offsets (bool, optional) – If True, show QA plots related to offset determination.

• debug (bool, optional) – If True, enable additional debug output.

Returns:

Instance of the subclass appropriate for the requested reduction mode.

Return type:

CoAdd2D

get_maskdef_dict(slit_idx, ref_trace_stack)

Collect mask-design metadata for a slit in the coadd.

Parameters:

• slit_idx (int) – Index of the slit in the uncoadded frames.

• ref_trace_stack (numpy.ndarray) – Stack of reference traces about which the images are rectified and coadded. The shape is (nspec, nimgs).

Returns:

Dictionary containing the mask-design metadata associated with the slit, including identifiers, object positions, slit centers, and design-table information.

Return type:

dict

Notes

This base-class method is overridden by subclasses.

get_wave_grid()

Construct the wavelength grid used for the two-dimensional coadd.

Returns:

• wave_grid (numpy.ndarray) – New wavelength grid, not masked

• wave_grid_mid (numpy.ndarray) – New wavelength grid evaluated at the centers of the wavelength bins, that is this grid is simply offset from wave_grid by dsamp/2.0, in either linear space or log10 depending on whether linear or (log10 or velocity) was requested. For iref or concatenate the linear wavelength sampling will be calculated.

• dsamp (float) – The pixel sampling for wavelength grid created.

Notes

The exact grid construction depends on the reduction mode and is controlled by wave_method().

good_slitindx(only_slits=None, exclude_slits=None)

Determine which slits or orders are eligible for two-dimensional coaddition.

A slit or order is considered good only if it is not masked by the common bitmask across the full set of uncoadded exposures and it satisfies the user-supplied inclusion or exclusion criteria.

Parameters:

• only_slits (list, optional) – Slit or order identifiers to include. If provided, only these identifiers are considered good.

• exclude_slits (list, optional) – Slit or order identifiers to exclude. Ignored if only_slits is provided.

Returns:

One-dimensional array of indices selecting the good slits or orders in the uncoadded stack.

Return type:

numpy.ndarray

handle_reference_obj()

Interpret the user-supplied reference-object selection.

Notes

This base-class method is overridden by subclasses.

load_coadd2d_stacks(spec2d, chk_version=False)

Load the input spec2d products into a CoAdd2dStack.

Parameters:

• spec2d (list) – List of input spec2d filenames or Spec2DObj objects.

• chk_version (bool, optional) – If True, check the version compatibility of the loaded files.

Returns:

Dataclass containing the stacked science images, masks, coordinate images, slit definitions, exposure times, and related metadata needed for coaddition.

Return type:

CoAdd2dStack

Notes

If the exposure times differ among the inputs beyond the allowed tolerance, the science, sky, and inverse-variance images are rescaled to a common effective exposure time before being stored in the returned stack.

offset_slit_cen(slitid, offsets)

Return the slit center traces shifted by the exposure offsets.

Parameters:

• slitid (int) – Slit or order identifier.

• offsets (array-like) – Offsets, in pixels, to apply to the slit centers for each exposure.

Returns:

Stack of shifted slit-center traces with one column per exposure.

Return type:

numpy.ndarray

static offsets_report(offsets, pixscale, offsets_method)

Log a summary of the offsets used for coaddition.

Parameters:

• offsets (array-like) – Offsets, in pixels, applied to the input exposures.

• pixscale (float) – Pixel scale used to convert the offsets to arcseconds for reporting.

• offsets_method (str) – Description of how the offsets were determined.

optimal_weights(uniq_obj_id, order=None, weight_method='auto')

Compute the optimal exposure weights for a set of reference objects.

The routine extracts the relevant one-dimensional spectra for the supplied reference-object identifiers and passes them to pypeit.core.coadd.sn_weights() to determine the weighting of each input exposure.

Parameters:

• uniq_obj_id (numpy.ndarray) – Array of unique object identifiers, one per exposure, used to select the reference object for the weight calculation.

• order (int, optional) – Echelle order to use when computing the weights. Ignored for multislit reductions.

• weight_method ({'auto', 'constant', 'uniform', 'wave_dependent', 'relative', 'ivar'}, optional) – Weighting algorithm passed to pypeit.core.coadd.sn_weights().

Returns:

• rms_sn (numpy.ndarray) – Array of root-mean-square S/N value for each input spectra. Shape = (nexp,)

• weights (list) – List of len(nexp) containing the signal-to-noise squared weights to be applied to the spectra. This output is aligned with the vector (or vectors) provided in waves which is read in by this routine, i.e. it is a list of arrays of type numpy.ndarray with the same shape as those in waves.

Notes

This method is used by both the multislit and echelle subclasses when the weights are determined from the brightest detected reference object.

static output_paths(spec2d_files, par, coadd_dir=None)

Construct and create the science and QA output directories for coadd2d.

Parameters:

• spec2d_files (list) – List of input spec2d filenames. The parent reduction directory is inferred from these paths if coadd_dir is not provided.

• par (PypeItPar) – Full parameter set. The routine uses and may update the values in par['rdx']['scidir'] and par['rdx']['qadir'].

• coadd_dir (str, optional) – Root directory for the coadd2d output. If None, the parent reduction directory inferred from spec2d_files is used.

Returns:

• sci_output_dir (str) – Path to the science output directory

• qa_output_dir (str) – Path to the QA output directory.

Notes

The required directories are created if they do not already exist.

reduce(pseudo_dict, show=False, clear_ginga=True, show_peaks=False, show_skysub_fit=False, basename=None)

Reduce a coadded pseudo-image into final science products.

Parameters:

• pseudo_dict (dict) – Dictionary describing the pseudo-image and associated metadata, typically returned by create_pseudo_image().

• show (bool, optional) – If True, display intermediate reduction results.

• clear_ginga (bool, optional) – If True, clear the Ginga display before showing new content.

• show_peaks (bool, optional) – If True, show QA plots related to object-finding peaks.

• show_skysub_fit (bool, optional) – If True, show QA for the sky-subtraction fit.

• basename (str, optional) – Basename to use when writing the output products.

Returns:

The reduced data products generated from the pseudo-image.

Return type:

tuple

Notes

This method performs the coadd-specific analogue of the standard PypeIt extraction sequence for a single frame.

reference_trace_stack(slitid, offsets=None, uniq_obj_id=None)

Construct the stack of reference traces used for rectification and coaddition.

Parameters:

• slitid (int) – Slit or order identifier.

• offsets (array-like, optional) – Offsets applied to the reference traces for each exposure.

• uniq_obj_id (array-like, optional) – Object identifiers selecting the reference trace in each exposure.

Returns:

Stack of reference traces with one column per exposure.

Return type:

numpy.ndarray

Notes

This base-class method is overridden by subclasses.

static unpack_specobj(spec, spatord_id=None)

Extract trace and S/N information from a SpecObj.

Parameters:

• spec (SpecObj) – Object to unpack.

• spatord_id (int, optional) – Slit spatial identifier or echelle order identifier used to select or validate the object.

Returns:

• flux (numpy.ndarray) – Flux array from the SpecObj

• ivar (numpy.ndarray) – Inverse variance array from the SpecObj

• gpm (numpy.ndarray) – Good pixel mask array from the SpecObj

Notes

This helper provides a common interface for the object-handling code used by the multislit and echelle subclasses.

wave_method()

Return the wavelength-grid construction method used for coadd2d.

Returns:

Name of the wavelength-grid method.

Return type:

str

Notes

This base-class method is overridden by subclasses.

class pypeit.coadd2d.EchelleCoAdd2D(spec2d_files, spectrograph, par, det=1, only_slits=None, exclude_slits=None, sn_smooth_npix=None, bkg_redux=False, find_negative=False, show=False, show_peaks=False, debug_offsets=False, debug=False)

Bases: CoAdd2D

Two-dimensional coaddition driver for echelle reductions.

This subclass implements the echelle-specific handling of reference objects, offsets, weights, and wavelength-grid construction on top of the shared CoAdd2D framework.

Notes

Echelle coadds can be aligned either by user-supplied offsets or by the trace of a selected reference object. Weights may be user supplied, uniform, or derived order-by-order from the brightest reference object.

_get_weights(indx=None)

Determine the exposure weights for an echelle coadd.

This method sets the internal use_weights attribute using either the user-supplied weights, uniform weights, or wavelength-dependent weights computed from the brightest detected reference object.

compute_offsets()

Determine the exposure offsets for an echelle coadd.

The offsets are defined relative to the first exposure and may be either user supplied or derived from the trace of the selected reference object.

compute_weights()

Determine the exposure weights for an echelle coadd.

This method sets the internal use_weights attribute using either the user-supplied weights, uniform weights, or wavelength-dependent weights computed from the brightest detected reference object.

get_brightest_obj(specobjs_list, orders)

Identify the brightest reference object in each echelle exposure.

Parameters:

• specobjs_list (list) – List of SpecObjs containers, one per exposure.

• orders (numpy.ndarray) – Array of order identifiers over which to search for the brightest object.

Returns:

Tuple containing:

• the reference-object echelle fractional-position identifiers for each exposure, and

• the average S/N values of the selected object in each exposure.

Return type:

tuple

handle_reference_obj()

Interpret the echelle reference-object syntax.

Notes

This method parses the user-requested reference object used to compute offsets and weights in echelle coadds.

reference_trace_stack(slitid, offsets=None, uniq_obj_id=None)

Construct the reference-trace stack for an echelle order.

Parameters:

• slitid (int) – Order identifier for which to build the reference traces.

• offsets (list or numpy.ndarray, optional) – Offsets to apply to the slit-center traces, one per exposure.

• uniq_obj_id (list or numpy.ndarray, optional) – Object identifiers selecting the reference trace in each exposure. For echelle reductions, these are ECH_FRACPOS_ID values.

Returns:

List of reference traces, one per exposure, for the requested order.

Return type:

list

Raises:

PypeItError – Raised if neither or both of offsets and uniq_obj_id are provided.

Notes

Two alignment modes are supported:

• offset-based alignment about the slit or order center, and

• object-based alignment about a selected reference trace.

snr_report(snr_bar)

Log an S/N report for the echelle reference object.

Parameters:

snr_bar (numpy.ndarray) – Average S/N values of the selected reference object, one per exposure.

wave_method()

Return the wavelength-grid method used for echelle coadd2d.

Returns:

Name of the wavelength-grid method.

Return type:

str

class pypeit.coadd2d.MultiSlitCoAdd2D(spec2d_files, spectrograph, par, det=1, only_slits=None, exclude_slits=None, sn_smooth_npix=None, bkg_redux=False, find_negative=False, show=False, show_peaks=False, debug_offsets=False, debug=False)

Bases: CoAdd2D

Two-dimensional coaddition driver for multislit and longslit reductions.

This subclass implements the multislit-specific handling of reference objects, offsets, weights, and wavelength-grid construction on top of the shared CoAdd2D framework.

Notes

Multislit coadds can use either user-supplied offsets or offsets derived from a reference object or mask-design information. Weights may be user supplied, uniform, or determined automatically from the brightest detected object.

compute_offsets()

Determine the exposure offsets for a multislit coadd.

The offsets are defined relative to the first exposure and may be supplied by the user, inferred from slitmask-design information, or computed from the brightest detected reference object.

compute_weights()

Determine the exposure weights for a multislit coadd.

This method sets the internal use_weights attribute using either the user-supplied weights, uniform weights, or weights computed from the brightest detected reference object.

get_brightest_obj(specobjs_list, slit_spat_ids)

Identify the brightest reference object in each multislit exposure.

Parameters:

• specobjs_list (list) – List of SpecObjs containers, one per exposure.

• slit_spat_ids (numpy.ndarray) – Array of slit spatial identifiers used to constrain the search.

Returns:

Tuple containing:

• the reference-object SPAT_PIXPOS identifiers for each exposure,

• the corresponding spatial positions,

• the slit SPAT_ID containing the highest-S/N object, and

• the average S/N values for the selected object in each exposure.

Return type:

tuple

get_maskdef_dict(slit_idx, ref_trace_stack)

Collect mask-design metadata for a multislit slit in the coadd.

Parameters:

• slit_idx (int) – Index of the slit in the uncoadded frames.

• ref_trace_stack (numpy.ndarray) – Stack of reference traces about which the images are rectified and coadded. The shape is (nspec, nimgs).

Returns:

Dictionary containing mask-design metadata for the slit.

Return type:

dict

handle_reference_obj()

Interpret the multislit reference-object syntax.

Notes

This method parses the user-requested reference object used to compute offsets and weights in multislit coadds.

reference_trace_stack(slitid, offsets=None, uniq_obj_id=None)

Construct the reference-trace stack for a multislit slit.

Parameters:

• slitid (int) – Slit identifier for which to build the reference traces.

• offsets (list or numpy.ndarray, optional) – Offsets to apply to the slit-center traces, one per exposure.

• uniq_obj_id (list or numpy.ndarray, optional) – Object identifiers. This argument is accepted for interface compatibility but is not used in multislit mode.

Returns:

List of reference traces, one per exposure, for the requested slit.

Return type:

list

snr_report(slitid, spat_pixpos, snr_bar)

Log an S/N report for the multislit reference object.

Parameters:

• slitid (int) – SPAT_ID of the slit containing the reference object.

• spat_pixpos (numpy.ndarray) – Spatial positions of the reference object, one per exposure.

• snr_bar (numpy.ndarray) – Average S/N values of the reference object, one per exposure.

wave_method()

Return the wavelength-grid method used for multislit coadd2d.

Returns:

Name of the wavelength-grid method.

Return type:

str

class pypeit.coadd2d.CoAdd2dStack(specobjs_list, slits_list, slitmask_stack, sciimg_stack, sciivar_stack, skymodel_stack, mask_stack, waveimg_stack, exptime_stack, exptime_coadd, redux_path, detectors, spectrograph, pypeline, maskdef_designtab_list, spat_flexure_list)

Bases: object

CoAdd 2D Stack dataclass

Variables:

• specobjs_list (list) – List of SpecObjs objects, one per exposure, containing the 1D extracted objects associated with the loaded spec2d inputs for the selected detector or mosaic. This list may be empty if matching spec1d files are not available.

• slits_list (list) – List of SlitTraceSet objects, one per exposure, containing the slit or order definitions for the input frames.

• slitmask_stack (list) – List of two-dimensional slit-ID images, one per exposure, produced from the corresponding slits_list entry using slit_img(). Each image labels the detector pixels by slit or order, including any recorded spatial flexure correction.

• sciimg_stack (list) – List of two-dimensional science images, one per exposure. These are the primary input images to be rectified and coadded.

• sciivar_stack (list) – List of two-dimensional inverse-variance images, one per exposure, aligned with sciimg_stack. If the exposure times differ among the input frames, these images are rescaled consistently with the science images before coaddition.

• skymodel_stack (list) – List of two-dimensional sky-model images, one per exposure, aligned with sciimg_stack. These are used when constructing sky- subtracted images and are also rescaled if the exposure times are homogenized.

• mask_stack (list) – List of bad-pixel mask images, one per exposure, containing the raw mask values from the input Spec2DObj instances.

• waveimg_stack (list) – List of two-dimensional wavelength images, one per exposure, giving the wavelength associated with each detector pixel in the corresponding science image.

• exptime_stack (list) – List of exposure times, one per input exposure, read from the primary headers of the input spec2d data.

• exptime_coadd (float) – Reference exposure time adopted for the coadd. This is taken to be the median input exposure time, using the higher of the two middle values for even-length stacks. If the individual exposure times differ by more than the allowed tolerance, the science, sky, and inverse-variance images are rescaled to this effective exposure time before coaddition.

• redux_path (Path) – Reduction path associated with the current coaddition context. At present this is set to the current working directory when the stack is constructed.

• detectors (list) – List of detector or detector-mosaic metadata objects, one per exposure, copied from the loaded Spec2DObj instances. These are later used for bookkeeping and for propagating detector properties into the coadded products.

• spectrograph (str) – Name of the spectrograph associated with the stack.

• pypeline (str) – Name of the PypeIt reduction mode associated with the stack, e.g. multislit or echelle.

• maskdef_designtab_list (list) – List of slitmask-design tables, one per exposure, taken from the input spec2d objects. These are used when propagating mask-design metadata into the coadded products when such information is available.

• spat_flexure_list (list) – List of spatial-flexure corrections, one per exposure, used when constructing slit masks and when relating slit geometry in the input frames to the coadded frame.