Nordic Optical Telescope

FIES and STANCAM SEQUENCER Script Reference

FIES setup scripts
FIES exposure scripts
Examples of using FIES scripts

StanCam calibrations scripts (stancam.script in user scripts)

biases
Takes eleven full frame unbinned (1x1 bin) bias frames, updates the FITS-header to CALIB and stores the frames in the calib-directory
flat tt
Makes an exposure of tt seconds, sets imagecat to "CALIB", imtype to "FLAT/SKY" and copies the file to /service/calibs. To abort the exposure press "Control-C".

FIES instrument-setup scripts (fies.script in user scripts)
These scripts use the FIES status database to check whether instrument items need to be moved or not. In general, the overheads will be smaller when using these scripts, than when using the basic sequencer commands.
If any of these setup scripts are started while a FIES integration is ongoing, the script will wait for the integration to finish, and will start moving things around during readout.

lampsoff
Will switch off all lamps, i.e. lamps 1, 4, 6, 7.
NB: as an exception this script does not read the database settings: it commands the lamps to be off even if they are supposedly off.

setup-ccddefaults
Sets up the CCD parameters and some administrative parameters to default values, as they are set when restarting the observing system. Equivalent to the commands:
fies.clearobject; fies.gainhi; fies.ampl B; fies.resetxy; fies.autosave_on; fies.remsave_off; fies.rempath /data/service; fies.remsystem verushka

setup-fib1-star [-v]
setup-fib2-star [-v]
setup-fib3-star [-v]
setup-fib4-star [-v] [-doNotSwitchOffTopThar]
Sets up necessary FIES items (mask, arm, lamps) for a FIES science (object or sky) exposure and for FIES/STANCAM target acquisition, for the indicated fiber. All lamps will be switched off, except for the top ThAr lamp in case -doNotSwitchOffTopThar is specified .
Use the [-v] flag for verbose output on the sequencer command terminal.

setup-fib23-star [-v]
As above for simultaneous sky mode, on med-res fibers 3 (target) and 2 (sky).

setup-fib1-thar [-v]
setup-fib2-thar [-v]
setup-fib3-thar [-v]
setup-fib4-thar [-v]
Sets up necessary FIES items (mask, arm, lamps) for FIES ThoriumArgon wavelength calibration for the indicated fiber. The ThAr lamp will be switched on, and all other lamps switched off.
Use the [-v] flag for verbose output on the sequencer command terminal.

setup-fib1-halo [-v]
setup-fib2-halo [-v]
setup-fib3-halo [-v]
setup-fib4-halo [-v]
Sets up necessary FIES items (mask, arm, lamps) for a FIES Halogen flatfield or order-definition exposure for the indicated fiber. The Halogen lamp will be switched on, and all other lamps switched off.
Use the [-v] flag for verbose output on the sequencer command terminal.

setup-fib5-thar [-v]
setup-fib5-halo [-v]
Sets up necessary FIES items (calshutter, calmove, lamps) for FIES ThoriumArgon/Halogen calibration of the calibration fiber (the fiber used for simultaneous ThAr mode). The indicated lamp will be switched on; the calibration shutter will be set to open.
Use the [-v] flag for verbose output on the sequencer command terminal.

FIES exposure scripts (fies.script in user scripts)
Note that these scripts do not set any CCD parameters.

exp-fib1-star [-v] [-f] [-nobell] exptime ["objectname"]
exp-fib2-star [-v] [-f] [-nobell] exptime ["objectname"]
exp-fib3-star [-v] [-f] [-nobell] exptime ["objectname"]
exp-fib4-star [-v] [-f] [-nobell] exptime ["objectname"]
Scripts to take a FIES object/sky spectrum using the indicated fiber. The scripts go through the following sequence:
- execute the appropriate setup-fib?-star script (see above)
- set the object name if specified on command line
- take a FIES spectrum, with exposure time as specified on command line The object name needs double quotes if it contains spaces.
Use the [-v] flag for verbose output on the sequencer command terminal.
Use the [-f] flag for fast mode: the script will return the prompt when read-out starts, such that new setup commands can be issued while reading out the CCD.
Use the [-nobell] flag to suppress the alarm bell at the end of the exposure.

