TSL Parameter Keyword Descriptions

  • AZRES - Azimuth Restriction
    • For tracks that should only be done at one specific azimuth, specify E or W.
    • If no azimuth restriction is needed, omit this keyword or leave this field blank ("").
    • See the Position Angle Calculator for more information about PA and azimuth restrictions.
    • Examples:
      AZRES  E
      AZRES  ""

  • COMMENT - Comment String
    • If there are spaces, enclose in double quotes.
    • Keep it as brief as possible, starting with anything vital to know about at the time of execution, e.g. any request ("Take adjacent ThAr") or ID clarification ("Fainter star of close pair") or intention that might be misread from a finding chart ("Transect BOTH nuclei with the slit").
    • Users tend to confuse the intentions of the COMMENT and the NOTES keywords (see below). COMMENT is for the most concise, vital, real-time instructions necessary for the visit of this target; NOTES are intended to apply to all targets but should still be concise.
    • Format Examples:
      COMMENT  "Take adjacent ThAr"
      COMMENT  template_exposure

  • CRSPLIT - Cosmic Ray Splits
    • Number of sub-exposures in which to split the total exposure time for a visit.
    • For long (>20 minutes) LRS EXP total integration times, use CRSPLIT to break up the time not only for cosmic ray censoring, but also for quality checks upon target centering and focus.
    • A CRSPLIT of 1 means no sub-exposures, i.e. one single exposure.
    • For example, an exposure time of 1800 sec with a CRSPLIT of 2 means two 900 sec exposures.
    • Use either CRSPLIT or NUMEXP, but do not mix the two in a single TSL file.
    • If the goal is to fill the track maximally with exposures, please also inform the RA with a COMMENT.
    • If covering an entire track with split exposures, be aware of the considerable readout overhead entailed by CRSPLIT >> 1. A good tactic is then to make the exposures as long as possible, but this brings in the changing HET effective pupil.
    • Example:
      CRSPLIT  3

  • DEC - Declination of Target
    • Valid values fall between -12:00:00 and +74:00:00, exclusive.
    • Coordinates are assumed to be J2000, unless specified otherwise using the EQUINOX keyword.
    • Examples:
      DEC  +13:12:12.34
      DEC  13:32:23
      DEC  -10:35:59.9

  • DITHER - Set dither exposure
    • Valid values are Y or N.
    • Default value are INSTRUMENT dependent. If not set Y selected for VIRUS and N for LRS2-B and LRS2-R.
    • Examples:
      DITHER  Y

  • EQUINOX - Equinox of Coordinates
    • Equinox of object coordinates.
    • Assumed to by 2000, unless otherwise specified.
    • Example:
      EQUINOX  1950.0

  • EXP - Exposure Time in Seconds
    • If CRSPLIT is used, EXP is the total exposure time in seconds for the Action, and each frame exposure is the CRSPLIT-fold divided fractional part. Normally the exposure depth contrast due to the slowly changing effective pupil is very minor (but if the visit covers the entire track end-to-end, may be significant).
    • If NUMEXP is used instead, this is the exposure time per frame.
    • If neither is specified, this is the exposure time for the (single) frame.
    • Example:
      EXP  900

  • EXTRACALS - Extra Calibrations
    • Used to specify the number count and exposure time for a list of calibration frames to be obtained during twilight (when standard cals are taken) in addition to any STDCALS calibrations or add-on calibrations such as e.g. THAR. It is one tool for adding calibrations of an unusual integration length or unusual nature given the science target setup (the other being to form individual "standalone" targets out of the said calibrations).
    • The general format of an extra calibration is:
      • <number of exposures>x<calibration type>[@<exposure>s]
    • Exposure times are in seconds.
    • If the exposure time is omitted, a default for the requested cal is assumed.
    • Multiple calibration types must be separated by commas and placed in double quotes.
    • 1xcalLFCadj (1xcalEtalonAdj) means one LFC (Etalon) cal will be taken before *or* after target
    • 2xcalLFCadj (2xcalEtalonAdj) means an LFC (Etalon) cal will be taken before *and* after target
    • Examples:
      EXTRACALS  9xbias
      EXTRACALS  2xdark@1200s
      EXTRACALS  2xcalLFCadj

      EXTRACALS  "5xpfipff@89s, 1xcalCd@400s, 1xcalCd@40s, 1xcalNe@100s"

  • FLUX - Flux Standard
    • Spectrophotometric flux standard requested: Y/N
    • Examples:
      FLUX  N

  • GNAME - Group Name
    • Assign a name to related objects collected into a GROUP.
    • Group names must be unique within a given program.
    • Groups should fulfill the requirement of needing to be executionally linked, in the sense that the "ungrouped" execution of their separate members would be devalued. An example would be the spectrum of a galaxy halo that would need an immediately following spectrum of the nearby night sky, constituting a SEQ group. Frankly, think of grouping as an available tool, with the default being NOT to use it.
    • Example:
      GNAME  JKgroup1

  • GTYPE - Group Type
    • Specify the relationship between the targets in a GROUP.

      ___acquisition on ONE night___

    • SEQ - Execute all actions in the GROUP on the same night in the specified sequence, with no other observations permitted in between even if the actions are in separate tracks.
    • AND - Execute all tracks in the GROUP on the same night, with other interleaved observations permitted.

      ___acquisition on MULTIPLE nights___

    • ORD - Execute all tracks in the specified order across one or more nights, with other interleaved observations permitted. The ordering is what distinguishes from unrelated targets.
    • POOL - Execute NUMTODO number of tracks out of the total tracks listed in the GROUP. The subsampling is what distinguishes from unrelated targets.
    • Example:
      GTYPE  POOL

  • HPFCOMPARISON - HPF Comparison lamps
    • This is used for very high precision RV work. These lamps will cause some amount of scattered light through the spectrum so for any kind of abundance work or for very faint sources no comparison source should be selected.
    • For most cases the precision RV work should be done with the LFC (laser frequency comb).
    • For abundance work select "none".
    • If the LFC is not available the choices could also be Uranium or Etalon. These should only be selected with permission from the core HPF team.
    • Example:
      HPFCOMPARISON  LFC

  • INSTRUMENT - Short Name for Instrument
    • LRS2-B - Blue Low Resolution Spectrograph.
    • LRS2-R - Red Low Resolution Spectrograph.
    • HPF - Inhabitable Zone Planet Finder Spectrograph.
    • VIRUS - VIRUS
    • This keyword is required if INSTRUMENT is not supplied
    • This keyword must be in the same block as SETUPMETHOD (either both in the same COMMON block, TRACK_LIST, etc)
    • Examples:
      INSTCONFIG  LRS2-B

  • MAG - V Magnitude of Target
    • GMAG  -  SDSS-g filter apparent magnitude of target
      • required for LRS2-B and VIRUS observations (may be nominal/estimated as appropriate)
      • Example:
        GMAG   18.9
    • RMAG  -  SDSS-r filter apparent magnitude of target
      • required for LRS2-R observations
    • IMAG SDSS-i filter apparent magnitude of target
      • requested for HPF observations, thought not required
    • JMAG  -  near-infrared J filter apparent magnitude of target
      • required for HPF observations

  • NOTES - Program Notes
    • Notes that apply to all tracks, used in the COMMON section of the TSL file.
    • Users tend to confuse the intentions of the NOTES and the COMMENT keywords (see above). COMMENT is for the most concise, vital, real-time instructions necessary for the visit of this target; NOTES is for all targets within the program but should still be concise.

  • NUMEXP - Number of Exposures
    • Number of exposures to take at the given exposure time (EXP).
    • Cannot be used with CRSPLIT as they are mutually exclusive.
    • Example:
      NUMEXP  4

  • NUMTODO - Number in Group to Execute
    • Number of tracks to execute in a GROUP of type POOL.
    • Example:
      NUMTODO  8

  • OBJECT - Object Name
    • Avoid special characters such as single quotes, double quotes, $, &, etc..
    • Avoid spaces, so for "NGC 3379" use NGC3379 or NGC_3379.
    • Names will be truncated downstream at 18 characters, so it is appreciated if the PI limits to 18 characters e.g. by chopping the least significant RA and Dec digits (SDSS users!). Bear in mind that the PI's preferred style of truncation to a maximum of 18 characters, might not match what the RAs have ended up having to do to the overly long name entry; thus curtail your object name lengths pro-actively.
    • Unique object names lead to fewer problems down the road.
    • Examples:
      OBJECT  my_planet
      OBJECT  standard1
      OBJECT  TPS0269
      OBJECT  TPS0269sky
  • OCD - Include observation in OCD
    • If "Y" for a VIRUS observation, it will be included in OCD (HETDEX observation scheduling tool)
    • Example:
      OCD Y
  • OFFSETDEC / OFFSETRA - Offsets in Declination/Right Ascension
    • Allows the PI to specify a 2-d offset relative to the object coordinates.
    • Useful for blind offsets, etc.
    • Both offsetra and offsetdec are given in seconds of arc.
    • Examples:
      OFFSETRA  +2.75
      OFFSETDEC  -5.43

  • OFFSETX / OFFSETY - Offset in X and Y from center of ifuslot
    • Allows the PI to make small offset in IFUslots system to set target into specific CCD
    • Both offsetx and offsety are given in seconds of arc.
    • Examples:
      • Set center to RL:
        OFFSETX  0
        OFFSETY  7

  • PIPRI - PI Priority
    • Allows the PI to specify an order in which to observe her targets.
    • The PI priority only has a practical effect on objects that are clustered together closely on the sky, and would compete with each other in the observing queue.
    • Example:
      PIPRI  2

  • PMDEC - Proper Motion for Declination in mas/yr
    • Proper Motion in Declination direction. This is defined in the same way that GAIA defines this, ie. milliarcseconds per year.
    • If you use this you probably need to consider the EPOCH of the PM. Some GAIA catalogs use 2015.0 while others, like SIMBAD use 2000.
    • Example:
      PMDEC  0.155

  • PMEPOCH - Epoch of the Proper Motion
    • Epoch of the proper motion.
    • Assumed to be 2000.0, unless the PI otherwise specifies.
    • Example:
      EPOCH  2000.0

  • PMRA - Proper Motion for Right Ascension in mas/yr
    • Proper Motion in Right Ascension direction. This is defined in the same way that GAIA defines this, ie. milliarcseconds per year.
    • If you use this you probably need to consider the EPOCH of the PM. Some GAIA catalogs uses 2015.0 while others, like SIMBAD use 2000.0.
    • Example:
      PMRA  0.35

  • PRI - Priority
    • The target priority corresponding to the priority time allocation given to you by the TAC.
    • You may distribute your objects over the priorities assigned by the TAC, or you may "oversubscribe" your top priority.
    • When the TAC's assigned priority has been reached, all remaining targets will automatically receive lower priority.
    • Example:
      PRI  1

  • PROGRAM - Program Number
    • Program identifier in form of IIYY-t-nnn where:
      • II = UT, PSU, STA, M, or G
      • YY = the year
      • t = the trimester 1, 2, or 3
      • nnn = the program number
    • NOAO programs have the form NYY[A|B]-nnnn where YY is the year, the semester is A or B, and the program number is nnnn.
    • Examples:
      PROGRAM  UT01-1-001
      PROGRAM  PSU01-1-014
      PROGRAM  STA01-1-005
      PROGRAM  N07A-0436

  • RA - Right Ascension of Target
    • Right Ascension of target specified to at least 0.1 sec.
    • Coordinates are assumed to be J2000, unless specified otherwise using the EQUINOX keyword.
    • Examples:
      RA  12:12:12.1
      RA  12:12:12.75
  • SEEING - Maximum Seeing
    • Expressed in arcseconds and denotes the maximum permitted delivered image FWHM as measured on the guider cameras in the SDSS g/r/i/ filter nearest to the wavelength of the instrument in use. 
    • Example:
      SEEING  2.8

  • SETUPMETHOD - Setup Method
    • How the target should be setup by the Resident Astronomer and Telescope Operator - required for all targets.
      • This keyword must be in the same block as INSTRUMENT (either both in the same COMMON block, TRACK_LIST, etc)
    • For VIRUS the method can be:
      • DirectGuider for a 2-3" accurate setup using guide star positions
      • ACAMblind for a <1" accurate setup using a blind offset on the HET ACQ camera
    • For LRS2 the method can be:
      • DirectACAM (guide the target into position on the ACQ camera) if the object is brighter than 20 and has a clean reasonable psf for centroiding.
      • ACAMblind for a blind offset (or if object is fainter than ~20th magnitude or unresolved)
    • For HPF the choice can be:
      • HPFACAM for i` < 11 point sources (use high-precision HPF acquisition camera)
      • DirectACAM for i` > 11 point sources (use HET ACQ camera for <1" setup)
    • Example:
      SETUPMETHOD  ACAMblind

  • SKYBRIGHT - Sky Brightness Limit
    • Brightest permitted V filter sky brightness in magnitudes per square arcsec (18-21). Specifying a value of 21.0 will additionally require the moon to be below the horizon.
    • As of July 2020, we require one of the following instead of SKYBRIGHT:
    • SKYBRIGHT_G  -  Sky Surface Brightness Limit in the SDSS g filter
      • Required for VIRUS and LRS2-B observations (14-23 allowed)
    • SKYBRIGHT_R  -  Sky Surface Brightness Limit in the SDSS r filter
      • Required for LRS2-R observations (14-23 allowed)
    • SKYBRIGHT_I  Sky Surface Brightness Limit in the SDSS i filter
      • Required for HPF observations (14-23 allowed)
      • Example:
        SKYBRIGHT_I  20.2

  • SKYCALS - Sky Calibrations
    • A boolean string Y or N indicating whether a twilight sky flatfield frame is required.
    • The current setup is assumed.
    • Example:
      SKYCALS  Y

  • SKYTRANS - Sky Transmission
    • Please specify the minimum acceptable sky transmission.
    • Use either P (photometric), S (spectroscopic), or N (not spectroscopic).
    • These correspond to transmissions of:
      • P   95-100%
      • S   50-95%
      • N ~20-50%
      • all environmental indicators including dust level must satisfy opening criteria
    • The appropriate transmission will be determined from quantitative ancillary indicators.
    • For N conditions, exposure times may be scaled to compensate for S/N.
    • For P and S conditions, exposure times will not generally be scaled.
    • PIs can request there be no scaling.
    • Only the exposure time listed in the Phase II file will be charged, should the actual exposure time exceed it.
    • Example:
      SKYTRANS  P

  • SNGOAL - Signal to Noise Goal
    • Specify the target signal-to-noise ratio of the observations.
    • This should be S/N per pixel per exposure (not per Visit).
    • This is an important guideline but not a guarantee.
    • As of July 2020, this is required for HPF observations, and reflects the continuum SNR per 1D extracted pixel estimated by Goldilocks in the 19th order (order 18 counting from 0). For programs observing emission-line sources, SNGOAL=-1 may be used to indicate its inappropriateness.
    • Example:
      SNGOAL  200

  • SNWAVE - S/N Reference Wavelength
    • Wavelength in angstroms at which to measure the S/N goal.
    • Example:
      SNWAVE  5500

  • STATUS - Target Status
    • Submit your targets as either ready (using "" not " ") or deferred (represented by D) until your later activation. The synoptic and phase-blocking software will automatically sort out if and when the ready target must be blocked (represented by H) or or revert to unblocked (once again ""), with no PI input needed.
    • When you wish that a particular target be no longer used (whether its tally of visits is fulfilled or not), ask for it to be marked as deferred (represented by D).
    • When you wish that a deferred target be activated or re-activated to ready, the synoptic or phase-blocking software will take care of sorting out whether the status becomes ready and unblocked (represented by "") or ready but blocked (represented by H).
    • Example:
      STATUS  D
    • Example:
      STATUS  ""

  • STDCALS - Standard Calibrations
    • A boolean string Y or N to specify whether the standard calibration set should be taken during the night.
    • If Y, note that now any special calibrations specified elsewhere are taken in addition to the standard calibration set. This is a change in meaning from the previous usage of the standard cals question where any calibration requirements other than the standard set required an answer of no.
    • The STDCALS formalism provides the bulk of HET science data calibrations, but additional methods are provided by add-on cals such as e.g. THAR, by the EXTRACALS formalism, and by if necessary forming cals into individual "standalone" targets on their own (typically grouped with associated science targets). This last method is however subject to TAC time charging to the extent that it consumes science time.
    • Example:
      STDCALS  N

  • SYNDATE - Synoptic Date Restrictions
    • For synoptic targets with visits required before, on, or after specific UT dates.
    • Format for dates should be sYYYYMMDD in UT dates, where s is either an   =   meaning precisely on this date, or a   >   meaning on or after this date, or a   <   meaning on or before this date.
    • Multiple specific dates can be separated by a comma with no space e.g. =20070412,=20070415 or with a dash, e.g. =20070412-20070415. If your targets have different exposure times or azimuth restrictions on these dates then you will have to make them separate entries.
    • Date ranges may be given by using two different formats: >20070412,<20070420 or >20070412-20070420.
    • Alternative modes of fine-tuning visit timing are with SYNFREQ and with phase blocking.
    • Example:
      SYNDATE  >20070912,<20070920
      SYNDATE  >20070912-20070920
      SYNDATE  >20071015,=20071018

  • SYNFREQ - Synoptic Frequency
    • Keyword controlling the cadence of visits. #-# is the absolute minimum and requested maximum number of nights cadence from one visit to the next. The result will be a typical visit spacing in that range, but sometimes longer due to constraints, weather, or queue competition.
    • If the SYNFREQ minimum symbol is 0 day and the target has more than one track in the night, we will assume that the target may potentially be observed on both tracks.
    • If the SYNFREQ minimum symbol is 1 day, we will assume that the target may be observed on at most one track in the night, not two.
    • Leaving SYNFREQ blank implies that the target may potentially be observed on more than one track per night. If instead it is intended to limit the cadence to at most one visit per night, use either the keyword SYNFREQ (with minimum symbol 1) or use the keyword SYNDATE (with e.g. the =date formalism) to enforce this. Lacking such indication, the RA potentially may validly observe a target on both tracks within one night by default.
    • By this convention the RA is relieved of continually rechecking on previously observed tracks and can simply rely on software that prevents unwanted intra-night repeat visits via the SYNFREQ or SYNDATE keywords.
    • Alternative modes of fine-tuning visit timing are with SYNDATE =date strings, and with phase blocking.
    • Examples:
      SYNFREQ  RAND1-5
      SYNFREQ  RAND15-30

  • TELL - Telluric Standard
    • A string Y or N to state whether a telluric standard is required. In addition, for planet search work sometimes the PI seems to want a telluric with a different GC configuration than that of the target we have added GC1, GC0, GCboth to cover these conditions and ensure that we get the standard with the configuration that the PI needs.
    • Example:
      TELL  Y
      TELL  GC1


  • TYPE - Action Type - LRS
    • Type of exposure: either a science exposure, or one of the available calibration frames.
    • Examples:
      TYPE  calNe
      TYPE  sci

  • TYPE - Action Type - MRS
    • Type of exposure: either a science exposure, or one of the available calibration frames.
    • Examples:
      TYPE  calNe
      TYPE  sci

  • VIFU - VIRUS IFU
    • Specify the VIRUS IFU slot position which will represent the position of the RA and DEC. The default value is the center of the IHMP (000). The slot number must have leading zero if less then 100.
    • Example:
      VIFU 024

  • VISITS - Number of Visits
    • Number of visits to execute for a given target. Note that a single science object can have multiple "targets," viz. entries in the htopx database. Each target can have multiple visits. Each visit can have multiple CRSPLIT exposures, adding up to the specified total exposure time.
    • Example:
      VISITS  3


Old/rarely used:

AR - Argon Lamps

  • Number of argon wavelength calibration lamps to be obtained during twilight (when standard cals are taken) in addition to any STDCALS or EXTRACALS Ar comparison arcs.
  • Exposure time will be the default for the current setup; otherwise use EXTRACALS.
  • Example:
    AR  5


BIAS - Number of Bias Frames

  • Number of additional bias frames to be taken during the night.
  • This number count will be in addition to any or STDCALS or EXTRACALS biases.
  • The binning will match that of the science target.
  • Example:
    BIAS  4
CD - Cadmium Lamps
  • Number of cadmium wavelength calibration lamps to be obtained during the night in addition to any STDCALS or EXTRACALS Cd comparison arcs.
  • Exposure time will be the default for the current setup; otherwise use EXTRACALS.
  • Example:
    CD  5
DARK - Number of Dark Frames

  • Number of dark frames to be obtained during the night in addition to any EXTRACALS dark frames.
  • Darks are no longer included in the standard set of calibrations due to the very large required overhead and the request will have to be supported by a scientific justification.
  • The binning will match that of the science target.
  • Example:
    DARK  2

FF - Number of Flat Fields

  • Number of flatfield images to be obtained during twilight (when standard cals are taken) in addition to any STDCALS or EXTRACALS flatfield images.
  • Exposure time will be the default for the current setup; otherwise use EXTRACALS.
  • Example:
    FF  5

GRISM - LRS Grism

  • Specify the name of the LRS dispersing element or none for direct imaging.
  • Example:
    GRISM  g2

HG - Mercury Lamps

  • Number of mercury wavelength calibration lamps to be obtained during twilight (when standard cals are taken) in addition to any STDCALS or EXTRACALS Hg comparison arcs.
  • Exposure time will be the default for the current setup; use EXTRACALS.
  • Example:
    HG  2

MASK - MRS Mask

  • Specifies the slit height at the spectrograph input in mm in one of three positions:
      upper (U), center (C), lower (L)
  • Example:
    MASK  3.0C

NE - Neon Lamps

  • Number of neon wavelength calibration lamps to be obtained during twilight (when standard cals are taken) in addition to any STDCALS or EXTRACALS Ne comparison arcs.
  • Exposure time will be the default for the current setup; otherwise use EXTRACALS.
  • Example:
    NE  5
PICHART - PI Finding Chart
  • Allows the PI to provide a URL for a finder chart for the target. Initially charts will be assumed to reside on the PI's website, and will be retrieved by the RA. Precede with https:, http:, or ftp:
  • Examples:
    PICHART  http://puck.as.utexas.edu/HET/UT08-1/chart1a.jpg
    PICHART  "ftp://data1/ChartA.jpg ftp://data1/ChartB.jpg"
THAR - Thorium-Argon Lamps
  • Number of thorium-argon wavelength calibration lamps to be obtained during twilight (when standard cals are taken) in addition to any STDCALS or EXTRACALS ThAr comparison arcs.
  • Exposure time will be the default for the current setup; otherwise use EXTRACALS.
  • Example:
    THAR  2
XE - Xenon Lamps
  • Number of xenon wavelength calibration lamps to be obtained during the night in addition to any STDCALS or EXTRACALS Xe comparison arcs.
  • Exposure time will be the default for the current setup; otherwise use EXTRACALS.
  • Example:
    • XE  3






Last updated: Fri, 31 Jul 2020 09:20:05 -0500 stevenj



Phase II

Phase II Information for New Users

TSL

Language Structure

Language Syntax

Examples

Keyword Table

Keyword Descriptions

TSL Control of Calibrations

Program Notes

Finding Charts

Synoptic Targets

Phase Blocking in TSL

Synoptic Date Block

Phase II Management