pypeit.coadd2d module

Module for performing two-dimensional coaddition of spectra.

class pypeit.coadd2d.CoAdd2D(spec2d, spectrograph, par, det=1, offsets=None, weights='auto', only_slits=None, exclude_slits=None, spec_samp_fact=1.0, spat_samp_fact=1.0, sn_smooth_npix=None, bkg_redux=False, find_negative=False, show=False, show_peaks=False, debug_offsets=False, debug=False)[source]

Bases: object

Main routine to run the extraction for 2d coadds.

Algorithm steps are as follows:

  • Fill this in.

This performs 2d coadd specific tasks, and then also performs some of the tasks analogous to the pypeit.extract_one method. Docs coming soon….

check_input(input, type)[source]

Check that the number of input values (weights or offsets) is the same as the number of exposures :param input: User input values (e.g., weights or offsets) :type input: list or numpy.ndarray :param type: String defining what the quantities are :type type: str

Returns:

User input values

Return type:

list or numpy.ndarray

coadd(interp_dspat=True)[source]

Construct a 2d co-add of a stack of PypeIt spec2d reduction outputs. This method calls loops over slits/orders and performs the 2d-coadd by calling coadd.compute.coadd2d, which ‘rectifies’ images by coadding them about the reference_trace_stack.

Parameters:

interp_dspat (bool, optional) – Interpolate in the spatial coordinate image to faciliate running through core.extract.local_skysub_extract. Default=True

Returns:

coadd_list – List of dictionaries, one for each slit, containing the 2d stack. # TODO Make this a PypeIt object, with data model yada-yada.

Return type:

list

compute_offsets(offsets)[source]

Determine self.offsets, the offset of the frames to be coadded with respect to the first frame. This is partially overloaded by the child methods.

Parameters:

offsets (list or str) – Value that guides the determination of the offsets. It could be a list of offsets, or a string.

compute_weights(weights)[source]

Determine the weights to be used in the coadd2d. This is partially overloaded by the child methods.

This method sets the internal use_weights. Documentation on the form of self.use_weights needs to be written.

Parameters:

weights (list, str) – Value that guides the determination of the weights. It could be a list of weights or a string. If ‘auto’ the weight will be computed using the brightest trace, if ‘uniform’ uniform weights will be used.

create_pseudo_image(coadd_list)[source]

..todo.. see below

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

static default_basename(spec2d_files)[source]

Construct the base name of the output spec2d file produced by coadding.

Parameters:

spec2d_files (list) – The list of PypeIt spec2d files to be coadded.

Returns:

The root base name for the output coadd2d spec2d file.

Return type:

str

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

Get the default 2D coadding parameters.

Parameters:

  • spectrograph (str) – The PypeIt-specific name of the spectrograph used to collect the data.

  • inp_cfg (dict, optional) – An existing set of parameters to add to.

  • det (list, str, tuple, optional) – Limit the coadding to this (set of) detector(s)/detector mosaic(s)

  • only_slits (list, str, optional) – Limit the coadding to this (set of) slit(s). Only_slits and exclude_slits are mutually exclusive. If both are set, only_slits takes precedence.

  • exclude_slits (list, str, optional) – Exclude this (set of) slit(s) from the coadding. Only_slits and exclude_slits are mutually exclusive. If both are set, only_slits takes precedence.

Returns:

The default set of parameters.

Return type:

dict

get_brightest_object(specobjs_list, spat_ids)[source]

Dummy method to identify the brightest object. Overloaded by child methods.

Parameters:

  • specobjs_list –

  • spat_ids –

classmethod get_instance(spec2dfiles, spectrograph, par, det=1, offsets=None, weights='auto', only_slits=None, exclude_slits=None, spec_samp_fact=1.0, spat_samp_fact=1.0, sn_smooth_npix=None, bkg_redux=False, find_negative=False, show=False, show_peaks=False, debug_offsets=False, debug=False)[source]

Instantiate the subclass appropriate for the provided spectrograph.

The class to instantiate must match the pypeline attribute of the provided spectrograph, and must be a subclass of CoAdd2D; see the parent class instantiation for parameter descriptions.

Returns:

One of the subclasses with CoAdd2D as its base.

Return type:

CoAdd2D

get_maskdef_dict(slit_idx, ref_trace_stack)[source]

Dummy method to get maskdef info. Overloaded by child methods.

Parameters:

  • slit_idx –

  • ref_trace_stack –

Returns:

?

Return type:

dict

get_wave_grid(wave_method)[source]

Routine to create a wavelength grid for 2d coadds using all of the wavelengths of the extracted objects. Calls get_wave_grid().

Parameters:

wave_method (str) – The method to use to create the wavelength grid passed to get_wave_grid()

Returns:

Returns the following:

  • 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.

Return type:

tuple

good_slitindx(only_slits=None, exclude_slits=None)[source]

This provides an array of index of slits in the un-coadded frames that are considered good for 2d coadding. A bitmask common to all the un-coadded frames is used to determine which slits are good. Also, If the only_slits parameter is provided only those slits are considered good for 2d coadding.