exp-fib1-thar [-v] [-f] [-nobell] exptime ["objectname"]
exp-fib2-thar [-v] [-f] [-nobell] exptime ["objectname"]
exp-fib3-thar [-v] [-f] [-nobell] exptime ["objectname"]
exp-fib4-thar [-v] [-f] [-nobell] exptime ["objectname"]
Scripts to take a FIES ThoriumArgon wavelength-calibration spectrum using the indicated fiber. The scripts go through the following sequence:
- execute the appropriate setup-fib?-thar script (see above)
- set the object name if specified on command line, or else "ThAr"
- set the image type to "WAVE"
- take a FIES spectrum, with exposure time as specified on command line
- switch off the ThAr lamp afterwards The object name needs double quotes if it contains spaces.
Use the [-v] flag for verbose output on the sequencer command terminal.
Use the [-f] flag for fast mode: the script will return the prompt when read-out starts, such that new setup commands can be issued while reading out the CCD.
Use the [-nobell] flag to suppress the alarm bell at the end of the exposure.

exp-fib1-halo [-v] [-f] exptime ["objectname"]
exp-fib2-halo [-v] [-f] exptime ["objectname"]
exp-fib3-halo [-v] [-f] exptime ["objectname"]
exp-fib4-halo [-v] [-f] exptime ["objectname"]
Scripts to take a FIES Halogen flat spectrum using the indicated fiber. The scripts go through the following sequence:
- execute the appropriate setup-fib?-halo script (see above)
- set the object name if specified on command line, or else "Halogen"
- set the image type to "FLAT"
- take a FIES spectrum, with exposure time as specified on command line
- switch off the Halogen lamp afterwards The object name needs double quotes if it contains spaces.
Use the [-v] flag for verbose output on the sequencer command terminal.
Use the [-f] flag for fast mode: the script will return the prompt when read-out starts, such that new setup commands can be issued while reading out the CCD.

fies-calibs [-noFIEStool] [-doF5] [-nflat N] [-nbias N] [-amp B/AB] [-bin 1x1/2x1/2x2] [-fib 1-4]
This is a script to take a default set of 1 ThAr, 7 bias, and 21 halogen frames, which constitutes a good set of calibration frames for normal use of FIES without the simultaneous-ThAr mode. This set of calibration frames can be used for FIEStool: the script can setup links such that FIEStool can easily find the new calibration data, and subsequently lets FIEStool pre-reduce the new calibration data into master calibration frames to be used the next night.
If less than 7 bias or 21 halogen frames are requested the FIEStool links will not be made, and pre-reduction will not be executed.
If no command-line arguments are given, the script prompts the user to specify the FIES fiber and other relevant parameters.
If any command-line arguments are given, then the -fib argument is mandatory.
Binning mode 1x1 and amplifier B are set by default.
In case the binning is chosen as 1x1, and either the med-res or high-res fiber is selected, and the flag -doF5 is given, then also 1 ThAr and 1 halogen will be obtained using fiber #5, which provides a minimal set of calibration files for the simultaneous-ThAr mode. Nevertheless, for simultaneous-ThAr mode additional calibration frames might be necessary.
The script can be run in the afternoon and takes about 45 minutes to complete, or less if CCD binning is requested.
The exposure times for the ThAr and halogen frames are determined in the script by automatically taking and analysing windowed test images. The exposure time of ThAr frames is scaled to get 80000 ADU peak count level in the bright 4764.8 Ar line. The exposure time of halogen frames is scaled to get a peak count level of 350000 ADU.

