Observing Commands

Glossary of MODS1/2 commands

This table lists the commands used to run scripts, align targets in long-slits or multi-object masks, display images and check the status of or start/stop services are listed below with a brief description of their function.

 

MODS1	MODS2	Description
mods1 status	mods2 status	brings up a status panel showing the status of mods services and owners
mods1 start gui	mods2 start gui	opens the MODS Control Panel
mods1 stop gui	mods2 stop gui	closes the MODS Control Panel
acqMODS –mods1	acqMODS –mods2	for running an acquisition script
acqBinoMODS		for running a binocular acquisition script
execMODS –mods1	execMODS –mods2	for running an obs, img, cal, or pro script
execBinoMODS		for running a binocular obs, img, cal, or pro script
modsDisp	mods2Disp	Automatically displays last MODS blue and red channel images
modsAlign		For centering an object on slit or aligning a mask. It will read the header to determine for which MODS it will be run. modsAlign2 is deprecated.
modsView		visualizing field and help select guide star

Binocular Commands

acqBinoMODS and execBinoMODS are wrapper functions which can take up to two arguments. The arguments to acqBinoMODS must be valid acquisition scripts and, to execBinoMODS, valid observation, imaging or calibration scripts. In only one script is given, that script will be executed on both sides, but if two scripts are given, the first will be executed by MODS1 on the SX side of the telescope and the second by MODS2 on the DX side.
The functions open two terminal windows, one for MODS1 and the other for MODS2. You should remember to close these windows once the script has completed.

• acqBinoMODS script1.acq [script2.acq]
• execBinoMODS script1.obs [script2.obs]

Binocular modes supported: identical and fraternal twin

At the moment, MODS1+MODS2 binocular observing is now supported for MOS, long-slit and imaging observations of the same target, using the same PA and guide star. The two options supported at this time are:

