Table of Contents
Purpose of EFS
The Echelle Format Simulator (EFS) is used primary in two ways. The first is to run the NIRSPEC Instrument. It does this by allowing the user to set up a number of options and settings, such and slit width, filter, and exposure time, and sending a script of commands to the NIRSPEC server, which carries out these commands. The second use is to set up one of these scripts but instead of running, save it for use at another time. By using the EFS, an observer can set up a script from the comfort of his or her office, home, or any other location, save it, and execute it at the instrument, saving valuable observing time.
Interaction with the DRP
The NIRSPEC software package is an interweaving collaborative effort in which the multiple programs all interact with each other, the server, and the instrument. In this way, NIRSPEC becomes increasingly more powerful, while at the same time, easier to use. This is clearly evident in the interaction between the EFS and the Data Reduction Pipeline, or the DRP. When the EFS writes a script, the DRP, which is constantly monitoring the server, takes note and begins to process the script itself. It therefore knows what the instrument is going to do, and begins to prepare for the incoming data. The data, upon arrival, is then processed, using the various information stored in the script by the EFS. After processing, the reduced data is either saved to disk, or sent to another component of the NIRSPEC software package, Quicklook. Therefore, when used in conjunction, you can go from a simple user interface like the EFS to a reduced image with minimal effort.
Scripts and Configurations
Information about the instrument and telescope setup is stored in a script. A script is a text file in which a set of commands are written, and when desired, is executed as a C-Shell program. They typically have the extension of *.csh. A configuration is the set up of every parameter to be set by the EFS. This includes filters, slits, integration times, object name, etc. When a you hit the Save Configuration As… button in the main menu, the configuration is saved to a file in the form of a script. When the GO button is hit, first the configuration is saved to a script, then the script is exectued. If a previously written script is opened, EFS looks through the script to determine the configuration, then sets up the fields and dropdown menus and such in the EFS to reflect this configuration.
Starting EFS
To start EFS, you can either launch it from a script or from the IDL prompt. If you launch it from a script, from the shell prompt, type run_efs to run the normal EFS, connected to a server. To run EFS with a simulated server, type run_efs -s.
To run EFS from the IDL prompt, first you have to set the device to handle 24 bit colors. Do this by typing device, true_color=24 at the IDL prompt. If running it connected to the server, first you have to compile the KIDL routines. Do this by typing .r kidl at the prompt. Then type in nirspec_efs, sim="nirspec" to start the EFS. To run EFS with a simulated server, it is not necessary to compile the KIDL routines. Start the EFS by typing nirspec_efs, sim="nirspecsim".
The Draw Window
This window displays the simulated echellogram for the given setup. The box is called a Set-Up Box. It defines approximately the limits of the detector. By using the box, you can tell which parts of the echellogram will fall on the detector, and which parts will be chopped off. By clicking and dragging the mouse in the window, you can move the box around, which automatically changes the Echelle and Cross Disperser angles correspondingly. In this way, mechanisms in NIRSPEC will be moved so that the matching parts of the echellogram fall on the detector.
These boxes display the X (horizontal) and Y (vertical) pixel of the detector the cursor is currently on. Pixels begin with (1,1) in the lower left corner of the Set-Up Box.
This box gives the wavelength in the echellogram that the cursor is currently on.
This box gives the order of the echellogram the cursor is currently on.
Controlling EFS
Menu Options
This section describes the routines and functions that can be called by clicking on an option the main menu bar, above the draw window. The menu bar is divided into four main sections, File, Telescope, Overlays, and Help.
This section of the menu displays the options involved in file manipulation. Such features include opening and saving scripts, and exiting the program.
This option opens a script to be edited or executed by the EFS. It uses a dialog box that allows the changing of directories, filters, and filenames directly by typing it into the box, or by clicking on the appropriate filename or directory in the scroll window. This same dialog is used for opening files throughout EFS, including saving files as well.
Use this option to save the current settings of the EFS to a file. Every settings, such as filter, echelle and cross dispersor angles, and integration time are saved into a script file, that can be opened at a later time for editing or execution.
Clicking this option will exit the EFS. Any changes will be lost if they are not saved.
This section of the menu gives options that involve operations on the telescope.
Click this option to set the amount the telescope moves in degrees in both the north and east directions when performing a nod. To move the telescope south, enter a negative value for North, and to move the telescope west, enter a negative value for East. Hit OK to close the dialog, saving the changes made. Hit Apply to put the changes into effect, but leave the dialog open. Hit Cancel to close the dialog, changing the values back to their values the last time OK or Apply was hit.
This section of the menu gives access to the various overlays that can be overplotted on the echellogram in the EFS.
This option removes any lines plotted on the echellogram.
This option brings up a dialog that allows you to create your own line lists, or to load one previously written, edit it, or simply plot it on the echellogram.
Hit this button to open a previously written line list.
Enter the wavelength for the new line here.
Hit this button to add the line to the list.
Enter a comment for the new line here.
To plot the lines redshifted by a specific Z, enter the Z here.
Hit this button to remove the currently selected line from the list.
Hit this button to completely clear the list.
Hit this button to bring up a dialog for selecting the color which the user lines are to be plotted on the echellogram.
Hit this button to switch between the various color systems. RGB is the default.
Slide the sliders to the various positions until the desired color is obtained.
Hit OK to dismiss the dialog.
Enter the filename you wish to save the list as.
Hit this button to save the list. It brings up a dialog to browse for a file to save to .
Hit this button to plot the lines in the list and close the dialog.
Hit this button to plot the lines in the list, but leave the dialog open.
Hit this button to close the dialog, and not plot any user lines.
Hitting this option plots the OH lines on the echellogram. Hitting it again removes them.
This submenu gives options for turning on and off the plotting of lines from various arclamps. All lines can be removed by hitting the Clear Overlays option.
Hitting this option plots the Neon lines on the echellogram. Hitting it again removes them.
Hitting this option plots the Argon lines on the echellogram. Hitting it again removes them.
Hitting this option plots the Krypton lines on the echellogram. Hitting it again removes them.
Hitting this option plots the Xenon lines on the echellogram. Hitting it again removes them.
This menu section gives online help in using EFS.
This help dialog shows the various Hotkeys used by the EFS. Hit OK to dismiss the dialog.
This will bring up the online version of this user manual in Netscape.
Buttons
This menu selects the type of calibration mode to use. First option, Setup Only, only moves the mechanisms in the instrument, but does not take an exposure. The second option, Object Only, allows the exposure of an object by the camera. Multiple setups are supported by use of the setup boxes. The Object+Lamps option is the same as the Object Only mode, except that at the end of the script, the use of arc lamps for calibration is included. The fourth option, Object+Star is and option that will take two exposures. The first is of the object. Then, you are prompted to move the telescope to the calibration star, and the star exposure begins. The Full Sequence is a Object+Star+Lamps sequence.
This menu selects the nod pattern to be used. A Stare is no nodding, a Nod two through four splits the slit makes two through fours nods in the slit. A Nod Chop makes a nod in the amount specified by the Set Nod Parameters option in the Telescope section of the main menu.
This menu selects the number of nods to perform.
This menu selects the spectral mode between High Resolution, Low Resolution, and Imaging. Consult the NIRSPEC manual for more about the spectral modes.
Change this dropdown menu to select the size of the slit to be used for the current setup.
Select the filter to be used for the current setup from this list.
Select the type of blocking to be used from None, Thin, or Thick.
Hit this button to see a transmission plot of the currently selected filter.
Switch this toggle to turn on and off the overplotting of a bad pixel mask over the detector box. This is useful in determining which part of the echellogram may be affected by bad pixels.
This box displays the current echelle angle. It can be changed either by moving the box, or by entering a value into this field.
This box displays the current cross dispersor angle. It can be changed either by moving the box, or by entering a value into this field.
When in Object or Object+Lamps calibration mode, you can create up to 1000 setups for a given script. This includes different filters, slits, echelle and cross dispersor angles, etc. for each setup.
Hit this button to create a new setup box.
Hit this button to go to the previous setup box.
Hit this button to go to the next setup box.
Hit this button to delete the currently selected setup box.
Hit this button to display information about the current setup box, indicated in the field to the right of the button.
Enter the name of the object in this box. It is disabled for Setup Only mode.
Enter the integration time of the object exposure in this box. It is disabled for Setup Only mode.
Enter the number of coadds for the object exposure in this box. It is disabled for Setup Only mode.
Enter the name of the calibration star in this box. It is enabled for Object+Star and Full Sequence modes.
Enter the integration time of the calibration star exposure in this box. It is enabled for Object+Star and Full Sequence modes.
Enter the number of coadds for the calibration star exposure in this box. It is enabled for Object+Star and Full Sequence modes.
Hit this button to send the script to the NIRSPEC server to be executed.
Hit this button to cancel the execution of a script by the NIRSPEC server.
Setting Up a Configuration
The first thing to decide is what you want to take an exposure of and how you want to calibrate it. There are basically two ways to calibrate: using a star, or using arc lamps. To use a star, either pick the Object+Star mode or the Full Sequence mode. To use arc lamps, pick the Object+Lamps mode or the Full Sequence mode. To not use any calibration, pick the Object Only mode, and to only move the mechanisms and not take an exposure, pick the Setup Only mode.
Next, you’ll want to determine the nod pattern to use. Nod stare does not move the telescope before taking an exposure; it simply takes one exposure with the slit in its current position. The numbered nod positions divide the slit into the same number of pieces as the number following Nod and takes exposures in the center of these pieces. Nod 2 moves the telescope from center up to one fourth of the slit length from to the top of the slit, takes an exposure, moves down to one fourth of the slit length from the bottom of the slit and takes another exposure. Nod 3 performs a similar action, except the three positions where exposures are taken are one sixth of the slit length from the top and bottom, and in the center of the slit. Nod 4 is also similar, where the four exposures are taken at one eighth of the slit length from the top and bottom and one eighth the slit length above and below the center. Nod Chop uses the numbers set by the Set Nod Parameters dialog in the Telescope section of the main menu to determine how much to nod. This is slightly different than normal nodding, because often times, the object will be completed moved out of the slit.
Now, determine the number of nod repetitions to make. You can repeat the nod pattern from one to six times.
Next, determine the Spectral Mode you wish to use. In the High Resolution mode, both the echellogram and the cross dispersor are used to produce a complete echellogram. In the Low Resolution mode, the echelle grating is replace with an LR Flat mirror that passes the light from the cross dispersor to the detector. In imaging mode, the light is not dispersed at all, an is instead passed to the detector as it had when it passed through the slit.
After that, determine the slit and filter to use for the exposure. The filter determines which wavelengths are detected, and the slit determines how much light is passed in and how wide the spectral features are. An important aspect to note than may not be obvious is that only certain slits are intended to be used for each Spectral Mode. In the High Resolution mode, the slits with slitlengths of 12" and 24" are intended to be used. In the Low Resolution mode, the 42" slits are intended to be used.
Now, position the setup box to set the echelle and cross dispersor angles. These angles determine which parts of the echellogram fall on the detector. Move the box by dragging it or by using the arrow keys so that the desired portion of the echellogram falls inside the box.
Lastly, enter information about the Object and Star, if necessary. Often, certain parts of this area may be disabled. This is because some of these fields only apply to certain calibration modes. For instance, in Object Only mode, no information about the calibration star is needed since no calibration star is used. Furthermore, for Setup Only mode, this entire area is disabled, since no exposure at all is taken. If necessary, enter the object and star names, and the integration time and coadds for each. If the mode supports multiple setups, enter the box number that corresponds to the setup you which use for the current exposure.
When all of the above is done, your configuration is done. Now you are ready to turn your configuration into a script.
From a Configuration to a Script
Once you have your configuration set up the way you want it, you can either save it to a file for execution later, or execute it immediately. To save it, hit the Save Configuration As… option from the File section of the main menu. This brings up the Pickfile dialog. Pick a file to write to or enter a filename in the filename box. Be sure to include the extension *.csh so that loading the file will be easier.
To execute the script, hit the GO button. This saves the script with a default filename consisting of the date and a file number with the *.csh extension, written to the default script directory. These files are the scripts the DRP looks for when a script is running. Next, after the script has been written, the EFS spawns a C-Shell for the execution of the script. Then, it is up to the server to carry out the commands.
While the script is running, the EFS is still fully functional, allowing the you to setup another configuration while waiting for the running script to finish. To stop the execution of the currently running script, hit the red ABORT button.
More About Using Setup Boxes
Setup boxes, when properly utilized, can save valuable time, as well as reduce the work by automating the data collection process. By using setup boxes, you can condense multiple scripts into one, and by simply hitting the Go button, you can sit back and watch the EFS take as many exposures as desired.
It may take a bit of experimenting to become comfortable with the manipulation of setup boxes. This section is intended to help you reach that comfort level by introducing a few techniques in setting up your configuration.
Moving Boxes
To move a box, click somewhere in the box, and move the mouse while holding the mouse button down (i.e. dragging the mouse) until the box is in the desired location. If you click somewhere in the echellogram that is not occupied by a box, the current box snaps to that location, centered about the point clicked. The current box can be moved in small increments by using the arrow keys.
Creating New Boxes
Setup boxes are only allowed in Object and Object+Lamps calibration modes. A new box can not be created unless you are in one of these modes. To create a new box, hit the New button. The new box is drawn in the center of the echellogram and colored yellow, while the old box’s color changes to green. The box colored yellow is the active or "current" box, while green boxes indicate the inactive boxes. The new box always becomes the current box. You can enter create a new box anywhere in the chain of boxes. Boxes that fall after the new box are shifted in number by one.
Changing the Current Box
There are two ways of switching between boxes: 1) by hitting the Previous or Next buttons until the desired box is current; 2) by simply clicking within the box you want to make active. If you click in an area occupied by more than one box, the current box is decided by the following: 1) if one of the boxes is already the current box, it remains the current box; 2) otherwise, of the remaining boxes containing the point that was clicked, the box with the highest number becomes the current box.
You may have noticed that when in a calibration mode that does not allow multiple setup boxes, the current box ( Box 1, the only box allowed ) follows you when you change filters, Spectral Modes, etc. This also happens for the current box in a multiple box setup. For instance, now you have two boxes, Box 2 is active, and Box 1 is inactive. If you change another filter, Box 2 follows you and is now centered in the echellogram of the new filter. Box 1 is still in the same position is was in the previous filter. To see this, hit the previous button.
Deleting Boxes
To delete the current box, hit the delete button. If the current box is not the last box, all the boxes with numbers higher than the deleted box get shifted down, so that there is continuity. For example, if you have 6 boxes and you delete box 3, boxes 4 through 6 become boxes 3 throught 5 respectively. Their setups are the same; only their numbers change. If the box deleted is the last box, the current box becomes the one previous to the deleted box. Otherwise, the current box number remains the same, but reflects the change in numbering, and therefore represents the box that was one after the deleted box. Using the above example, the current box is still number 3, but has the configuration of what Box 4 had before the deletion.
Using Multiple Boxes
One use of multiple boxes is to take a sampling of images in the various filters. The most importing thing to remember is that once you have a box where you want it, before switching to another filter for your new box, create the new box first. Remember, if you change filter, the current box comes with you. To avoid this, create a box, making it the current box, then change filters. This also applies to switching between Spectral Modes.
Another common utilization of setup boxes is to create a "postage stamp" of the echellogram. This is the use of multiple boxes to cover the entire filter bandpass. For example, lets say you wanted the entire echellogram for the Nirspec-6 filter. When you bring it up in the EFS, you notice that one box is two small to cover the entire echellogram. Therefore, use multiple boxes. Move the box to the so that it covers the lower left corner of the echellogram (e.g. echelle: 62.5, Cross Disp.: 33.34). Then hit New. Move that box to the lower right of the echellogram (e.g. e.: 63.84, c.d.: 33.42). Hit new two more times and move the two new boxes to cover the top half of the echellogram (e.g. e.: 62.25, c.d.: 35.19, e.: 63.95, c.d.: 35.16). If necessary, adjust the four boxes so that the entire echellogram is covered. Now you are ready to expose!
Using User Line Lists
The use of Arc lines are a valuable resource to the astronomer in terms of calibration and setup. However, the User Lines feature of the EFS is another powerful tool, allowing you to customize existing lists, and to create your own lists. The EFS can then plot the lines specified in your list over the simulated echellogram, giving you the ability to adjust your setup so that the desired line(s) fall on the detector.
To enable the User Lines, hit User Lines under the Overlays section of the main menu. This brings up a dialog that lists the user line list. To open an existing line list, hit the Browse button. Then select the desired file, and hit the okay button. The list is displayed in the box. To start a list from scratch, simply start adding lines. If a list is already displayed, and you want to start a new list, hit the Clear List button. This will remove all lines from the list box.
To add a line to the list, simply type the wavelength (in microns) in the Add Line to List: box. If you want to add a comment to the line, perhaps describing which line it represents, enter the text in the New Line Comment: box. When the new line is ready to be added, hit the Add button. The line is added and the list is automatically sorted from the shortest wavelength to the longest. If you want to remove a line from the list, click on the line in the list and hit the Remove Selection button.
Once you have the list the way you want it, you may save it if you like. Do this by typing the filename in the Save List As: box and/or hitting the Save button. The pickfile dialog is brought up and you can select a file to write to or enter the name of a new file in the box.
If you are ready to plot the lines on the echellogram, hit either the OK button or the Apply button. The OK button will close the dialog, while the Apply button will leave the dialog open. If the list has been modified in anyway, hitting OK will prompt you to save the list if desired. Hit Yeas on the prompting dialog to save the list to a file, hit no to plot the lines and close the dialog without saving the list.
Before you plot the lines however, you may want to select the color for plotting. To do this, hit the Select Color button. The current color is shown in the box next to the button. If you hit the button, a new dialog is created. The box on the top shows the currently selected color. To adjust the color, move the sliders for the Red, Green, and Blue to the desired color. To adjust the Color System, click on the Select Color System menu, although, this is usually unnecessary. The RGB system is the default. The following table shows some sample colors in the RGB system.
RGB |
Color |
EFS Line |
255, 200, 50 |
Yellow-Orange |
Neon |
220, 220, 220 |
Light Gray |
Argon |
255, 100, 0 |
Red-Orange |
Krypton |
100, 255, 100 |
Light Green |
Xenon |
200, 200, 0 |
Yellow |
OH |
255, 0, 255 |
Magenta |
User Lines Default |
255, 255, 255 |
White |
None |
0, 0, 0 |
Black |
None |
0, 255, 255 |
Cyan |
None |
A special, useful feature of the user lines list is the ability to enter a Z to simulated a redshift of a spectral line, so that the lines in the list are plotted on the echellogram where the would fall if there were shifted by the specified amount. Redshifted wavelengths are determined using the relation:
l
shifted = ( 1+ Z ) lrestBy using this feature, if the object’s Z is known, it is easy to determine which filter and echelle and cross disperser angles to use to make sure the desired line falls on the detector.
Problem: "I can’t open the script I want to!"
Solution: Make sure the file is a *.csh file. If necessary, change the filter in the Open File Dialog to match the extension of the file to be opened. For example, if the file you want to open is a *.csh file named filename.sh, change the filter to *.sh or *.*.
Problem: "I can’t use multiple setup boxes. Why?"
Solution: Multiple setup boxes are only enabled for the Object Only and Object+Lamps calibration modes.
Problem: "My echellogram looks strange! The orders seem to have no thickness. What am I doing wrong?"
Solution: You may need to change the slit. In the High Resolution mode, the slits with slitlengths of 12" and 24" are intended to be used. In the Low Resolution mode, the 42" slits are intended to be used.
Problem: "I can’t plot some of the transmission curves for some of the filters! Why?"
Solution: Some of filters transmission curves have not yet been determined due to lack of data. The filters for which the Plot Filter Button is enabled have complete data and therefore transmission curves available.
Problem: "After using the bad pixel mask for a while, there are a few pixels that have been left behind and are cluttering up the echellogram. How can I get rid of them?"
Solution: The easiest way to redraw the echellogram is to reselect the slit you want to use from the slit dropdown menu. Every time the slit is changed, the echellogram is redrawn. Even if you don’t change the slit, selecting the same slit again will also redraw it, removing any stray marks left over from the bad pixel mask.
Aborting a script
Arc Lines
Argon
Bad Pixel Mask
Blocking
Boxes
Buttons
Calibration Mode
Clear Overlays
Coadds
Cross Dispersor
Draw Window
DRP Version
Echelle Angle
Echelle Order
Echellograms
Executing a script
Filters
Filter Blocking
Filter Transmission Curve
High Resolution
Imaging Mode
Integration time
Keyboard hotkeys
Krypton
Low Resolution
Menu Bar
Neon
Nodding
OH Lines
Opening a line list
Opening a Script
Overlays
Plot Filter Profile
Postage Stamp
Purpose
Quitting EFS
Saving a line list
Saving a Script
Setting Nod Parameters
Setup Boxes
Slits
Spectral Lines
Spectral Mode
Starting EFS
User Lines
Wavelengths
Xenon