Here are notes on how to add a new spectrograph from scratch or to add a new mode. To do so, you should install PypeIt following the development path; see :doc:`../installing` and :doc:`development`.
PypeIt defines instrument-specific behavior/parameters using a python class hierarchy; see :class:`~pypeit.spectrographs.spectrograph.Spectrograph` for relevant documentation and the abstractions that will need to be defined for new spectrographs.
PypeIt reductions follow three different data-reduction paths: (1)
single, long-slit, or multi-slit reductions (e.g., Keck DEIMOS), (2) echelle
reductions for spectrographs that observe multiple, cross-dispersed orders
(e.g., Keck NIRES), and (3) slit-based integral-field spectrographs (e.g.,
KCWI). When introducing a new spectrograph, it is helpful to start with the
class for a supported spectrograph and alter it for the new spectrographs.
All spectrograph classes are located in pypeit/spectrographs/, starting
from the top-level of the repository. See :ref:`instruments` for a table with
the data-reduction (pipeline) path used for each spectrograph.
The class-hierarchy is used by PypeIt to specify certain instrument
modes, like spectrograph arm, that inherit from a common base class. For
example, :class:`~pypeit.spectrographs.keck_lris.KeckLRISSpectrograph`
implements many of the methods that are common to both arms (red and blue) of
the spectrograph. These include methods used to read raw files, to
define header cards with required :doc:`metadata`, and to determine the type of
frame (arc, dome, bias, etc) based on that :doc:`metadata`. The
:class:`~pypeit.spectrographs.spectrograph.Spectrograph` instance for each
LRIS arm inherits these methods common to them both by subclassing from
:class:`~pypeit.spectrographs.keck_lris.KeckLRISSpectrograph`. If your
spectrograph has a similar set of modes, see
pypeit/spectrographs/keck_lris.py for a demonstration.
Note
- The class-hierarchy is not meant to capture different instrument configurations (gratings, filters, etc).
- The
nameattribute of a spectrograph should be None if the class is only a base class.
Having said all of that, the basic steps one needs to follow to introduce a new spectrograph are as follows:
Build a new file called
{telescope}_{spectrograph}.pyfile and put it in thepypeit/spectrographs/directory.Add the name of the new module to the
__all__list defined inpypeit/spectrographs/__init__.py. E.g.__all__ = [ ... 'keck_lris', ... ]
Please maintain the alphabetical ordering of the modules listed.
Generate a new Telescope object in
pypeit/telescopes.py, as needed.Add the telescope name to the list of
valid_telescopesinpypeit/par/pypeitpar.py.Set the algorithmic path: the class attribute,
pypeline, must be'MultiSlit','Echelle', or'SlicerIFU'.Set the default parameters PypeIt uses during the reduction; see :ref:`parameters`, and, e.g., :func:`~pypeit.spectrographs.keck_deimos.KeckDEIMOSSpectrograph.default_pypeit_par`.
Include a default bad-pixel mask; see, e.g., :func:`~pypeit.spectrographs.keck_deimos.KeckDEIMOSSpectrograph.bpm`.
Define the link between header keywords read from the raw fits files and the PypeIt-specific :doc:`metadata` keys used throughout the code; see e.g., :func:`~pypeit.spectrographs.keck_deimos.KeckDEIMOSSpectrograph.init_meta` and :func:`~pypeit.spectrographs.keck_deimos.KeckDEIMOSSpectrograph.compound_meta`.
Define the set of PypeIt-specific :doc:`metadata` keys that are used to establish a unique instrument configuration; see, e.g., :func:`~pypeit.spectrographs.keck_deimos.KeckDEIMOSSpectrograph.configuration_keys`.
Define the method used to determine the frame type of a given file based on its :doc:`metadata`; see, e.g., :func:`~pypeit.spectrographs.keck_deimos.KeckDEIMOSSpectrograph.check_frame_type`.
Set the :doc:`metadata` for the instrument detector(s); see, e.g., :func:`~pypeit.spectrographs.keck_deimos.KeckDEIMOSSpectrograph.get_detector_par`.
Define the method used to read the raw data. See :func:`~pypeit.spectrographs.spectrograph.Spectrograph.get_rawimage` and compare to, e.g., :func:`~pypeit.spectrographs.keck_deimos.KeckDEIMOSSpectrograph.get_rawimage`.
For fixed-format echelle spectrographs, there are numerous methods that provide details for the expected format of the orders. See, e.g., :class:`~pypeit.spectrographs.vlt_xshooter.VLTXShooterNIRSpectrograph`.
You may need to generate wavelength solutions for your setups. You can use the :ref:`pypeit_identify` utility, and add this to the PypeIt archive by following the steps outlined in the :doc:`../calibrations/construct_template` documentation. See :ref:`wave_calib`.
See this example PR for the SOAR/Goodman spectrograph.
If this is a near-IR instrument, you may wish to turn off calibration steps. See :class:`~pypeit.spectrographs.gemini_gnirs.GeminiGNIRSSpectrograph` for an example.
For a spectrograph to be designated as being "supported" by PypeIt, we require a minimum set of tests. These are:
- A full run of the pipeline for each grating/mode of the spectrograph in the `PypeIt Development Suite`_.
- A simple unit test that checks that an image can be loaded. This needs to be added to the `PypeIt Development Suite`_; see here.
We request that the following docs be updated to advertise the new spectrograph:
- Include a comment noting the addition of the relevant spectrograph module in
the most recent release doc in
doc/releases. There is typically a section for "Instrument-specific" changes. - If specific advice is important/useful, add an instrument specific doc to the
doc/spectrographsdirectory and link the doc in thedoc/specrographs/spectrographs.rstdoc. - It will be helpful to users to have a tutorial to follow when using PypeIt to
reduce data from the newly supported spectrograph. Please either add a new
tutorial (see, e.g.,
doc/tutorials/lris_howto.rst) or add a comment indoc/tutorials/tutorials.rstpointing users to a spectrograph tutorial that is very similar (or identical) to the procedures that should be used for the new spectrograph.