Coadd 2D Spectra

Overview

This document describes how to combine the 2D spectra from multiple exposures. For a worked examples, see Coadd2D HOWTO.

Coadding must be done outside of the data reduction pipeline (run_pypeit); i.e., PypeIt will not coadd your spectra as part of the data reduction process, although it can combine (without weighting) multiple exposures during reductions (see Combining Science Exposures).

Note

Because the flux of the single reduced science frames is expressed in counts, coadding frames with different exposure times is not recommended. If the user still wishes to do so, the fluxes of the individual frames are rescaled by the median exposure time. For example, if we have four frames with exposure times of 1800, 1800, 1800, and 1200 seconds, the exposure time of the coadded frame will be:

coadd_exptime = np.percentile([1800,1800,1800,1200],50, method='higher')

and the flux of the individual frames will be rescaled by:

rescale_factor = coadd_exptime / exptime

where exptime is the exposure time of the individual frames. coadd_exptime is saved in the header of the coadded frame as ALLSPEC2D_EFFECTIVE_EXPTIME, so that the user can easily convert the flux of the coadded frame from counts to counts/s.

Note, also, that the combination (without weighting) of multiple exposures during main reduction (i.e, Combining Science Exposures) does not perform this rescaling.

coadd2d file

The pypeit_coadd_2dspec script requires an input file to guide the process. The format of this type of Input File Format includes a Parameter Block (required) and a Data Block (required).

Here is an example for keck_lris_blue:

# User-defined execution parameters
[rdx]
    spectrograph = keck_lris_blue
    detnum = 2
[reduce]
    [[findobj]]
        snr_thresh=5.0

# Data block
spec2d read
path /path/to/your/Science/folder
filename
spec2d_b170320_2083-c17_60L._LRISb_2017Mar20T055336.211.fits
spec2d_b170320_2090-c17_60L._LRISb_2017Mar20T082144.525.fits
spec2d_b170320_2084-c17_60L._LRISb_2017Mar20T062414.630.fits
spec2d_b170320_2091-c17_60L._LRISb_2017Mar20T085223.894.fits
spec2d end

The opening Parameter Block sets information and parameters for the reduction steps. The spectrograph name is required.

See Coadd2DPar Keywords for a list of the options specific to 2D coadds, including Manual Extraction.

The Data Block always begins and ends with spec2d read and spec2d end, respectively. It (optionally) provides the path to the Spec2D Output files. It then includes a (one column) table which is a simple list of the Spec2D Output files.

Note

The inclusion of the line filename in the example above is required. This is the line providing the columns names for the data to follow and must be present, even if there is only one column.

You may also include file-specific options in the Data Block as additional columns. See Data Block for its formatting.

Setup script

Similar to pypeit_setup, we provide a script that helps you construct the required input file. In this case, pypeit_setup_coadd2d helps you build the required .coadd2d file.

The script usage can be displayed by calling the script with the -h option:

$ pypeit_setup_coadd2d -h
usage: pypeit_setup_coadd2d [-h]
                            (-f PYPEIT_FILE | -d SCIENCE_DIR [SCIENCE_DIR ...])
                            [--keep_par] [--obj OBJ [OBJ ...]]
                            [--det DET [DET ...]]
                            [--only_slits ONLY_SLITS [ONLY_SLITS ...]]
                            [--exclude_slits EXCLUDE_SLITS [EXCLUDE_SLITS ...]]
                            [--spat_toler SPAT_TOLER] [--offsets OFFSETS]
                            [--weights WEIGHTS]

Prepare a configuration file for performing 2D coadds