Parameters:

  • only_slits (list, optional) – List of slits to combine. It must be slitord_id. Only_slits and exclude_slits are mutually exclusive. If both are provided, only_slits takes precedence.

  • exclude_slits (list, optional) – List of slits to exclude. It must be slitord_id. Only_slits and exclude_slits are mutually exclusive. If both are provided, only_slits takes precedence.

Returns:

array of index of good slits in the un-coadded frames

Return type:

numpy.ndarray

load_coadd2d_stacks(spec2d, chk_version=False)[source]

Routine to read in required images for 2d coadds given a list of spec2d files.

Parameters:

  • spec2d_files – list List of spec2d filenames

  • det – int detector in question

Returns:

Dictionary containing all the images and keys required for perfomring 2d coadds.

Return type:

dict

offset_slit_cen(slitid, offsets)[source]

Offset the slit centers of the slit designated by slitid by the provided offsets

Parameters:

  • slitid (int) – ID of the slit that is being offset

  • offsets (list, numpy.ndarray) – A list or array of offsets that are being applied to the slit center

Returns:

A list of reference traces for the 2d coadding that have been offset.

Return type:

list

offsets_report(offsets, offsets_method)[source]

Print out a report on the offsets

Parameters:

  • offsets –

  • offsets_method –

Returns:

optimal_weights(slitorderid, objid, weight_method='auto')[source]

Determine optimal weights for 2d coadds. This script grabs the information from SpecObjs list for the object with specified slitid and objid and passes to coadd.sn_weights to determine the optimal weights for each exposure.

Parameters:

  • slitorderid (int) – The slit or order id that has the brightest object whose S/N will be used to determine the weight for each frame.

  • objid (numpy.ndarray) – Array of object indices with shape = (nexp,) of the brightest object whose S/N will be used to determine the weight for each frame.

  • weight_method (str, optional) –

    Weight method to be used in sn_weights(). Options are 'auto', 'constant', 'relative', or 'ivar'. The default is 'auto'. Behavior is as follows:

    • 'auto': Use constant weights if rms_sn < 3.0, otherwise use wavelength dependent.

    • 'constant': Constant weights based on rms_sn**2

    • 'uniform': Uniform weighting.

    • 'wave_dependent': Wavelength dependent weights will be used irrespective of the rms_sn ratio. This option will not work well at low S/N ratio although it is useful for objects where only a small fraction of the spectral coverage has high S/N ratio (like high-z quasars).

    • 'relative': Calculate weights by fitting to the ratio of spectra? Note, relative weighting will only work well when there is at least one spectrum with a reasonable S/N, and a continuum. RJC note - This argument may only be better when the object being used has a strong continuum + emission lines. The reference spectrum is assigned a value of 1 for all wavelengths, and the weights of all other spectra will be determined relative to the reference spectrum. This is particularly useful if you are dealing with highly variable spectra (e.g. emission lines) and require a precision better than ~1 per cent.

    • 'ivar': Use inverse variance weighting. This is not well tested and should probably be deprecated.

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.

static output_paths(spec2d_files, par, coadd_dir=None)[source]

Construct the names and ensure the existence of the science and QA output directories.

Parameters:

  • spec2d_files (list) – The list of PypeIt spec2d files to be coadded. The top-level directory for the coadd2d output directories is assumed to be same as used by the basic reductions. For example, if one of the spec2d files is /path/to/reductions/Science/spec2d_file.fits, the parent directory for the coadd2d directories is /path/to/reductions/.

  • par (PypeItPar) – Full set of parameters. The only used parameters are par['rdx']['scidir'] and par['rdx']['qadir']. WARNING: This also alters the value of par['rdx']['qadir']!!

  • coadd_dir (str, optional) – Path to the directory to use for the coadd2d output. If None, the parent of the science directory is used.

Returns:

Two strings with the names of (1) the science output directory and (2) the QA output directory. The function also creates both directories if they do not exist.

Return type:

tuple

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

Method to run the reduction on coadd2d pseudo images

Parameters:

  • pseudo_dict (dict) – Dictionary containing coadd2d pseudo images

  • show (bool) – If True, show the outputs to ginga and the screen analogous to run_pypeit with the -s option

  • show_peaks (bool) – If True, plot the object finding QA to the screen.

  • basename (str) – The basename for the spec2d output files.

Returns:

reference_trace_stack(slitid, offsets=None, objid=None)[source]

Dummy method to obtain the stack of reference traces. Overloaded by child methods.

Parameters:

  • slitid –

  • offsets –

  • objid –

Returns:

snr_report(snr_bar, slitid=None)[source]

..todo.. I need a doc string

Parameters:

  • snr_bar –

  • slitid –

Returns:

class pypeit.coadd2d.EchelleCoAdd2D(spec2d_files, spectrograph, par, det=1, offsets=None, weights='auto', only_slits=None, exclude_slits=None, spec_samp_fact=1.0, spat_samp_fact=1.0, sn_smooth_npix=None, bkg_redux=False, find_negative=False, show=False, show_peaks=False, debug_offsets=False, debug=False)[source]

Bases: CoAdd2D

Coadd Echelle reductions.

For documentation see CoAdd2D.