easythar [-f] [-o "objectname"] [-nthar N] [-factor expFactor]
easyhalo [-f] [-o "objectname"] [-nflat N]
Note: the command syntax of the -o flag was changed Dec 2010.
Scripts to make a ThAr wavelength calibration frame or a halogen flat-field frame, respectively. These scripts do not do any instrument setup: use the setup-fibN-thar or setup-fibN-halo scripts prior to using the 'easy' scripts.
The exposure times for the ThAr and halogen frames are determined in the 'easy' scripts by automatically taking and analysing windowed test images. The exposure time of ThAr frames is scaled to get 80000 ADU peak count level in the bright 4764.8 Ar line. The exposure time of halogen frames is scaled to get a peak count level of 350000 ADU.
For high-accuracy radial-velocity work, the ThAr exposure level can be scaled up with the [-factor] option. The exposure time will be multiplied by the user-supplied factor.
Use the [-f] flag for fast mode: the script will return the prompt when read-out starts, such that new setup commands can be issued while reading out the CCD.
The default object names are "ThAr" and "halogen", respectively. The default number of exposures is 1, which can be altered with the [-nthar] and [-nflat] flags respectively.
Note that the lamp is left on after the script has finished.

simulthar [-f] exptime lamptime
Script to take a FIES spectrum in simultaneous-ThAr mode. The ThAr light will be inserted into the spectrograph in 10 short pulses, which are equally distributed in time over the full CCD exposure time exptime. This is done by opening and closing the calibration shutter. The parameter lamptime specifies the total time that the ThAr light will enter the spectrograph, which is typically only a few seconds.
This script goes through the following sequence:
- execute the setup-fib5-thar script (see above)
- determine the timings of the ThAr pulses
- set the COMMENT/CALSHUTN/CALSHUTD header with this ThAr timing info
- take a FIES spectrum, with exposure time as specified on command line
- close the calibration shutter afterwards
Use the [-f] flag for fast mode: the script will return the prompt when read-out starts, such that new setup commands can be issued while reading out the CCD.
Note that the ThAr lamp is left on after the script has finished.

Examples using basic FIES sequencer commands and FIES sequencer scripts

setup-fib4-star

and after the star is put on the fiber (using StanCam), take a 12-minute spectrum and a 10-second ThAr calibration spectrum:
exp-fib4-star 720 "my target star"
exp-fib4-thar 10 "ThAr at my target star"

2) Now for target acquisition on the med-res fiber #3:
setup-fib3-star

and after the star is put on fiber #3, take a 12-minute spectrum with simultaneous ThAr calibration in fiber #5, with 4 seconds exposure time for the ThAr lamp:
object "my target star"
simulthar 720 4

3) Now the lines of a high-level script for obtaining a 1800-second spectrum using low-res fiber #1, sandwiched by ThAr calibrations:
autosave_on
resetxy
ampl AB
bin 2
exp-fib1-thar 10 "first ThAr"
exp-fib1-star 10 "my target"
exp-fib1-thar -f 10 "last ThAr"
Note that with amplifier mode AB the readout time is halved, but the central order of the echellogram is lost.

4) Take 21 two-second flats in the afternoon with med-res fiber #3:
setup-fib3-halo
object "flat Halogen"
mexpose 2 21

5) Use easythar for med-res fiber #3, to make a ThAr exposure at night:
setup-fib3-thar
easythar "ThAr HD12345"

FIES-related STANCAM target-acquisitioning scripts (stancam.script in user scripts)
These scripts should be executed in the STANCAM sequencer.

acquisition [-e] [-hicut xxxx] fiber expotime

-e	test flag: don't execute, only echo the commands
-hicut	DS9 high cut in ADU
-std	sets IMAGETYP='STD', else IMAGETYP='OBJECT'
fiber	fiber specifier [1,2,3,4]
expotime	expo time for unbinned acquisition image

Script for FIES target acquisition. Will first make a binned full-frame acquisition image, does fiboff, and will then go into movie mode using an unbinned window around the fiber.
This script makes sure that the mask and arm are positioned correctly for each step in the target acquisition.
Exits with full-frame unbinned CCD settings, and autosave_on.

The sequence of STANCAM sequencer commands in this script is: stopmovie, camera-probe-stancam, autosave_on, resetxy, bin 2, object "FIES target acquisition", expose, resetxy, fiboff, camera-probe-fies, setup-fibN-star, fork-fibNmovie .

stancam.fibpos-man fiber

