TSL Parameter Keyword Descriptions

  • 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

  • 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.
    • This parameter is used primarily form MOS, moving targets, and synoptic targets.
    • For MOS targets this parameter is required because the Tracker rho ring is limited to 180 degrees of rotation and thus East and West tracks will be flipped, requiring different configuration files. For tracks far north or far south the amount of rho angle rotation allows for similar East and West Tracks.
    • See the Position Angle Calculator for more information about PA and azimuth restrictions.
    • Examples:
      AZRES  E
      AZRES  ""

  • 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

  • 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").
    • For blind offset setups, give the name of the .xy setup file.
    • For MOS setups, give the name of the .cfg setup file.
    • For MOS setups, also specify whether this is the West or East track.
    • 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 as to the minimum acceptable length for any "runt" exposure split to be fit in if the end-of-track must curtail the final split. Without explicit guidelines in this situation, a final "runt" split will be undertaken only if it attains at least 50% of nominal length.
    • 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. In the light of this please inform the RA if instead of equal length exposure splits, you would prefer an automated alternative of equal depth exposure splits (as modulated by the effective pupil).
    • Example:
      CRSPLIT  3

  • 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

  • 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

  • EQUINOX - Equinox of Coordinates
    • Equinox of object coordinates.
    • Assumed to by J2000, 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, see the CRSPLIT keyword description for more on this).
    • 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 current setup is assumed.
    • Multiple calibration types must be separated by commas and placed in double quotes.
    • Examples:
      EXTRACALS  9xbias
      EXTRACALS  2xdark@1200s
      EXTRACALS  "5xpfipff@89s, 1xcalCd@400s, 1xcalCd@40s, 1xcalNe@100s"

  • 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

  • FLUX - Flux Standard
    • Give the needed quality level of flux standard, according to the HET flux standard quality listing. E.g. 3 for level three or better flux standards, or Y for any flux standard.
    • If no flux standard is required, enter N. If a particular selection of flux standards is preferred to all the others, not consistent with this basic "quality level" selection scheme, please inform the RAs.
    • Examples:
      FLUX  2
      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

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

  • 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

  • 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

  • INSTRUMENT - Short Name for Instrument
    • LRS2-B - Blue Low Resolution Spectrograph.
    • LRS2-R - Red Low Resolution Spectrograph.
    • This keyword is required if INSTCONFIG is not supplied
    • Examples:
      INSTCONFIG  LRS2-B

  • MAG - V Magnitude of Target
    • Example:
      MAG  18.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

  • 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 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.
    • For MOS setups, please append "W" or "E" for West or East track.
    • Unique object names lead to fewer problems down the road.
    • Examples:
      OBJECT  my_planet
      OBJECT  standard1
      OBJECT  NGC1905_W
      OBJECT  TPS0269
      OBJECT  TPS0269sky

  • 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

  • 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"

  • PIPRI - PI Priority
    • Allows the PI to specify an order in which to observe her targets.
    • The PI priority only has meaning for objects that are clustered together closely on the sky.
    • Example:
      PIPRI  2

  • 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 image fwhm.
    • Example:
      SEEING  2.8

  • SKYBRIGHT - Sky Brightness Limit
    • Please specify the highest permitted V-band sky brightness in magnitudes per square arcsec, on a scale where 21.0 is fully dark when photometric.
    • Values outside the range 18.0 to 21.0 will be truncated to the nearest limit.
    • Example:
      SKYBRIGHT  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 is an important guideline but not a guarantee.
    • 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
    • Example:
      TELL  GC1

  • 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

  • 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

  • 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

  • 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.
    • Examples:
      XE  3






Last updated: Thu, 16 Jun 2016 14:11:22 -0500 shetrone



Phase II

TSL

Language Structure

Language Syntax

Examples

Keyword Table

Keyword Descriptions

TSL Control of Calibrations

Program Notes

Finding Charts

Synoptic Targets

Phase Block

Synoptic Date Block

Phase II Management

Observer Tips