options:
  -h, --help            show this help message and exit
  -f PYPEIT_FILE, --pypeit_file PYPEIT_FILE
                        PypeIt reduction file (default: None)
  -d SCIENCE_DIR [SCIENCE_DIR ...], --science_dir SCIENCE_DIR [SCIENCE_DIR ...]
                        One or more directories with spec2d files to stack (use
                        wildcard to specify multiple directories). (default:
                        None)
  --keep_par            Propagate all parameters from the pypeit file to the
                        coadd2d file(s). If not set, only the required
                        parameters and their default values are included in the
                        output file(s). (default: True)
  --obj OBJ [OBJ ...]   Limit the coadd2d files created to observations of the
                        specified target. If not provided, a coadd2D file is
                        written for each target found in the science directory.
                        The target names are included in the PypeIt spec2d file
                        names.For example, the target for spec2d file "spec2d_cN
                        20170331S0216-pisco_GNIRS_20170331T085412.181.fits" is
                        "pisco". (default: None)
  --det DET [DET ...]   A space-separated set of detectors or detector mosaics
                        to coadd. By default, *all* detectors or default mosaics
                        for this instrument will be coadded. Detectors in a
                        mosaic must be a mosaic "allowed" by PypeIt and should
                        be provided as comma-separated integers (with no
                        spaces). For example, to separately coadd detectors 1
                        and 5 for Keck/DEIMOS, you would use --det 1 5; to coadd
                        mosaics made up of detectors 1,5 and 3,7, you would use
                        --det 1,5 3,7 (default: None)
  --only_slits ONLY_SLITS [ONLY_SLITS ...]
                        A space-separated set of slits to coadd. Example syntax
                        for argument is DET01:175,DET02:205 or MSC02:2234. If
                        not provided, all slits are coadded. If both --det and
                        --only_slits are provided, --det will be ignored. This
                        and --exclude_slits are mutually exclusive. If both are
                        provided, --only_slits takes precedence. (default: None)
  --exclude_slits EXCLUDE_SLITS [EXCLUDE_SLITS ...]
                        A space-separated set of slits to exclude in the
                        coaddition. This and --only_slits are mutually
                        exclusive. If both are provided, --only_slits takes
                        precedence. (default: None)
  --spat_toler SPAT_TOLER
                        Desired tolerance in spatial pixel used to identify
                        slits in different exposures. If not provided, the
                        default value for the specific instrument/configuration
                        is used. (default: None)
  --offsets OFFSETS     Spatial offsets to apply to each image; see the
                        [coadd2d][offsets] parameter. Options are restricted
                        here to either maskdef_offsets or auto. If not
                        specified, the (spectrograph-specific) default is used.
                        Other options exist but must be entered by directly
                        editing the coadd2d file. (default: None)
  --weights WEIGHTS     Weights used to coadd images; see the [coadd2d][weights]
                        parameter. Options are restricted here to either uniform
                        or auto. If not specified, the (spectrograph-specific)
                        default is used. Other options exist but must be entered
                        by directly editing the coadd2d file. (default: None)

For example, assuming you have already executed run_pypeit on your data using a pypeit file, you can construct the default coadd2d file(s) using:

pypeit_setup_coadd2d -f keck_lris_A.pypeit

This will produce one .coadd2d file per unique target in the pypeit file with associated spec2d files in the output science directory. The script provides additional options that allow you to select specific objects/targets, specify the method used to set the offsets and/or weights, specify the detectors to coadd, and/or specify the slits that should be coadded.

pypeit_coadd_2dspec

Once you have prepared a .coadd2d file, the primary script to execute is pypeit_coadd_2dspec.

The script usage can be displayed by calling the script with the -h option:

$ pypeit_coadd_2dspec -h
usage: pypeit_coadd_2dspec [-h] [--show] [--debug_offsets] [--peaks]
                           [--basename BASENAME] [--debug] [-v VERBOSITY]
                           [--spec_samp_fact SPEC_SAMP_FACT]
                           [--spat_samp_fact SPAT_SAMP_FACT]
                           coadd2d_file

Coadd 2D spectra produced by PypeIt

positional arguments:
  coadd2d_file          File to guide 2d coadds

options:
  -h, --help            show this help message and exit
  --show                Show the reduction steps. Equivalent to the -s option
                        when running pypeit. (default: False)
  --debug_offsets       Show QA plots useful for debugging automatic offset
                        determination (default: False)
  --peaks               Show the peaks found by the object finding algorithm.
                        (default: False)
  --basename BASENAME   Basename of files to save the parameters, spec1d, and
                        spec2d (default: None)
  --debug               show debug plots? (default: False)
  -v VERBOSITY, --verbosity VERBOSITY
                        Verbosity level between 0 [none] and 2 [all]. Default:
                        1. Level 2 writes a log with filename
                        coadd_2dspec_YYYYMMDD-HHMM.log (default: 1)
  --spec_samp_fact SPEC_SAMP_FACT
                        Make the wavelength grid finer (spec_samp_fact < 1.0) or
                        coarser (spec_samp_fact > 1.0) by this sampling factor,
                        i.e. units of spec_samp_fact are pixels. (default: 1.0)
  --spat_samp_fact SPAT_SAMP_FACT
                        Make the spatial grid finer (spat_samp_fact < 1.0) or
                        coarser (spat_samp_fact > 1.0) by this sampling factor,
                        i.e. units of spat_samp_fact are pixels. (default: 1.0)

options

Here are commonly used options:

–show

Show a series of matplotlib plots to the screen.

–basename

Provides the basename for the spec1d and spec2d files. If not provided, defaults to a portion of the input spec2d filenames.

–debug

Provides additional debugging diagnostic plots compared to using --show.

run

Then run the script:

pypeit_coadd_2dspec  FRB190711_XS.coadd2d --show

The parameters that guide the coadd process are also written to disk for your records. The default location is *_coadd2d.par, where the wildcard should contain the frames included and the target/object name. You can choose another location by modifying –basename.

For worked examples, see Coadd2D HOWTO.

Current Coadd2D Data Model

The outputs produced by pypeit_coadd_2dspec are identical to a standard run of run_pypeit, except that the results are places in *_coadd directories. See Spec1D Output and Spec2D Output.