Documentation for the scripts included with TUI.
Run a set of commands, one at a time. Each command runs to completion before the next command is executed. If any command fails, the script aborts. You may save your commands to a file and retrieve them again later.
The results of the commands do not show up in the Run_Commands window. If you can't see what you want in TCC's various displays then open the Log Window
Commands Format
Each line must be one of:
Example:
# sample commands that are safe to run
The rest of the window shows the usual script status bars and controls.
Caveat
Run_Commands provides a simple way of running a fixed set of commands. It is very easy to use, but also very limited. If you find yourself wanting more control or flexibility then I encourage you to write your own script.
The DIS:Drift script allows you to take a time series of spectra by moving the object along the slit in the +X direction during an exposure.
The range of motion is centered on your starting position, so typically you should begin by putting your object in the center of the slit. Note that the slit is 400" long, but the slit viewer can only see the middle 150" of that. If you try to use the full 400" you risk losing some of your exposure because we are not sure the slit is precisely lined up along the X axis.
In detail, the script performs the following sequence:
The Echelle:Trail script allows you to "trail" the telescope up and down along the slit while taking an Echelle exposure. You specify the number of trails (drifts in +Y or -Y along the slit) and length of each trail.
As Don York explained: trailing is used with the echelle to distribute charge over the CCD, especially for bright star work. The CCD saturates around 34,000 DN. The S/N per exposure can be increased by root 2 with trailing and the readout per unit S/N is reduced, a significant savings for exposures on stars brighter than 6th mag (6 minute exposure to just saturate.)
The range of motion is centered on your starting position, so typically you should begin by putting your object in the center of the slit.
Warning: trail length is input in arcsec but is also reported in percent. Unfortunately, this is percent of the default slit, and so is not necessarily correct for the current slit. This problem can only be fixed if the hub starts reporting the length of the current slit.
The NICFPS:Data Cube script allows you to take a sequence of exposures over a range of wavelengths. Controls (items in bold are required):
Warning: this script does not restore the etalon z spacing to its original value when done. So NICFPS will almost certainly have a different spacing after you run this script.
If you must interrupt a data cube partway through, record the Current Index plus all input parameters. Then to restart the data cube later, set Initial Index to the recorded Current Index and restore all other input parameters.
Warning:> if you wait too many days before restarting the data cube, the earth's velocity may have changed too much with respect to your target (producing a doppler shift). If in doubt, discuss this with the telescope operator or (during the day) the instrument scientist.
The NICFPS:FPCalibrate script allows you to take Fabry-Pérot calibration data. The script takes a sequence of images over a range of Fabry-Pérot etalon positions, as specified in a file.
The file format is as follows:
Here is a short sample file:
# Data for the NICFPS:FPCalibrate script # x y z position (integer steps) 0 0 0 100 -25 33
The input controls for the script are as follows:
Warning: this script does not restore the original etalon position when it is done, so the etalon will almost certainly be in a new position after you run this script.
The NICFPS:Dither:Point Source Random script allows you to take a sequence of exposures in a square pattern plus a point in the middle. This pattern is typically used for point sources.
The requested number of exposures is taken at each point before moving on to the next. The order is as shown below. Any dither point may be omitted by unchecking its checkbox before running the script. Ctr is always your current telescope pointing, even if you omit Ctr.
Dither pattern without randomization
Controls include:
Randomization helps to reduce residuals when median combining the images, especially with #Exp > 1. The random component is evenly distributed across the region independently in x and y.
For example, if #Exp = 3 and Box Size = 20", the script might do the following, taking exposures in the order indicated by red numbers:
Dither pattern with randomization
The NICFPS:Dither:Extended Source script allows you to a set of take pairs of dithered source/sky exposures. These pairs of exposures are taken over various points of a small 5-point dither pattern.
The sequence is to take NExp exposures at each point before moving on to the next, in this order:
NExp
The input controls are ignored once the script starts (as usual for scripts).
As the script runs the status of each dither point is updated. This status is retained when the script ends so you can see what happened. It is cleared when you start a new run.
Note: the small dither pattern is aligned with the axes of your coordinate system (typically RA/Dec). This differs from the NICFPS:Dither:Point Source script, whose dither pattern is aligned with the detector. This is because Extended Source uses object offsets whereas Point Source uses boresight offsets. If north is up on your image then the patterns will be the same.
Thanks to Corey Wood for the first implementation of this script.
The SPIcam:Sky Flats script allows you to take a series of twilight or morning flats, automatically increasing or decreasing the exposure time to roughly maintain a constant brightness for the images and dithering the telescope (using a 15" box) between each exposure. If you don't want automatic adjustment of exposure time then please use the normal SPIcam Exposure window, instead.
This script uses the current time to decide whether you are taking twilight flats or morning flats. For evening flats the time increases using equation:
nextEveTime = -288 log(e-prevTime/288 + e-(prevTime+45)/288 - 1) - (prevTime+45) (or 160 if prevTime is too large)
and for morning flats the time decreases using equation:
nextMornTime = 288 log(eprevTime/288 + e(prevTime+45)/288 - 1) - (prevTime+45) (or 1 if prevTime is too short)
Note: even the time of the first exposure is compensated. This allows you to take an exposure, enter that time (with some suitable correction if the image was too light or too dark) and start the script without having to mentally compensate for changing sky brightness.
As usual for scripts, the input options are recorded when you press "Start" and ignored thereafter. Thus you must stop and restart the script to run it with different settings.
Note: this script uses the same time compensation used by the original SPIcam eveflat and mornflat scripts (but with limits to avoid crashes).
The Telescope:Pointing Data script takes set of pointing error measurements of pointing reference stars across the sky. It logs the results to a data file which can be used to fit a pointing model.
The script runs in one of two modes, controlled by the Attended Mode checkbutton:
Note:
You may change any parameter except Az/Alt Grid while the script is running; the new value will be used as soon as possible. For parameters you type (such as exposure time), you must type <tab<> or <enter> or click on a different field to save the new value; unfortunately there is no visual feedback indicating if a value has been saved. If you want to change several values at the same time, you may wish to pause the script while you make the changes.
Select an az/alt grid, adjust any other settings as desired, then push Start. For each point in the az/alt grid the script will find and slew to a nearby pointing reference star, measure the star, write the pointing error to a data file whose path is displayed, and correct the pointing error.
The graph shows the grid of az/alt points. While a star near a grid point is being measured, that grid point is shown as a large blue star. Once the star has been measured, the grid point is a small green star, or a red X if the star could not be measured. Note that the graph does not show the positions of the pointing reference stars (to avoid clutter) nor the measured error (because TPOINT does this so much more better).
The data file can be read by TPOINT and used to fit a pointing model. You will also want access to the the current pointing model (to get the terms we use, and to see how much pointing has changed). You can get that from tcc35m-1-p in tccdata/telmod.dat.
A few grids of az/alt points are built in. TUI looks for additional grids in TUIAdditions/Grids/*.dat. The Az/Alt Grid menu is rebuilt each time you click on it, so you can add, delete or modify grid files while TUI is running.
You may generate additional grids using the MakeGrid application, or generate files by hand. The format of grid files is one line per point: az alt (decimal degrees, no comma separating them). Lines starting with # or ! and blank lines are ignored. Leading and trailing whitespace is also ignored. For example:
# azimuth altitude # (deg) (deg) 91.02 51.43 126.52 15.08 ...
The TSpec:Nod script takes a set of TripleSpec exposures alternating between two points A and B in the pattern A1 B1 B2 A2.
The script always moves the telescope back to point A at the end, even if the script fails or you cancel it.
Thus if #Exp = 3 and Cyles = 5 the script will take 60 exposures: 3 exposures at each point, 4 points in a cycle, 5 cycles.
