TSL Control of Calibrations

These notes are largely outdated but retained for reference. EXTRACALS is primarily used for HPF LFC cals as of 2020, as explained here.

HET calibration data potentially comprise wavelength comparison arcs, flatfields, biases, darks, skyflats, and flux, radial velocity, and telluric standard stars. Obtaining the right combination for the requirements of your science data requires a minimum understanding the interaction of the TSL target submission language with the service observing practices. For a refresher on the most relevant kinds of calibrations, consult the Phase I pages.

The first distinction to be aware of is that a calibration can be requested in one of two possible modes: as an "standalone" target in its own right, or by the addition of suitable keyword attributes to a related science target. Using the first mode, that of cals as targets (cf. TSL keyword TYPE), the PI has the greatest control over all details of the execution of the calibration, but at the possible cost of TAC time and of some RA inconvenience from the queue being encumbered with a lot of non-science "targets."

Using the second mode of requesting cals via keyword attributes given to science targets, the PI has a choice of three options within this method. The first and most customary option, is to request nightly cals via the STDCALS keyword. These "standard cals" consist of an RA-chosen appropriate number count and exposure level of comparison arcs, flats, and biases. The HRS standard complement includes ThArs, flats, additional gascell-in flats if appropriate, and biases. The MRS standard complement includes ThArs and flats illuminated through the FIF from an interposable lamp, viz. fifthars and fifflats, in contrast to the HRS standard cals which are generated internally to the spectrograph, as well as biases. The LRS standard complement includes appropriate selections of Ar, Cd, Hg, Ne, and Xe comparison arcs, as well as flats and biases.

The exposure durations are RA-chosen to be tailored to the detailed instrumental configuration, and are only rarely adjusted (e.g. for changes of lamp output). The currently exact count number and exposure values are available upon request, or may be inferred from recent observing reports. What if the PI accepts the RA-chosen standard exposure lengths but wants MORE than the number of instances provided by the standard cals? A second optional approach is to select from a set of keywords that provide for adding more (including more than zero) instances of most types of cals. Specifically, the keywords THAR, FF, GASCELL, AR, CD, HG, NE, XE, BIAS, DARK, FLUX, RV, TELL, and SKYCALS (i.o.w. skyflats), when added as attributes of a science target, tell the service astronomer to carry out the indicated cals on that night. If the standard cals already supply a standard number count of such cals (e.g. of flatfields), then the keyword and accompanying count figure is interpreted to be requesting ADDITIONAL instances in excess of the standard number count. Clearly it is a mistake to use this option unless you truly want MORE THAN the standard number provided. Note as well that this option is NOT the way to request cals specially carried out as time-ADJACENT to a given science target (see below).

(The g1, g2, and e2 grisms receive standard comparison cals of AR NE XE and a simultaneously exposed CD+HG+AR combination designated CMA (cadmium mercury argon) in the night report. If wanted, distinct cals of CD or HG can be requested via those keywords. The e2 grism receives standard comparison cals of AR and NE. If wanted, additional cals of XE CD or HG can be requested via those keywords. Warm-up and integration lengths are aimed at capturing the largest range of lines at a good level, with particular attention to wavelength coverage. When line strength disparity justifies it, two contrasting exposure durations are recorded, with negligible added overhead.)

The keyword EXTRACALS provides a third keyword-mode approach for specifying cal requests, and it offers the additional capability of allowing PI-chosen exposure lengths as well. (Cal exposure lengths supplied by PIs in any other contexts are merely placeholders for the standard cals exposure lengths that will be executed.) Use this option if added very long or very short exposure cals offer advantages beyond those of standard exposure length.

Calibrations are typically finished off at the end of the night, but may be executed at ANY convenient time opening in the course of the night. In order to secure particular calibrations carried out time-ADJACENT to particular science, include a phrase early in the COMMENTS keyword text space (e.g. "ThAr before" ... "ThAr after" ... etc). Such incidental cals are not counted in the cals tallying described above. The alternative mode to cause cals to be carried out time-ADJACENT to particular science is the above-mentioned one of creating actual cals "targets" and then grouping them with science targets using the GNAME and GTYPE keywords.

Besides registering the need for time-ADJACENT cals, the COMMENTS are the best place to request HRS fifflats, fifthars, or pfipflats, as these are not provided with their own dedicated keywords.

These notes are largely outdated but retained for reference. EXTRACALS is primarily used for HPF LFC cals as of 2020, as explained here.

Some Miscellaneous Cautions --

• If the required standard star setup is in any detail different from the associated science target setup, a special step may be needed. Most conveniently simply note the requirement at the start of the COMMENTS. Alternatively create the individual "standalone" targets for any standard star setup that departs in any way from the associated science target setup. However, in the case of telluric standards, extra keyword values have been coded (GC0, GC1, GCboth) which afford a full choice of using the iodine gascell in the standard star spectrum, independently of the gascell role in the science spectrum.

• If requesting a specific standard star time-adjacent to a science target, be aware that this can engender some scheduling difficulty in the case of intense queue competition for that sidereal time range. Possibly a choice several acceptable adjacent standard stars (in a POOL-type group) might be tried.

• A "comparison sky" is not usually counted among the scientific data calibrations, because it is always treated as an individual "standalone" target grouped (SEQ-type) with its science object. Realize that the observer may have to secure the science target earlier or later in the track than the anticipated ideal time. Thus to prevent a time collision or gap, the observer may choose to execute the "sky target" at a right ascension shifted from the nominal, but an empty sky field will nonetheless be carefully selected.