spectral_trace_list
===================

SpectralTraceList
+++++++++++++++++


List of spectral trace geometries for the detector plane.

Should work in concert with an ApertureList (or ApertureMask) object and a
DetectorList object

Spectral trace patterns are to be kept in a ``fits.HDUList`` with one or
more ``fits.BinTableHDU`` extensions, each one describing the geometry of a
single trace. The first extension should be a ``BinTableHDU`` connecting
the traces to the correct ``Aperture`` and ``ImagePlane`` objects.

The ``fits.HDUList`` objects can be loaded using one of these two keywords:

- ``filename``: for on disk FITS files, or
- ``hdulist``: for in-memory ``fits.HDUList`` objects

The format and contents of the extensions in the HDUList (FITS file) object
is listed below

Input Data Format
-----------------
A trace list FITS file needs the following extensions:

- 0 : PrimaryHDU [header]
- 1 : BinTableHDU [header, data] : Overview table of all traces
- 2..N : BinTableHDU [header, data] : Trace tables. One per spectral trace

EXT 0 : PrimaryHDU
++++++++++++++++++
Required Header Keywords:

- ECAT : int : Extension number of overview table. Normally 1
- EDATA : int : Extension number of first Trace table. Normally 2

No data is required in this extension

EXT 1 : BinTableHDU : Overview of traces
++++++++++++++++++++++++++++++++++++++++
No special header keywords are required in this extension

Required Table columns:

- description : str : identifier of each trace
- extension_id : int : which extension is each trace in
- aperture_id : int : which aperture matches this trace (e.g. MOS / IFU)
- image_plane_id : int : on which image plane is this trace projected

EXT 2 : BinTableHDU : Individual traces
+++++++++++++++++++++++++++++++++++++++
Required header keywords:
- EXTNAME : must be identical to the `description` in EXT 1

Recommended header keywords:
- DISPDIR : "x" or "y" : dispersion axis. If not present, Scopesim tries
  to determine this automatically; this may be unreliable in some cases.

Required Table columns:
- wavelength : float : [um] : wavelength of monochromatic aperture image
- s : float : [arcsec] : position along aperture perpendicular to trace
- x : float : [mm] : x position of aperture image on focal plane
- y : float : [mm] : y position of aperture image on focal plane



SpectralTraceListWheel
++++++++++++++++++++++


A Wheel-Effect object for selecting between multiple gratings/grisms.

See ``SpectralTraceList`` for the trace file format description.

Parameters
----------
trace_list_names : list
    The list of unique identifiers in the trace filenames

filename_format : str
    ``f-string`` that directs scopesim to the folder containing the trace
    files. This can be a ``!-string`` if the trace names are shared with
    other ``*Wheel`` effect objects (e.g. a ``FilterWheel``). See examples.

current_trace_list : str
    default trace file to use

kwargs : key-value pairs
    Addition keywords that are passed to the ``SpectralTraceList`` objects
    See SpectralTraceList docstring

Examples
--------
A simplified YAML file example taken from the OSIRIS instrument package::

    alias: INST
    name: OSIRIS_LSS

    properties:
      decouple_detector_from_sky_headers: True
      grism_names:
        - R300B
        - R500B
        - R1000B
        - R2500V

    effects:
      - name: spectral_trace_wheel
        description: grism wheel contining spectral trace geometries
        class: SpectralTraceListWheel
        kwargs:
          current_trace_list: "!OBS.grating_name"
          filename_format: "traces/LSS_{}_TRACE.fits"
          trace_list_names: "!INST.grism_names"

      - name: grating_efficiency
        description: OSIRIS grating efficiency curves, piggybacking on FilterWheel
        class: FilterWheel
        kwargs:
          minimum_throughput: !!float 0.
          filename_format: "gratings/{}.txt"
          current_filter: "!OBS.grating_name"
          filter_names: "!INST.grism_names"