File formats
------------

The file formats of the target catalogue, rulesets and rules files are
in specified in detail in the Online 4FS user manual
VIS-MAN-4MOST-47110-1720-0001_

.. _VIS-MAN-4MOST-47110-1720-0001:
    https://ds-web.aip.de/docushare/dsweb/Services/Document-3915

Survey configuration file
.........................

YAML file containing a dictionary with
the following entries:

- **catalog**: Target catalog file name (FITS)
- **ruleset**: Rulesets file name (CSV)
- **rules**: Rules file name (CSV)
- **templates**: Templates directory name
- **resultfile**: Output file name (FITS)

All file and directory names can be given relative to the location
of the survey configuration file.

Example
~~~~~~~

.. literalinclude:: ../qmostetc/tests/conf.yml
   :language: yaml

Target catalogue
................

FITS table with the following columns:

- **NAME**: Unique target name
- **RESOLUTION**: spectrograph resolution (1:LRS; 2:HRS)
- **RULESET**: ruleset name; the special ruleset ``DONOTOBSERVE`` prevents the target from processing
- **TEMPLATE**: template file name
- **DEC**: target declination [deg]
- **MAG**: magnitude value (per arcsec² for flat targets)
- **MAG_TYPE**: magnitude type; a string combining mag unit (AB or Vega)
  and filter
- **REDDENING**: *E(B-V)* reddening parameter [mag]
- **EXTENT_FLAG**: target shape (0:point, 1:flat, 2:sersic)
- **EXTENT_PARAMETER**: sersic radius for sersic shaped targets [arcsec]
- **EXTENT_INDEX**: sersic index for sersic shaped targets
- **REDSHIFT_ESTIMATE**: Final redshift to be applied to the template spectrum
- **TEMPLATE_REDSHIFT**: Intrinsic redshift of the template spectrum

The units must be given conform to the `FITS standard`_ and compatible
to the unit specified for the column.

Output catalogue
................

The output catalogue is copied from the input target catalogue, with
the following additional columns:

- **TEXP_D**, **TEXP_G**, **TEXP_B**, **TEXP_S**: calculated exposure
  time [min], for dark, grey, bright, and superbright moon light
  conditions.
- **FIBER_MAG**: fiber magnitude, in the same magnitude type as the
  target magnitude [mag]. The fiber mag will be calculated based on
  the throughputs estimated for the wavelength ranges specified in the
  rules.
- **FIBER_MAG_RED**, **FIBER_MAG_GREEN**, **FIBER_MAG_BLUE**: fiber
  magnitudes with the spectroscope efficiencies for the blue, green
  and red 4MOST spectrograph arms as filter [mag] (LRS or HRS as
  specifcied in the target catalogue). This is always given as AB
  magnitude, using the same throughput as above.

Rulesets file
.............

CSV file with the following columns:

- **RULESET_NAME**: unique ruleset name
- **REQ_VALUE**: Required value if the expression is not boolean
- **EXPRESSION**: Expression combining rules results

Each ruleset name except ``DONOTOBSERVE`` in the target catalogue must
correspond to one ruleset in this file.
    
Example
~~~~~~~

.. literalinclude:: ../qmostetc/tests/rulesets.csv

Rules file
..........

CSV file with the following columns:

- **RULE_NAME**: unique rule name
- **VARIABLE**: spectrum name; one of ``FLUENCE``, ``NOISE``,
  ``SNR``, ``SKY_FLUENCE``, ``BG_NOISE_FLUX``
- **METRIC**: evaluation metric; one of ``MEAN``, ``MEDIAN``, ``MAX``,
  ``MIN``, ``SUM``, ``nnPC``, ``NSAMPLE``
- **OPERATOR**: one of ``/``, ``*``, ``DIV``, ``MUL``, ``>``, ``>=``,
  ``GT``, ``GE``, ``<``, ``<=``, ``LT``, ``LE``
- **VALUE**: numeric reference value, or factor
- **L_MIN**, **L_MAX**: wavelength range. The wavelength range must be
  fully covered by one spectrograph arm.
- **L_UNIT**: unit for the wavelength specification; one of ``AA``,
  ``NM``, ``UM``, ``M``.
- **DELTA_L**: wavelength binwith
- **DELTA_L_UNIT**: unit of wavelength binwidth; one of ``AA``, ``NM``,
  ``UM``, ``M``.
- **RES_MODE**: spectrograph resolution; one of ``LRS``, ``HRS``
- **SPEC_ARM**: spectrograph arm; one of ``BLUE``, ``GREEN``, ``RED``

Each rule referenced in the ruleset file must correspond to one rule
in this file. 

Example
~~~~~~~

.. literalinclude:: ../qmostetc/tests/rules.csv

Template file
.............

FITS table with the following columns:

- **WAVELENGTH**: wavelength [nm]
- **FLUX**: target flux [erg s-1 cm-1 nm-1]

Each template in the catalog file must refer to one template
file. The units must be given conform to the `FITS standard`_ and
compatible to the unit specified for the column.

.. _FITS standard:
   https://www.aanda.org/articles/aa/full_html/2010/16/aa15362-10/aa15362-10.html