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  ""
  
  
• CE - Collecting Efficiency
• Minimum acceptable collecting efficiency ("CE") required for your observation
• CE is the product of sky transparency and pupil illumination (averaged over an exposure)
• Full documentation available here
• Eventually CE will replace SKYTRANS=P/S/N and allow users to specify a minimum CE requirement.
  
  
• 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 (>10 minutes) LRS2 exposures, we strongly discourage the use of CRSPLIT - one single long exposure will provide better sky subtraction and higher quality data.
  • 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.
  • 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.
  • The dither pattern includes three positions and is suitable for filling in the gaps between fibers on VIRUS.
    
  • Default value is 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.
  • Hard-coded to be 2000; cannot be otherwise specified!
  
  
• EXP - Exposure Time in Seconds
  • EXP is the total exposure time in seconds for the Action. When using CRSPLIT > 1, each frame exposure is the CRSPLIT-fold divided fractional part; when using DITHER, each dithered exposure is 1/3 of EXP.
  • Normally the exposure depth contrast due to the slowly changing effective pupil is relatively minor (but if the visit covers the entire track end-to-end, may be significant).
  • If CRSPLIT and DITHER are not 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.
    
    
• 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 (range: 0-99)
  • 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.
  • The PI priority can be any whole number, usually from 0-99 (contact us for situations requiring more dynamic range than that)
  • Unlike TAC-assigned priority (PRI), the PIPRI can be any value the PI wishes
    
  • 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.
  • Hard-coded to be 2000.0, cannot be otherwise specified.
  
  
• 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 time allocation at each priority level
  • If your program significantly exceeds its time allocation within one priority, the over-use will be deducted from remaining time at other priorities so that the program's total allocation is not exceeded.
    
  • Example:
    PRI  1
    
  
  
• PROGRAM - Program Number
  • Program identifier in form of IIYY-t-nnn where:
    • II = UT, PSU, M, or G
    • YY = the year
    • t = the trimester 1, 2, or 3
    • nnn = the program number
  • Examples:
    PROGRAM  UT01-1-001
    PROGRAM  PSU01-1-014
    
  
  
• 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
    

• RVHIGHPREC - RV high precision is required (required for all HPF observations)
• Observation requires highest precision Radial Velocity measurement available (for HPF only)
  
• LFC must be available
• HPF instrument must be stable for 24+ hours
  
• Example:
  RVHIGHPREC    Y

• 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
  • Formerly was the brightest permitted V filter sky brightness in magnitudes per square arcsec (18-21).
    
  • As of Feb 2023, the magic value of 21.0 no longer requires the moon to be below the horizon; use MOONDOWN instead
  • 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-21.5 allowed)
    
  • SKYBRIGHT_R  -  Sky Surface Brightness Limit in the SDSS r filter
  • Required for LRS2-R observations (14-20.5 allowed)
  • SKYBRIGHT_I  -  Sky Surface Brightness Limit in the SDSS i filter
  • Required for HPF observations (14-19.7 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   90-100%
    • S   50-90%
    • 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).
  • Once in the queue, the observing software monitors the number of visits executed on a target. When the tally of visits executed reaches the requested number, its status will change to "D" and it will not be active for subsequent observations.
    
  • 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

FF - Number of Flat Fields

GRISM - LRS Grism

HG - Mercury Lamps

MASK - MRS Mask

NE - Neon 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