Constructing a New Wavelength Template

Overview

This doc describes how to create a wavelength template used to perform wavelength calibration with the Automated Algorithms.

See Wavelength Calibration for a discussion of various algorithms and see WaveCalib for a discussion of the main outputs and good/bad examples.

Finding Data

To build a new template, the requirements are wavelength calibrations for the arc spectra over the full wavelength range needed. This may take multiple exposures of arc lamps to cover the full range.

Using the Holy Grail Algorithm

Once you have a set of different arc lamp exposures that cover the desired range, run through the data using the option of the Holy Grail algorithm to generate a wavelength calibration and select the slits where the technique is successful. See WaveCalib for an example QA plot that illustrates a good wavelength solution.

With a complete set of correctly calibrated arc line data, identify wavelength regions, with no gaps, that cover the full range in wavelength desired.

In situations where the Holy Grail fails, one may resort to pypeit_identify.

If a calibrated arc line spectrum that covers the desired wavelength range is already available, an ascii file with 2 columns, wavelength and flux, can be used instead of running the reduction with the Holy Grail algorithm.

Creating the Template

Once all of the slits and wavelength calibration files are selected, use build_template() to turn the list of slits, wavelength ranges, and WaveCalib files into a final template.

For longevity, it is a good idea to install the PypeIt Development Suite (see here) and combine your solution with all PypeIt wavelength solutions using the same instrument and grating. If you used the pypeit_identify utility, it will output a file called wvcalib.fits. You should put this file in the appropriate instrument folder in the PypeIt Development Suite templates directory:

$PYPEIT_DEV/dev_algorithms/wavelengths/template_files/

you should also rename this file to match the current formatting:

mv wvcalib.fits ${TELESCOPE}_${INSTRUMENT}_${GRATING}_${WAVECEN}.fits

Now, open the pypeit/core/wavecal/spectrographs/templ_TELESCOPE_INSTRUMENT.py file, and either (1) add a new setup if yours doesn’t already exist or (2) edit a setup if you want to add your solution to a pre-existing setup. The latter is only usually warranted if you are extending the wavelength coverage of a previous setup. The key information you will need is the spectral binning and the slit spatid. Both of these numbers are printed on the command line when you complete the fitting with the pypeit_identify utility. Once this is setup, simply execute python templates.py from the directory that contains templ_TELESCOPE_INSTRUMENT.py.

This will automatically put your solution into the reid_arxiv directory. Add all of these files to git, and submit a PR for both PypeIt and the PypeIt Development Suite.

Alternatively, if you want to construct a template file yourself (with the possible disadvantage that your solution cannot be stitched together with solutions from the same spectrograph+grating in the future), you can write a script where the input looks like the following:

from pypeit.core.wavecal import templates

templates.build_template(wfiles, slits, wv_cuts, binspec, outroot, ifiles=ifiles,
                         det_cut=det_cut, chk=True, normalize=False, lowredux=False,
                         subtract_conti=True, overwrite=overwrite, shift_wave=True)

See build_template() for a description of all the parameters, and pypeit/core/wavecal/spectrographs for examples of the use of this function.

This produces a file called outroot that contains the template. The templates are saved in pypeit/data/arc_lines/reid_arxiv. It also produces a plot of the final product.