fiber fiber specifier [1,2,3,4]

Fiber guider: updates the reference fiber position (green cross). Can be used either during a movie-mode or in direct imaging.
- Movie Mode:If the green cross does not coincide with the actual center of the fiber, you may want to update the position manually. This is particularly important at the beginning of the exposure, and even more important when switching between fibers and/or at the begining of the night as the mismatch between the reference fiber position and the actual position can be several pixels. This command brings up an interactive imexam session. With the mouse, place the cursor at the position in the DS9 image that corresponds to the fiber center. Press 'x' to mark this point, then press 'q' to quit the imexam session. The fiber reference position is updated immediately, and the telescope is offset to bring the target onto this position.
- Direct Imaging: Used to calibrate the position of the fibers for StanCam direct imaging (camera-probe-stancam/camera-probe-ccd) by running the script fibposcalib.
In either mode, the new fiber position is checked against the latest recorded position. If the position deviates by more than 40 pixels, an error message will appear and the script exit. Should the very unlikely event happen that the position actually deviates by more than 40 pixels from previous, run the script multiple times with adjustments within 40 pixels. If the position deviates by more than 20 pixels, you will need to confirm the reposition as this is a shift larger than expected.
stancam.fibpos-update
Fiber guider: use last computed fiber position (blue cross) as new reference position (green cross).

stancam.fibpos-snafu
Fiber guider: reset all fiber positions (green cross) to some appoximate default values. This command is typically used to recover from a runaway of the green-cross position, which should normally be indicating the center of the fiber. No need to interrupt ongoing exposures or restart the observing system after using fibpos-snafu. After issuing the command the green cross should be fairly close to the fiber positions, however proper determination of fiber positions afterwards using fibpos-man is highly recommended.

fiboff -p [FIES|CCD] fiber
Calculates the telescope offset required to bring a target onto a given fiber (number 1 to 4) and performs the required telescope offset. The script uses the currently loaded StanCam image in the DS9 display and assumes this corresponds to an acquisition image of the field the telescope currently is pointed at. The target is identified interactively by the user through an imexam session. Optionally, the camera probe position can be specified with '-p', which can decrease the overheads associated with the fiber offset routine.

fibmark [yes|no]
Creates a DS9 region file consisting of the fiber positions and rotator center (acquisition image only) corresponding to the StanCam image currently loaded into DS9. The positions will be marked on every image displayed until the script is run with the 'no' option. This script is mainly useful for the movie display mode. Default 'yes'.

fib1window
fib2window
fib3window
fib4window
Sets up a 100x100 pixel window around the fiber in question. Should be used with STANCAM in fiber-viewing mode (camera-probe-split).
fib1movie exptime hi-cut
fib2movie exptime hi-cut
fib3movie exptime hi-cut
fib4movie exptime hi-cut
Argument exptime specifies the exposure time to be used, and argument hi-cut specifies the colour cut on the image display.
Starts up STANCAM movie-mode in a 100x100 pixel window around the fiber in question.
Should be used with STANCAM in fiber-viewing mode (camera-probe-split).
When starting a new movie, any ongoing movie will be automatically stopped first.
To change the exposure time of an ongoing movie, use the expmovie command as documented below. To change the ds9 colour cuts during an ongoing movie, you can use the commands locut and hicut, or restart the movie with the appropriate colour cut level.
Note that the movie has to be stopped by pressing CNTR-C or by stopmovie, and that it sets autosave_on at exit, and resetxy at exit to go to full-frame unbinned readout.
fork-fib1movie exptime hi-cut
fork-fib2movie exptime hi-cut
fork-fib3movie exptime hi-cut
fork-fib4movie exptime hi-cut
Forks the movie in a separate pop-up SEQUENCER window. This is useful when invoking the movie-mode from a script, which can then subsequently start a FIES-spectrum exposure.
When forked from a script, the movie can be stopped or restarted without affecting the calling script.
The comments on the previous item (fibNmovie) also apply to fork-fibNmovie.
expmovie exptime
Change the exposure time of an ongoing movie to exptime, without having to restart the movie. Valid exposure times: 0.1s - 30s
stopmovie
Will stop the ongoing movie mode (i.e. fibNmovie, fork-fibNmovie).
Sets resetxy at exit to go to full-frame unbinned readout.

