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]
[--spec_samp_fact SPEC_SAMP_FACT]
[--spat_samp_fact SPAT_SAMP_FACT]
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)
--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)
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]
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)
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.