1. Identical Twinning (the same script on both sides)
2. Fraternal Twinning (same base configuration but different scripts, e.g. the same base position, position angle and guide star but different MOS masks or different configurations on each side (a 1″ long-slit observation using MODS1 blue-only acquisition and spectroscopy and MODS2 red-only acquisition and spectroscopy.

Binocular offsets

By default all offsets are currently done asynchronously, meaning that each side will offset independently. But the mirror limits of travel prohibit asynchronous offsets greater than the copointing radius, which is 40″. Offsets larger that 40″ can be made ‘synchronously’. (but moving the mount). To indicate that an offset should be synchronous, MODS scripts use the “syncoffset” command. A common use case would be large blind offsets. The OT inserts the “syncoffset” command for blind offset acquisition scripts. If these scripts are run monocularly, then this command must be commented out.

acqBinoMODS and acqMODS

acqMODS and acqBinoMODS execute target acquisition scripts.

>> acqMODS –modsN [options] file.acq

Monocularly, the options are:

-n dry-run the acquisition w/o execution, useful for error handling and reviewing scripts (alias –dryrun)

-a only run the acquisition image sequence (alias –acquire)

-p only load coordinates and preset the telescope (alias –preset)

-i only configure the instrument (alias –inst)

-l only load target coordinates but don’t execute the preset (alias –load)

The options provide ways to execute only portions of the script, but generally acqMODS is run without options.

>>acqBinoMODS file.acq

>>acqBinoMODS mods1.acq mods2.acq

When running binocularly, no options are accepted.

Acquisition progress will be printed to the terminal screen. If there are faults, acqMODS will print the error message and give you the option to abort, retry, or ignore the error.

In a typical long-slit or multi-slit target acquisition, after the thru-slit and field images are taken, the script will pause and ask you to run the modsAlign program to align the targets with the slit mask. On resuming, the usual practice is to take a final, confirmatory thru-slit image to make sure you got the target(s) in the slit(s).


If something goes wrong at the alignment step, the usual response is to re-take the acquisition images. You can do this either by repeating just the acquisition block of the script using the command line option, -a:

acqMODS –modsN -a script.acq

or by repeating the field image manually, by clicking “Out” on the GUI to extract the slit mask and “Go” to take the exposure.

execBinoMODS and execMODS

The following discussion applies to execMODS, and for the most part execBinoMODS. The binocular command has some subtle differences discussed below.

execMODS executes observing (.obs and .img) and calibration (.cal) scripts, configuring the instrument and acquiring science or calibration data as indicated. execMODS is also used to execute instrument setup procedure (.pro) scripts. The command syntax is:

>> execMODS –modsN [options] scriptFile where modsN is either mods1 or mods2 depending on which MODS the scripts is being sent to. execMODS will not run target acquisition (.acq) files.

The command options for execMODS are:

-n dry-run the acquisition w/o execution (alias –dryrun)

-r N run the script starting from command number N (alias –runfrom; use listMODS to get command numbers)

-e run from the Exec: block to the end (alias –exec)

-f name run from the name: block to the end (alias –fromblock)

-b name run only the name: block commands (alias –runblock)

-u run unattended and abort on errors (alias –unattended) The options provide ways to execute only portions of the script, or restart from anywhere in the script after clearing a fault, or doing a quick dry-run to see what the script will do. More often execMODS will be run without options.

One difference with the binocular command execBinoMODS is it can accept 1 or 2 separate input script files:

>> execBinoMODS scriptFile

>> execBinoMODS scriptFile1 scriptFile2 When only one scriptFile is provided, this script is applied identically to both MODS. When 2 inputs are provided, the first scripts applies to MODS1 and the second to MODS2. This is particularly useful when running calibrations, as MODS1 and MODS2 have different lamp intensities. Keep in mind that at this time, at this time only twin and twin fraternal observations are offered. So any 2 scripts fed to execBinoMODS must have the same PA, guide stars. There are no options when running execBinoMODS.

If there are faults, execMODS and execBinoMODS will print the error message in the terminal where the command was run from and give you the option to abort, retry, or ignore the error, same as acqMODS. One difference is that it also prints the command number where the fault occurred, so you could restart the script from that command after clearing the fault (provided the fault wasn’t with the script proper).

The -e option can be a very useful option in recovery or when rerunning observations.

>> execBinoMODS -e scriptFile

>> execBinoMODS -e scriptFile1 scriptFile2

This options will rerun the scriptFile(s) provided but not resent the instConfig. If the instConfig is resent this will relock IMCS and cause a possible spectral shift.

If the –u(–unattended) option is given, execMODS will abort on all faults rather than prompting for abort/retry/ignore. This option must be used if running a calibration (.cal) script unattended by an observer (e.g., starting biases or calibration lamp spectra then going to bed). This ensures that if there are problems, the instrument will abort if nobody is around to do that. Unattended operation should be done with forethought as to what will happen if things go wrong – in particular, never run a new, untested, or unproven script in unattended mode.

modsAlign

modsAlign was rewritten in December 2016 (v2.1.3) to allow it to be run simultaneously for both MODS1 and MODS2 and almost automatically, thereby making binocular MODS1+2 observing more efficient. modsAlign is run from the command line, with a set of arguments and options which depend on the type of alignment: long-slit, MOS or a spectrophotometric standard through the wide 5″ slit. From the image header, it determines for which MODS it will be run and will launch a dedicated ds9 window for each one. The header will also be used to distinguish slit and field images, so the order of the arguments does not matter.

modsAlign is run after the slit/mask and field acquisition images have been acquired and while the acqMODS (or acqBinoMODS) script is in a paused state. modsAlign will by default look in /newdata for the images, but, in the case of MOS alignments, the mms file must be in the directory from which modsAlign is run.

The syntax for multi-object (MOS), long-slit and spectrophotometric standard star alignments are (where the order of the arguments does not matter):

• modsAlign <myfield.mms> <maskimage.fits> <fieldimage.fits> (MOS)
  
• modsAlign -y dy <slitimage.fits> <fieldimage.fits> (long-slit)
  
• modsAlign -r <fieldimage.fits> (spectrophotometric standard)
  

Highlights of the new modsAlign are:

• for MOS alignments, the routine will automatically find and centroid on the boxes, then find and centroid on the alignment stars, so there is no longer any need to click on boxes or stars unless you want to override the selections. By default, the observer is prompted to verify the selections, but a --turbo option will bypass this.
• for long-slit alignments, there is a -y dy option which determines automatically the x-center of the slit at a distance dy arcseconds from the mask center. The observer will still need to select the target with “a” (to centroid) or “x” (to use the cursor position).
• for spectroscopic standard star alignments, a final adjustment can be done on the thru-slit confirmatory image, on which both the slit center and the star centroid are accurately determined.
• -B By default, a “quick-bias” subtraction is done on both the slit and field images. -B allows you to turn this off. “Quick-bias” subtraction is helpful for centroiding on faint targets because it effectively removes the even-odd column striping, but is not recommended for fields with diffuse emission extending over a significant fraction of a quadrant.

There are 3 alignment modes: multi-object, long-slit science, and wide-slit spectrophotometric standards:

1. For multi-object slitmask acquisition:
   1. modsAlign <myfield.mms> <maskimage.fits> <fieldimage.fits>
   2. The slitmask image will be displayed first, with best-fit box positions overlaid, where the box centroids are determined by a two-step process: first using the mms file to locate the boxes, and second, using a Sobel mean-square fitting algorithm to measure the box edges. The observer will be given the option to either accept these centroids “a”, reject them and select the boxes manually “m” or abort “!”. If the observer chooses the option “m”, then he or she should position the cursor on each box and type “a”. This will determine the center of the nearest box, so long as the cursor is not further than the box width from it; “x” on the other hand will put a box at the cursor position. Once all boxes are marked, type “q” to save the box centroids and continue.
   3. The field image is then displayed and a regions file depicting the box positions will be overlaid. The centroids of the alignment stars will be automatically determined and shown in green. Type “a” to accept these centroids, or “e” to delete or add stars followed by “q”.
   4. The offset in x, y and rotation will be printed and you will be queried whether to send or not. If reasonable, send with “Y” or “y”. Note that no answer (hitting “enter”) will be interpreted as a negative reply and will not send the offsets.
   5. Once the offset is made, continue the script to obtain a confirmatory thru-slit image
2. For long-slit science acquisition:
   1. modsAlign -y dy <slitimage.fits> <fieldimage.fits> will display the slit image, determine the X-center of the slit at a position dy arcsec above the slit center, then display the field image and prompt the observer to position the cursor on the target and type “a” to centroid or “x” to use the cursor position. dy = 11″ for MODS1 and 9″ for MODS2 clear the bad columns in MODS1R and correspond to the reference positions used for spectrophotometric standard stars.
      
   2. Alternatively, the observer can use the -l option, as before, to select the position along the slit where they want to center the target. (modsAlign -l <slitimage.fits> <fieldimage.fits>). In this case, the slit image will be displayed and the observer should position the cursor at the position along the slit where they want the target to be, type “x” and then “q”. The X-center will be fit and the slit position will be overlaid on the field image. On the field image, the observer should position the cursor on the target and type “a” to centroid or “x” to take the cursor position. (For point sources, we used to recommend Y positions, Y=620 for the 1Kx1K ROI or Y=1652 for the 3Kx3K, to keep the spectrum, which is tilted, in the top two quadrants and above a region of bad pixels in the top left quadrant of the red channel of MODS. These Y values are further than 7″ from the slit center, but also are quite high in the central slit.)
   3. Using either the -y or -l option, after selecting the target, you should see both slit and target centers marked on the field image and the computed offsets shown in the launching terminal window. If these and the offsets look reasonable, send them by typing “y” or “Y”.
3. For spectrophotometric standard star acquisition:
   1. modsAlign -r <fieldimage.fits> will display the field image with an outline of the wide slit and the reference position of the slit center, marked by a cross. It uses the following reference positions for the 5″ slit centers: (501.2, 620) for MODS1, and (508, 590) for MODS2.
   2. Position the cursor on the star, and type “a” to centroid or “x” to take the cursor position. The offset will be computed and displayed in the launching terminal window, along with a prompt to type “y” or “Y” to send it.
   3. modsAlign -r can be run on the thru-slit confirmatory image where, this time, it will measure the slit X-center as well as the star centroid from the image and determine a small offset that should improve upon the centering achieved using only the reference position.

modsAlign also writes out a file mods_lastOffset which contains the last offset performed when running modsAlign. The troubleshooting section on Recovering from a Lost Preset outlines how this file is useful in getting back on sky in such an event .

Offsets MODS

Offsets can be sent through the scripts, the Command prompt in the MODS Dashboard, or can be sent via the Offset Pointing Panel on the MODS Dashboard.

The command the the user would enter in the Command line of the MODS Dash board is the same as that used in the MODS observing scripts:

OFFSETXY <dX|dY> <ABS|REL>

This offsets the telescope in the Slit XY coordinates, or

OFFSET <dRA|dDec> <ABS|REL>

Offsets the telescope in celestial (RA,Dec) coordinates, where:

dX – X-axis offset in arcseconds, ± X_CCD motion (perpendicular to the slit)
dY – Y-axis offset in arcseconds, ±Y_CCD motion (parallel to the slit)
dRA – RA offset in arcseconds, + = E, – = W (includes the cosδ correction)
dDec – Dec offset in arcseconds, +=N, – = S
ABS – make an absolute offset relative to the pointing origin
REL – make an offset relative to the current position