STANCAM/FIES miscellaneous scripts (stancam.script or fies.script in user scripts)

log-comment "Comment in quotes" [file1 file2 file3 ...]
Adds a remark to the FITS headers of an existing data file, in the LOGCOMME keyword.
When invoked with just the comment, it will be applied to the latest available image with a prefix for the current night (which starts at noon) and the sequencer's instrument.
If image names are provided, the program will test the existence of ALL them before applying the change.
Eg.
```
        $ stancam.log-comment "This is a comment"

        $ fies.log-comment "Comment for two" FIug170154 FIug170155
```
Notice that there's no need to add the ".fits" after each image's name
If no arguments are provided, a usage message is displayed

wait-camera-state idle|integrating|readout|pending|not-integrating
Wait until the ccd camera is in the requested mode. NB!: waiting for the mode to be 'readout' without starting an integration afterwards will lead to infinite waiting.
'not-integrating' will likely be the most usefull state to wait for.

runselector <date>
A command line frontend to set the PROPID,PROPTITL & PINAME fits keywords for the current observations. Choose the program being observed from a drop-down menu. The optional date argument displays programs for that date.

runselectorUIF [alfosc|fies] <date>
A GUI frontend to set the PROPID,PROPTITL & PINAME fits keywords for the current observations. Choose the program being observed from a drop-down menu. The optional date argument displays programs for that date. This GUI is started automatically when starting the observing system

StanCam/FIES DS9 and Analysis scripts (stancam.script or fies.script in user scripts)

setdisplay [X server]
Set the X server on which the StanCam/FIES DS9 window will be displayed. If no X server is specified, the server from which the command is issued will be used. Note that the X server must allow for remote connections (use 'xhost').

display-start
Starts an empty StanCam/FIES DS9 display. The display will be named STANCAM, but will hold two frames; Frame 1 will contain the last StanCam image and frame 2 will contain the last FIES image.

display [file]
Loads an image into the StanCam/FIES DS9 display. If no file is specified, the last image obtained will be loaded. If no DS9 display exists, one will be started (see also display-start).
When fies.display is used a FIES image will be displayed.
When stancam.display is used a StanCam image will be displayed.

focus-auto focus-step-size [image]
Computes the best focus value from a focus sequence image taken with the command 'focusexpose'. If no image name is given, the last obtained image will be used. The computed focus value is not automatically sent the the TCS.

overlay [yes|no]
Overlays the loaded StanCam image with seeing information and marks saturated objects.

hicut value
Applies a minmax scaling of the loaded image and sets the highcut to the value specified.

locut value
Applies a minmax scaling of the loaded image and sets the lowcut to the value specified.

restore-uparm
Populates the iraf uparm directory, used by the pyraf based sequencer scripts, with some known working parameter files.

wcs-align [yes|no]
Display the loaded image using world coordinates such that North is up. Called with the 'no' option, the image is aligned according to orientation on the detector.

zscale
Sets the upper and lower limits of the loaded image based on the IRAF ZScale algorithm. (Displays the image values near the median image value).

imexam
Initiates an IRAF imexam session on the image(s) currently loaded into the StanCam/FIES DS9. The session will always operate on the frame where the cursor is placed, no matter which frame has got the focus. You can move the cursor between the two frames - imexam will operate correctly anywhere. While active in the imexam session, no further commands can be issued from the sequencer window.

CURSOR KEY COMMANDS:

?       Print help
a       Aperture radial photometry measurement (see above for output)
c       Column plot
e       Contour plot
f       Redraw the last graph
j       Fit 1D gaussian to image lines
k       Fit 1D gaussian to image columns
l       Line plot
m       Statistics
            image[section] npixels mean median stddev min max
q       Quit
r       Radial profile plot (see above for output)
s       Surface plot
x       Print coordinates
            col line pixval [xorign yorigin dx dy r theta]

