.. include:: ../include/links.rst .. _slitmask_ids_report: Slitmask ID assignment and missing slits ======================================== Version History --------------- ========= =================== =========== =========== *Version* *Author* *Date* ``PypeIt`` ========= =================== =========== =========== 1.0 Debora Pelliccia 9 Oct 2020 1.1.2dev 1.1 Debora Pelliccia 5 Nov 2020 1.2.1dev 1.2 Debora Pelliccia 26 Jan 2021 1.3.1dev 1.3 Debora Pelliccia 21 Oct 2021 1.6.1dev 1.4 J. Xavier Prochaska 11 Jan 2022 1.7.1dev 1.5 Kyle Westfall 23 Mar 2023 1.12.2dev 1.6 Debora Pelliccia 6 Sep 2023 1.13.1dev ========= =================== =========== =========== ---- Basics ------ The procedure used to assign slitmask ID to each slit is currently available for these :ref:`slitmask_info_instruments` only, and is part of the more general slit tracing procedure described in :ref:`slit_tracing`. Procedure --------- ID assignment and adding missing slits ++++++++++++++++++++++++++++++++++++++ Slitmask ID assignment is primarily performed by :func:`pypeit.edgetrace.EdgeTraceSet.maskdesign_matching`. This function matches the slit edges traced by ``PypeIt`` to the slit edges predicted using the slitmask design information stored in the observations. These predictions are generated by :func:`pypeit.spectrographs.spectrograph.Spectrograph.get_maskdef_slitedges`. For DEIMOS, this function uses the optical model to convert the slit positions from millimeter to pixels, which is done by :func:`pypeit.spectrographs.keck_deimos.KeckDEIMOSSpectrograph.mask_to_pixel_coordinates`, and relies on the existence of pre-generated detectors maps pre- and post-grating, called `amap` and `bmap`, respectively. For MOSFIRE, the prediction about the slit edges are generated simply using the following information: the number of slits, their length, and the fact that a MOSFIRE slitmask will always be constructed using 46 CSUs (Configurable Slit Units), which have a fix length of 7.01" and multiple CSUs can be used together to form longer slits. For LRIS, the procedure is similar to the one for MOSFIRE where edges are predicted based on the RA, DEC of each slit and the platescale of the detector. It has been developed and tested for ``keck_lris_red``, ``keck_lris_red_mark4``, and ``keck_lris_blue``. The function :func:`~pypeit.edgetrace.EdgeTraceSet.maskdesign_matching` assigns to each slit a ``maskdef_id``, which corresponds to `dSlitId` and `Slit_Number` in the DEIMOS/LRIS and MOSFIRE slitmask designs, respectively. Moreover, :func:`~pypeit.edgetrace.EdgeTraceSet.maskdesign_matching` uses the predicted slit edges positions to add slit traces that have not been found in the image. Overlapping alignment slits +++++++++++++++++++++++++++ Because ``PypeIt`` uses the predictions from the slitmask design to add missing slit edges, it is able to trace overlapping alignment slits (often present in DEIMOS observations only) that otherwise would be identified during :ref:`slit_tracing` as one large alignment slit, i.e., with width larger than 4". To avoid that the edges of overlapping slits cross, those edges are placed adjacent to one other. Application ----------- To perform the slitmask ID assignment, the **use_maskdesign** flag in :ref:`edgetracepar` must be **True**. This is the default for DEIMOS (except when the *LongMirr* or the *LVM* mask is used) and MOSFIRE (except when the *LONGSLIT* mask is used). Currently, for LRIS one needs to add these explicitly to the :ref:`pypeit_file`, e.g.:: [calibrations] [[slitedges]] use_maskdesign = True minimum_slit_length = 3. minimum_slit_gap = 0. Also for LRIS, one will need to have modified the raw data file using the `tilsotua` package which reverse engineers the slitmask design file into the necessary information. See their `GitHub page `_ for more. Three other :ref:`edgetracepar` control the slitmask ID assignment; these are: **maskdesign_maxsep**, **maskdesign_sigrej**, **maskdesign_step**. Access ------ The ``maskdef_id`` is recorded for each slits in the :class:`~pypeit.slittrace.SlitTraceSet` datamodel, which is written to disk as a multi-extension FITS file prefixed by Slits. In addition, for these :ref:`slitmask_info_instruments` a second `astropy.io.fits.BinTableHDU`_ is written to disk and contains more slitmask design information. See :ref:`slits` for a description of the provided information and for a way to visualize them. Moreover, the ``maskdef_id`` assigned to each slit can be found, after a full reduction with ``PypeIt`` (see, e.g., :ref:`deimos_howto`), by running ``pypeit_parse_slits Science/spec2d_XXX.fits``, which lists all the slits with their associated ``maskdef_id``. Testing ------- - PYPEIT-DEIMOS (PD) Requirement PD-9 states: "Ingest slitmask information into a data structure." Requirement PD-10 states: "Use mask information to determine initial guess for slits positions." Requirement PD-42 states: "Deal with overlapping alignment boxes that exceed 4”. " - PYPEIT-MOSFIRE (PM) Requirement PM-10 states: "Ingest slitmask information into a data structure." Requirement PM-11 states: "Use slitmask information to determine initial guess for slits positions." - LRIS -- DevSuite only thus far ``PypeIt`` meets these requirements as demonstrated by the three tests at ``${PYPEIT_DEV}/unit_tests/test_maskdesign_matching.py``. To run the tests: .. code-block:: bash cd ${PYPEIT_DEV}/unit_tests pytest test_maskdesign_matching.py::test_maskdef_id -W ignore pytest test_maskdesign_matching.py::test_add_missing_slits -W ignore pytest test_maskdesign_matching.py::test_overlapped_slits -W ignore The tests require that you have downloaded the ``PypeIt`` :ref:`dev-suite` and defined the ``PYPEIT_DEV`` environmental variable that points to the relevant directory. These tests are run using only one instrument setup and for DEIMOS only one detector. First test ``pytest test_maskdesign_matching.py::test_maskdef_id -W ignore``. The algorithm of this test is repeated twice (once for a DEIMOS dataset and once for a MOSFIRE dataset) and is as follows: 1. Load the information relative to the specific instrument (DEIMOS, MOSFIRE). 2. Load the :ref:`instr_par` parameters and select the detector. 3. Build a trace image using three flat-field images from a specific dataset in the :ref:`dev-suite`. 4. Update the instrument configuration parameters to include configurations specific for the used instrument setup. Among others, this step sets the **use_maskdesign** flag in :ref:`edgetracepar` to *True*. 5. Run the slit tracing procedure using :class:`~pypeit.edgetrace.EdgeTraceSet`, during which the slitmask ID assignment is performed, and record the ``maskdef_id`` associated to each slit in the :class:`~pypeit.slittrace.SlitTraceSet` datamodel. 6. Read the ``maskdef_id`` for the first and last slits of the selected detector and check if those correspond to the expected values. The expected values for DEIMOS are determined by previously reducing the same dataset with the already existing *DEEP2 IDL-based pipeline*, which is optimized to match the slits found on the DEIMOS detectors to the slitmask information. The expected values for MOSFIRE are determined by visual inspection. Second test ``pytest test_maskdesign_matching.py::test_add_missing_slits -W ignore``. The algorithm of this test is repeated twice (once for a DEIMOS dataset and once for a MOSFIRE dataset) and is as follows: 1. Load the information relative to the specific instrument (DEIMOS, MOSFIRE). 2. Load the :ref:`instr_par` parameters and select the detector. 3. Build a trace image using three flat-field images from a specific dataset in the :ref:`dev-suite`. 4. Update the instrument configuration parameters to include configurations specific for the used instrument setup. Among others, this step sets the **use_maskdesign** flag in :ref:`edgetracepar` to **True**. 5. Run step-by-step (lines 72-100) the slit tracing procedure performed by :class:`~pypeit.edgetrace.EdgeTraceSet`. This enable to add an extra step, where we remove 4 edges (lines 112-118) that were found by the slit tracing procedure. 6. Continue with the remaining steps of :class:`~pypeit.edgetrace.EdgeTraceSet`, including :func:`~pypeit.edgetrace.EdgeTraceSet.maskdesign_matching`, which adds the missing slits and performs the the slitmask ID assignment. 7. Check that the pixel position of the traces that were previously removed are now recovered. Third test ``pytest test_maskdesign_matching.py::test_overlapped_slits -W ignore`` is performed only on DEIMOS data. The algorithm of this test is identical to the first test, but using a different DEIMOS dataset that shows overlapping alignment slits. The algorithm, then, checks that the total number of slits and the number alignment slits are as expected. The expected numbers are determined by visual inspection of the observations. Because these tests are now included in the ``PypeIt`` :ref:`unit-tests`, these checks are performed by the developers for every new version of the code. The ``PypeIt`` team have carefully tested ~10 datasets, but more tests are welcome.