Why and What: In long-slit mode, the OSMOS instrument is centered using images taken from behind the slit -- there are no slit-viewing optics, as there are on CCDS, MarkIII, and Modspec. To center the object, you take a direct exposure (with the disperser and the slit out of the beam), locate the target, and then move the telescope so that the object's image coincides with the slit in the telescope's focal plane. This is an exacting, delicate, error-prone, and potentially time-consuming operation. This document describes a script, osctrtask, which automates much of the process and makes it much more straightforward.

[[Note: Once you've successfully taken a spectrum, there is a program called osqlsp that will give you a properly bias-subtracted, optimally extracted, sky-subtracted, and (optionally) wavelength-calibrated version for quick-look. This is not documented separately, but it is functionally almost identical to the qccds program for CCDS spectra. You should be able to use the qccds documentation to run this; just substitute 'osqlsp' for 'qccds' in the instructions.]]

The basic procedure is as follows:

1. Move to the field. Find a guide star (JSkyCalc24mGS makes this part very efficient).
2. Engage the autoguider.
3. Take a direct image of the field (i.e., with slit and disperser out.).
4. Insert the slit (but not the disperser) and take another image -- this must have the same readout format as the direct image.
5. Run osctrtask (much more detail below); this computes DX and DY offsets for the guide stage.
6. Now, without moving the guide box:
   1. Disengage the autoguider.
   2. Enter the DX and DY offsets computed by osctrtask into the DX and DY (not X and Y) fields in the xmis window on hiltner
   3. Move the probe by hitting carriage return in the DX and DY boxes (do this only once per field or you'll move more than once).
   4. Using the telescope control paddle, move the telescope to re-center the guide star approximately.
   5. Re-start the autoguider.
The target should now be in the slit.
7. Optionally, take an exposure through the slit (without the disperser) to verify that the target is in fact in the slit.
8. Put in the disperser and start your science exposure.

Once you get going, you can speed this up considerably by inserting fine-scale slit offsets before engaging the autoguider in step (2) above; then, in step (6), the final centering adjustments will be so small that the autoguider should be able to follow them, so you don't have to disengage the autoguider.

The osctrtask script itself does the following:

• Bias-subtracts the acquisition image and (optionally) the slit image, and loads them into images named acqimage and slitimage. These names are fixed, and the contents of acqimage (and slitimage if it is selected) are overwritten every time the task is run.
• Displays the image(s) on the ds9 image display.
• Obtains the pixel coordinates of the target on acqimage. There are several options for this, described below.
• Obtains the pixel coordinates of the slit, either interactively from ds9, or from the task parameters.
• From the pixel coordinates, computes and reports the guide-stage offsets needed to center the target.

Note that the script leaves the original data untouched -- you needn't be afraid of it screwing anything up.

Quick Instructions: You should be logged on as obs24m on one of the new (as of 2012) servers, e.g. mdm24ws1.

• Make a scratch directory for your centering work, by typing e.g. mkdir mycenter, and descend into that directory ( cd mycenter).
• Grab your own copy of the osctrtask script, by typing

  cp /usr/local/pkg/thorsoft/scripts/osctrtask.py .
  

  (Don't overlook the final dot).
• Be sure that there isn't another ds9 task running on agung somewhere. (osctrtask makes heavy use of ds9, and if there's another running it could get very confused). The command ps -a shows the processes running; if the output from ps is too long, try ps -a | grep ds9.
  Note that if you have a ds9 that you started from the taskbar or menu, this program is guaranteed to fail.
• Type pyraf to start pyraf. (This is an iraf wrapper written at STScI, which has many advantages over the classic IRAF cl.)
• In pyraf, import the osctrtask task by typing

  
  pyexecute('osctrtask.py') 
  
  

  
  This takes the script and magically converts it into an iraf task! [If this or the next step fails, read this note.]
• Now, type epar osctrtask to set it up. This pops a simple GUI form that is easy to use, unlike the usual IRAF epar.
• Edit the parameters, and select the Execute button to run the task. What happens next depends on the options you select, so ... on to the discussion below.

Here's a screenshot of the 'epar' for osctrtask.

The first four parameters tell osctrtask where to get the data. Note that the datapath requires a final slash, and the prefix requires a final dot (which is nearly invisible here). acqnum and slitnum are the exposure numbers for the two images; you need to give something for slitnum even if you're not using it. These are internally converted to the standard four-digit format. In the case shown here, the program would go looking for the original acquisition image as

    /data/hiltner/Sep15/915.0190

For the bare-bones use of the program,

• turn on twoframes
• turn off getwcs
• be sure slitns is corrrect (described below),
• follow the instructions under Marking the images interactively below.

You'll find the bare-bones use to be a bit labor-intensive, and there's considerable ease and efficiency to be gained by using the other features of the program, as follows.

slitns -- In the comissioning runs (spring 2010), OSMOS was mounted so that the slits were east-west. To minimize atmospheric dispersion near the meridian, one wants the slits north-south by default, and it is hoped that this will be the default orientation for long-slit work. Select the appropriate radiobutton.

twoframes, xslitpar and yslitpar -- If you are using a fresh exposure to locate the slit, set twoframes to Yes. If you're using a nominal slit position from a previous exposure, de-select twoframes and type the X and Y pixel coordinates of your slit location into the xslitpar and yslitpar boxes. If you do this, use caution -- the X coordinate needs to be accurate to better than one pixel!

The next nine (!) parameters control automatic target finding. This doesn't always work, but when it does it is a tremendous convenience.

getwcs -- If this is checked, the program will find star images in the acqimage and attempt to match them to the UCAC3 astrometric catalog. If this appears to work, the world coordinate system parameters will be set in acqimage's header, in which case you know the precise RA and dec for every point in the image.

marktarg -- If this is selected, then if the wcs is successfully found, and you supply target coordinates, your target will be marked with a circle on the ds9 display.

autotarg -- If this is selected and the wcs is successfully found, and you supply target coordinates, the exact centroid of the target will be found automatically (by automatically running the IRAF imexam command 'a'). Otherwise, you'll have to type 'a' yourself (see below), or enter the coordinates manually if autocentering will converge on the wrong object.

There are two ways to feed in the nominal RA and dec of the target, so the program can mark and/or centroid it on the image:

1. If fromlist is 'Yes', then the list specified by targlist is searched for an object with the exact name given by targname (it has to be a perfect, case-senstive match). The targlist is in the same format used by the TCS, namely

   name_no_blanks  rah ram ras   decd decm decs  equinox
   for example:
   Feige98          14 38 15.76  +27 29 32.9  2000.0
   

2. If fromlist is 'No', then the targetra and targetdec are read; they must be J2000. The format for targetra and targetdec is fairly forgiving -- you can use spaces instead of colons.

Finally, there's the rawtarg parameter, which turns off the centroiding of the target. This is useful if, for example, you're centering on a faint object with a nearby bright companion. In this case, you need to type in the X and Y pixel coordinates you want, when the program prompts you.

The pushprobe parameter (not yet implemented) would automatically push the guide probe to the new position. This may remain implemented, since it's possible to get badly lost with large moves.

When you run osctrtask, the acqimage (and optionally the slitimage) are automatically displayed in ds9; acqimage is in Frame 1, and slitimage (if any) is in Frame 2. You may need to use ds9's Frame commands 'next' and/or 'previous' to bring up the appropriate image.

Unless you're autocentroiding the target and using a previous slit position, you will need to mark one or two positions on these images using a cursor. To get these positions, the program runs the IRAF imexam task and parses the output. Unfortunately, the programming trick used makes it impossible to see the results as you go along -- when you mark the target, or the slit, nothing happens. This is awkward and disconcerting, but it's normal (and apparently inevitable).

Note that when imexam is alive, you get a "blinking life preserver" cursor in ds9 -- if you have an arrow cursor instead, then imexam is not in control yet. A common reason for this is that there's an unanswered prompt in the window where you're running pyraf - possibly something like "Display frame [1]:" Just hit enter to keep it happy, and you should get the blinking life preserver in ds9, and be able to proceed.

Depending on what the program needs, it will tell yoiu to mark the slit with an 'x', the object with an 'a', or both.

• The slit location, if needed, needs to be marked very accurately (sub pixel) in the cross-slit cirection. To attain this accuracy you may need to use the Zoom commands in ds9 (and the center mouse button to recenter the image) to blow up the slit to adequate scale. You may want to fiddle with the image stretch -- that's in the scale top-bar menu. The Scale parameters ... choice at the bottom pops a nice window that gives great control over the stretch -- it's good not to have the slit pure white. Once you have enough scale and a good stretch, position the life-preserver cursor dead in the middle of the slit and type 'x'. As noted above, you won't get immediate feedback, but it should be doing the right thing.
• The target location, if needed, is marked with an 'a', which finds the image centroid, so you don't need to be quite as fussy. To do this, change frames to show the acquisition image, find your target (which will have been circled if the wcs finding was selected and working), zoom in on the target, put the cursor on the star, and type 'a'. Again, you won't see anything, but your answer should have been recorded.
• Once you've marked everything you need to, type 'q' to quit the imexam cursor. If the program has the information it needs, it should finish. If not, it should ask you again.
• Note that the distinction between 'x' and 'a' is key -- they produce different-format output, and this is used to distinguish the slit and the star. Also, 'a' autocenters the star and reports those coordinates, while 'x' reports the exact pixel coordinates you marked.
• If you need to select a member of a close double, or it's not appropriate to centroid the target for some reason, set the rawtarg flag to Yes. Then, you'll be prompted to type in the X and Y pixel coordinates you want.
• Among the last things the program reports before it quits are the X and Y locations of the slit. If you have determined these interactively, you may be able to get away with copying them into xlitpar and yslitpar and dispense with the slit exposure on the next setup. Doing so assumes that the projection of the slit on the detector does not move; the manual says this is the case, but I for one have not adopted this practice.

All these procedures go better if you have really accurate target coordinates, good to the sub-arcsecond level. The JSkyCalc24mGS program that moves the guide probe uses the UCAC3 as the base catalog, and the guide star coordinates are updated for proper motion, so their coordinates are typically good to less than 0.1 arcsec.

Experience has shown that the center of the 'center' slit is not perfectly aligned with the guide probe coordinate system. In our 2010 September run, we adopted the practice of applying an extra offset of dx = -180, dy = -100 to the JSkyCalc24mGS coordinates -- basically, we just moved the guide probe using JSkyCalc24mGS, then manually made the small extra move using the dx and dy boxes in the xmis window, and then centered the guide star and started guiding. We always used the same nominal guide star pixel coordinates in the Maxim DL guide software, and with accurate target coordinates the stars were already in the slit (though not necessarily dead-center).

Hopefully users will find this program easy to use, but you need to be clear on the concept -- to center the object, you do not move the guide box, you move the guide probe using xmis. The whole scheme depends on the guide box remaining perfectly stationary in the guide camera.

The Maxim DL guide system for the FLI cameras has a different interface than the old Seitzer guider (which is fading from memory at this point), but it's easy to keep a fixed guide position. The nominal guide star position is re-set when (a) you have the Guide tab open, (b) you select the "Expose" radiobutton and (c) you hit "Start"; this takes an exposure and finds a guide star for you. In order to maintain a consistent guide star position, you want to do this only once, when you set up the guider at the start of your run. Once the guider is calibrated, just leave the radiobutton on "Track"; this will keep the nominal pixel coordinates the same. [Confusingly, there is a tab in the camera control that is also labeled Expose; that's the option for taking a picture without guiding; you'll use that to find the guide star and get it close to its nominal position in the frame.] I had excellent results using the Maxim system guiding direct images -- nice round images every time -- so it should work very well for OSMOS spectra, as long as you remember not to re-set the guide star location.

The OSMOS manual claims that once the slits have been installed in the filter wheel, their projected locations on the detector are very steady. For this reason, I've offered the option of re-using the slit position, by turning off twoframes and supplying the appropriate slitxpar and slitypar. It might be best to treat this claim cautiously until more experience is gained with the instrument, especially if your program calls for observations at funny telescope positions or rotator angles.

In order for the getwcs option to work, you need accurate telescope coordinates -- within 20 or 30 arcsec, ideally. These should be the coordinates of the field center, not an offset slit. The JSkyCalc24mGS program provides field center coordinates for the offset slits, even if you have the instrument rotated. If you need to rezero the telescope coordinates, be sure to insert the appropriate field center coordinates in the RA and dec boxes in xtcs, and then carefully check that the RA and dec have reset to the correct values before moving away. If you blunder when you re-zero coordinates, and move away before you realize your mistake, you have a real mess on your hands, so be careful. (The 2.4m user's guide, on the mountaintop web server, has a section on 'how to restore lost pointing').

Note that there's no need to account for the rotator angle in this scheme -- once the instrument is mounted, the guide stage rotates with the instrument, so they're in the same frame. However, mounting the instrument at a different angle does affect the relation between the guide stange and the instrument; that's the reason we need the slitns parameter.

Because some of the readout options are long and skinny (1000 x 4000), the star-matching algorithms have been modified to read a strip of the catalog that should coincide with the field of view, more or less. This involved a rewrite of the star-matching software, which had read catalog stars from a square patch. The star-matching software needs to know both the mounting choice and the instrument rotator, but it gets the instrument rotator from the image header.

The bias-subtraction scheme splits the image into four pieces, bias-subtracts each piece, and then pastes the pieces back together. In the process, any header information that is not explictly copied into the new image is lost. I have copied some of the most informative header parameters into the new images -- title, ra, dec, filter and so on -- but beware that much of the header information will be missing from acqimage and slitimage.

----------------------------------------------------------------------

Footote: What is the world coordinate system? The WCS refers to the "real" coordinates in an image, e.g, the RA and dec rather than the XY pixel coordinates. An image with WCS has keywords written into the header that express the transformation from XY to "real" coordinates (in this case RA and dec). DS9 can interpret WCS, so when the WCS in an image is set, and it's displayed in DS9 the RA and dec that show in DS9 are the real RA and dec, not some lame guess.

Important note: DS9 is only 'wcs-aware' if you use its own 'File' menu to display images. If instead you use 'display' from within IRAF, nearly all the header information is lost. In addition, all the dynamic range is lost because IRAF was written in the dark ages of 256-level displays; if you use display from within IRAF, it forcibly maps the original image into a fake 8-bit image, and then displays the fake image. There is no good reason to display from within IRAF -- imexam and the like work fine if you don't -- and it basically cripples DS9. Make it a practice NEVER to display an image from within IRAF. Instead, use the File pull-down menu in ds9, and choose Open and use the dialog box. You'll never go back.

[Back to wcs loading discussion ... ]

------------------------------

		/lhome/obs24m/iraf/uparm/osctrtask.par

		cp /usr/local/pkg/thorsoft/scripts/osctrtask.par .

		pyexecute('osctrtask.py') 

[Back to the instructions.]