killdisplay
Terminates all instances of the StanCam/FIES DS9 display.

killimexam
Terminates all FIES sequencer scripts related to imexam and the StanCam/FIES DS9 display.

Staff-only scripts

fies.fies-FS
Staff-only script for obtaining flux-standard QC.

fies.fies-RV
Staff-only script for obtaining RV-standard QC.

stancam.change-filter
Interactive program to update filter information of the STANCAM filter cassette after having changed a filter. Information will be updated both in the optical database and in the TCS. DO NOT UPDATE FILTER INFORMATION ON THE TCS CONSOLE. USE THIS PROGRAM INSTEAD.

stancam.edit-fibposccd [ editor ]
stancam.edit-fibposccd -h
stancam.edit-fibposccd -test
Edit the fibposccd.def file and make sure the values on it are sane. Uses emacs by default. Provide your favourite editor name otherwise.
As an alternative, it can be used only in "test" mode to check the file, without launching the editor.
Calling the script with -h will provide more detailed help.

stancam.edit-fibpossplit [ editor ]
stancam.edit-fibpossplit -h
stancam.edit-fibpossplit -test
Edit the fibpossplit.def file and make sure the values on it are sane. Uses emacs by default. Provide your favourite editor name otherwise.
As an alternative, it can be used only in "test" mode to check the file, without launching the editor.
Calling the script with -h will provide more detailed help.

stancam.fibposcalib fiber expotime
Interactive script to calibrate the position of the fibers for StanCam direct imaging (camera-probe-stancam/camera-probe-ccd).
Runs stancam.acquisition to let the user center the star on the fiber, then swaps back to camera-probe-stancam and lets the user determine the star=fiber (X,Y) coordinates with stancam.fibpos-man.

stancam.qc-script (Stancam)
Takes a sequence of two bias frames and two (dome) flat fields and calls gainron (see below) to calculate gain and read-out-noise.

stancam.gainron [file] (Stancam)
Computes detector gain and read-out-noise based on a sequence of two bias frames and two flat fields. The filename must be the last in the sequence.
If no filename is given, the last obtained image name will be used. Calculated values are being compared to previous values before being uploaded to database.
If the deviations from previous results are found to be too large, the script can be terminated without uploading results.
killpostprocess
Terminates all FIES sequencer commands and the StanCam/FIES DS9 display. Note that this will terminate any running observing scripts.

stancam.movie-expose [-d][-t] tt (This is technically speaking not a script, but a command)
Makes an exposure of tt seconds. To abort the exposure press "Control-C". If the '-t' option is used, a simulated exposure is made. This is usefull for script testing.
This command will not output any messages to the talker unless started with the -d option. Used in scripts for movie mode. This command is not aliased, so it can only be used by the full name stancam.movie-expose.

setup-fibguider-on
Setup observing system to use the fiber guider. Files affected: rc.postprocess, fibNmovie

setup-fibguider-off
Setup observing system to *not* use the fiber guider. Files affected: rc.postprocess, fibNmovie

stancam.fibguider-config [options]
Sets parameters used for the fiber guiding routine. Options:
default
guider=[enabled|disabled]
analyser=[enabled|disabled]
outermask=[big|small|disabled]
hicut=[auto|manual]
guidegain=[0.1,0.2,0.3,...,1.0]
tc=[1,2,3,...,60]

stancam.fibguide-playback <yyyymmddhhmm|yyyymmdd> [statsonly]
Playback any stancam fibmovie sequencer that was being created at the moment of yyyymmddhhmm. Corresponding fibguider crosses are shown in the DS9 and any telescope offsets and fiber position updates are output in the terminal window. Useful for evaluating the fibguider performance.
If the date is given as yyyymmdd, all fiber movies for that particular date will be processed. This is particularly useful together with the 'statsonly' argument, in which case there will be no playback but only listed the statistics for each movie.

stancam.fibpos-compute [filename] [fiber] [no_images]
Computes fiber center for a given [fiber] by analyzing last [no_images] prior to [filename]. Results are shown in plots, and user can adopt new fiber position as reference position.