Echelle can either stack with:

  • input offsets or if offsets is None, it will find the objid of brightest trace and stack all orders relative to the trace of this object.

  • specified weights, or if weights is None and auto_weights is True, it will use wavelength dependent weights determined from the spectrum of the brightest objects objid on each order

compute_offsets(offsets)[source]

Determine self.offsets, the offset of the frames to be coadded with respect to the first frame

Parameters:

offsets (list or str) – Value that guides the determination of the offsets. It could be a list of offsets, or a string, or None.

compute_weights(weights)[source]

Determine self.use_weights, the weights to be used in the coadd2d

Parameters:

weights (list or str) – Value that guides the determination of the weights. It could be a list of weights or a string. If ‘auto’ the weight will be computed using the brightest trace, if ‘uniform’ uniform weights will be used.

get_brightest_obj(specobjs_list, nslits)[source]

Utility routine to find the brightest object in each exposure given a specobjs_list for Echelle reductions.

Parameters:

  • specobjs_list – list List of SpecObjs objects.

  • echelle – bool, default=True, optional

Returns:

Returns the following:

  • objid: ndarray, int, shape (len(specobjs_list),): Array of object ids representing the brightest object in each exposure

  • snr_bar: ndarray, float, shape (len(list),): Average S/N over all the orders for this object

Return type:

tuple

reference_trace_stack(slitid, offsets=None, objid=None)[source]

Utility function for determining the reference trace about which 2d coadds are performed.

There are two modes of operation to determine the reference trace for the 2d coadd of a given slit/order:

  1. offsets: We stack about the center of the slit for the slit in question with the input offsets added

  2. ojbid: We stack about the trace of a reference object for this slit given for each exposure by the input objid

Either offsets or objid must be provided, but the code will raise an exception if both are provided.

Parameters:

  • slitid (int) – The slit or order that we are currently considering

  • stack_dict (dict) – Dictionary containing all the images and keys required for performing 2d coadds.

  • offsets (list, numpy.ndarray) – An array of offsets with the same dimensionality as the nexp, the numer of images being coadded.

  • objid (list, numpy.ndarray) – An array of objids with the same dimensionality as the nexp, the number of images being coadded.

Returns:

A list of reference traces for the 2d coadding that have been offset

Return type:

list

class pypeit.coadd2d.MultiSlitCoAdd2D(spec2d_files, spectrograph, par, det=1, offsets=None, weights='auto', only_slits=None, exclude_slits=None, spec_samp_fact=1.0, spat_samp_fact=1.0, sn_smooth_npix=None, bkg_redux=False, find_negative=False, show=False, show_peaks=False, debug_offsets=False, debug=False)[source]

Bases: CoAdd2D

Child of Coadd2d for Multislit and Longslit reductions. For documentation see CoAdd2d parent class above.

# Multislit can coadd with: # 1) input offsets or if offsets is None, it will find the brightest trace and compute them # 2) specified weights, or if weights is None and auto_weights=True, it will compute weights using the brightest object

compute_offsets(offsets)[source]

Determine self.offsets, the offset of the frames to be coadded with respect to the first frame

Parameters:

offsets (list or str) – Value that guides the determination of the offsets. It could be a list of offsets, or a string, or None. If equal to ‘maskdef_offsets’ the offsets computed during the slitmask design matching will be used.

compute_weights(weights)[source]

Determine the weights to be used in the coadd2d.

This method sets the internal use_weights. Documentation on the form of self.use_weights needs to be written.

Parameters:

weights (list, str) – Value that guides the determination of the weights. It could be a list of weights or a string. If equal to ‘auto’, the weight will be computed using the brightest trace, if ‘uniform’ uniform weights will be used.

get_brightest_obj(specobjs_list, spat_ids)[source]

Utility routine to find the brightest object in each exposure given a specobjs_list for MultiSlit reductions.

Parameters:

  • specobjs_list – list List of SpecObjs objects.

  • spat_ids (numpy.ndarray) –

Returns:

Returns the following:

  • objid: ndarray, int, shape (len(specobjs_list),): Array of object ids representing the brightest object in each exposure

  • slit_idx (int): 0-based index

  • spat_id (int): SPAT_ID for slit that highest S/N ratio object is on (only for pypeline=MultiSlit)

  • snr_bar: ndarray, float, shape (len(list),): Average S/N over all the orders for this object

Return type:

tuple

get_maskdef_dict(slit_idx, ref_trace_stack)[source]
Parameters:

  • slit_idx (int) – index of a slit in the uncoadded frames

  • ref_trace_stack (numpy.ndarray) – Stack of reference traces about which the images are rectified and coadded. It is the slitcen appropriately shifted according the frames offsets. Shape is (nspec, nimgs).

Returns:

Dictionary containing all the maskdef info. The quantities saved are: maskdef_id, maskdef_objpos, maskdef_slitcen, maskdef_designtab. To learn what they are see SlitTraceSet datamodel.

Return type:

dict

reference_trace_stack(slitid, offsets=None, objid=None)[source]

..todo.. I need a doc string

Parameters:

  • slitid –

  • offsets –

  • objid –

Returns: