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

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

# Example configuration yml file
catalog: targets.fits
ruleset: rulesets.csv
rules: rules.csv
templates: .
resultfile: ../../example_result.fits

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

RULESET_NAME; REQ_VALUE; EXPRESSION
#
# EXAMPLE 1: The following Ruleset is a Boolean expression, which must
# be True and is satisfied when both Boolean rules Seng1_LR_blue
# andSeng2_LR_redare satisfied
#
Test1LR; 1.0   ;   Seng1_LR_blue  && Seng2_LR_red
#
# EXAMPLE 2: The following ruleset is satisfied if the numerical
# expression given by the sum of the rule GalHaloLR_blueand of the
# square of GalHaloLR_redis larger than 2.5
#
Test12LR; 2.5;   (GalHaloLR_blue)+(GalHaloLR_red**2)

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

RULE_NAME;VARIABLE;METRIC;OPERATOR;VALUE;L_MIN;L_MAX;L_UNIT;DELTA_L;DELTA_L_UNIT;RES_MODE;SPEC_ARM
#
# EXAMPLE 1&2: The 2 following rules are Boolean expression. they can
# be combined in the Ruleset file to return a Boolean value.
#
Seng1_LR_blue;SNR;MEDIAN;GE;10.0;5150.0;5200.0;AA;1.0;AA;LRS;BLUE
Seng2_LR_red;SNR;MEDIAN;GE;10.0;8490.0;8675.0;AA;1.0;AA;LRS;RED
#
# EXAMPLE 3&4: The 2 following rules are numericalexpressions. they
# can be combined in the Ruleset file to return a Boolean value.
#
GalHaloLR_blue;SNR;MEDIAN;DIV;1.0;4200.0;5000.0;AA;1.0;AA;LRS;BLUE
GalHaloLR_red;SNR;MEDIAN;DIV;1.0;7200.0;9000.0;AA;1.0;AA;LRS;RED

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.