______________________________________________________________________________ SLITLESS Package Installation Instructions ______________________________________________________________________________ To install the SLITLESS package: 1) Down load the file slitless.tar from http://www.physics.unlv.edu/~cnelson/slitless.html and save it in some appropriate directory. 2) type: tar xvf slitless.tar The following files will appear in the directory: imsize.cl plotlog.cl plotlog.f slitless.cl velocity.cl velplot.f Now using your favorite editor, edit the file slitless.cl. 3) emacs slitless.cl 4) Go to the line that says: set slitless = "/path-name/" and change "/path-name/" to the directory that contains the downloaded files. Be sure that there is a "/" at the end. As an example, in my set-up the line reads: set slitless = "/data/cnelson/scripts/slitless/" 5) Don't change anything else and save the file. Next cd to your "home$" iraf directory, (the one that contains your login.cl file) and edit the loginuser.cl file. If you don't already have one, make a file called loginuser.cl and edit it this way. 7) emacs loginuser.cl 8) Add the following line somewhere before the last line (which should say "keep"). task $slitless.pkg = /path-name/slitless.cl Again replace "path-name" with the directory name of the downloaded stuff. As an example, the line in my loginuser.cl files looks like this: task $slitless.pkg = /data/cnelson/scripts/slitless/slitless.cl 9) If you are creating the loginuser.cl file on the last line type: keep Also be sure to type a carriage return at the end so that IRAF will recognize the line! 10) Exit the editor and at the IRAF prompt type: cl < loginuser.cl The fortran programs velplot.f and plotlog.f will need to be compiled using "fc" in IRAF and linked with PGPLOT subroutines. The procedure below should work if you replace "pgplot-dir" with the full pathname of libpgplot.a, which is the library of PGPLOT subroutines. I don't think that there is any non-standard fortran in the program so it should go fine. If you have never used PGPLOT before, be sure that somewhere in one of your startup files (e.g. .cshrc, .profile, .login, ...) that there is a line that says: setenv PGPLOT_FONT=/"pgplot-dir"/grfont.dat (or if you use Bourne Again shell, or bash setup export PGPLOT_FONT=/"pgplot-dir"/grfont.dat) So do the following: 11) Locate the PGPLOT stuff on your local disks (probably in /usr/lib/pgplot/ or something similar). 12) In a window with IRAF running, go to the directory where you placed the SLITLESS package. 13) Type the following line with "pgplot-dir" replaced with the directory for the PGPLOT stuff. fc velplot.f /"pgplot-dir"/libpgplot.a -lX11 -lm 14) Type the following line with "pgplot-dir" replaced with the directory for the PGPLOT stuff. fc plotlog.f /"pgplot-dir"/libpgplot.a -lX11 -lm 15) Now, in the same iraf window as above type: slitless 16) This loads the SLITLESS package like loading any other IRAF package. It should print a list of the tasks in the package: imsize plotlog velocity 17) Done! In the future all you will have to do is load the slitless package (step 15). ______________________________________________________________________________ How to Use the SLITLESS Package to Measure Velocities in Slitless Spectroscopy Data. ______________________________________________________________________________ I. Overview The SLITLESS package is designed to help in matching emission line features in slitless or wide slit spectra with their counterparts in narrow-band emission line images to calculate radial velocities for emission line gas. It is designed with STIS data in mind but could be easily modified to work on other similar data sets. The main task is "velocity" in which the measurements are made. The "imsize" task is a simple script to get the size of an image and although it could have been directly incorporated is useful as a separate task. The "plotlog" task takes the output logfile from "velocity" and produces PGPLOT graphs of the data using a number of options. Here is a brief overview of the process and a more detailed step-by-step account follows below. The first steps are to match the spatial scales and orientation of the two images and display them in a standard IRAF display device (e.g. ximtool or saotng). Rotation and rebinning are only done on the narrow band image so that the dispersion direction and scale are not altered in the slitless image. Using an image cursor, you then mark a zero-point in each image for the spectral and spatial scales. This should be a bright isolated knot which is clearly the same emission line cloud in each image. The galaxy nucleus might make a good choice for this. Next, PGPLOT graphs of "slices" from each image are made at various distances from the zero-point, parallel to the dispersion. Using a graphics cursor, you then mark features and label them, such that peak #1 in the slitless spectrum slice is matched with peak #1 in the emission line image slice, etc. If done carefully, reliable velocities can be obtained from this "by-eye" marking. Alternatively, you can fit single or multiple Gaussians to a range of pixels in each image or you can make profile cuts at 80%, 50%, and 20% of the peak height, similar to those used in characterizing emission line profiles. The relative shift between the centers obtained in any of these manners is converted into a shift in wavelength and then a velocity. Also the widths of the fits and profile cuts are saved and analyzed. The width from the emission line image is subtracted in quadrature from the slitless width. This is converted to a width in Angstroms and then a velocity width. The data are stored in a log file and you move on to the next pair of "slices". When finished the "plotlog" task can be used to read in the data from the log file and plot velocity versus zero-point distance for any of the different measurements. II. A Typical Session with the Velocity Task We will now go through the details of a typical session with "velocity" and "plotlog" as a demonstration. If you have any questions or problems please contact me by e-mail at cnelson@physics.unlv.edu or (702) 895-1776. A. Things to Do in the Image Display The first thing to do is to type epar velocity. A number of parameters are listed, however only the first nine need concern us at this point (the others merely provide a prompt for altering the defaults later on). Briefly, the first two (slimage and emimage) are the slitless spectrum image and the emission line image. The third (logfile) is the name of a logfile to use. The next four are the top and bottom display levels (corresponding to z1 and z2 in the IRAF task DISPLAY) for each image (slz1 & slz2 for the slitless spectrum, emz1 & emz2 for the emission line image). The next parameter (lambda0) is the rest wavelength of the line we are going to analyze. The last parameter (nadd) is the number of rows to sum up perpendicular to the dispersion to make a single image slice (it can be changed from within the program so any value is fine for now). After these have been entered type :go or get out of epar and type "velocity slitless-image emission-line-image" at the IRAF prompt. If all is going well information on the spatial and spectral scales and the image orientations are printed, the images are displayed (slitless in frame #1 and emission line in frame #2), and and IRAF image cursor appears. Typing '?' will print out a list of the options and should look like this: c --- cursor position i --- imexamine task m --- magnify n --- # spatial pix. to sum p --- plot r --- rotate s --- change stretch z --- set zero points ? --- commands q --- quit Here is a bit more info on each: c --- cursor position --- prints the x,y and pixel values of the cursor. i --- imexamine task --- gets you into the imexamine task with all of its usual options (type q to return to the current task). m --- magnify --- resample the emission line image with the goal of matching the spatial scale of the slitless spectrum. n --- # spatial pix. to sum --- change the number of rows summed into a slice. p --- plot --- plot slitless spectrum and emission line image slices for analysis. r --- rotate --- rotate the emission line image with the goal of matching the orientation of the slitless spectrum. s --- change stretch --- change the stretch (z1 and z2) of the currently displayed frame. z --- set zero-points --- set the spectral and spatial zero-points of each image. q --- quit ? --- help The first thing to do is to rotate and change the pixel scale of the emission line image. This is done using 'r' and 'm'. The rotate command uses the IRAF rotate task. It will prompt for an angle to rotate (positive for counter-clockwise) and supply a default value which is the difference between the ORIENTAT header keywords. The default value will work if no other rotations have been performed and the header values are accurate. The IRAF task magnify is used to change the pixel scale. Scale factors for both X and Y axes are prompted for since the STIS spatial scale is slightly different along or across the dispersion. Therefore, it is probably best to rotate the image before magnifying. The header value for the pixel scale is pulled from the emission line image and a default scaling factor is computed by combining with the known STIS pixel scales as given by Woodgate et al. (1998, PASP, in prep.). The output from the rotate and magnify commands is stored as an image on the disk with the same name as the emission line image but with the suffix .rescale attached. This image can be then used in subsequent sessions without having to repeat these steps. Note, however, that if the task is rerun the .rescale image will be deleted so if you want to keep it you might want to rename the image immediately after running the task. Next, you should center and zoom the display windows to frame the specific emission line in the slitless spectrum and the desired features in the emission line image. The next step is to choose an appropriate zero-point for each image. The best choice for this is a feature which is clearly the same in both. Position the cursor over the chosen feature in either image and type 'z'. The frame is then automatically switched to the other one. Position the cursor over the corresponding feature in this frame and type 'z' again. The task uses the IRAF imcntr task to center up on the brightest area using a box-size of 7 pixels, so although one should be careful here, being off by a few pixels when you hit 'z' shouldn't be disastrous. All velocities measured in the program will be relative to the velocity of this feature, whatever it is. B. Things to Do in the Graphics Window We are now ready to plot a pair of slices. Select a feature in either of the two images, position the cursor over it and type 'p'. A PGPLOT graphics window should appear showing two panels. The upper panel will always be the slitless spectrum and the lower will always be the emission line image slice. There should also be a graphics cursor. Typing '?' will give another list of options which applies to the graphics cursor input. ---------------------------------------------------------------------- Graph Options ---------------------------------------------------------------------- 1,2,3,4,5,6,7,8 or 9 --- Mark cloud peaks a --- autoscale b --- set continuum at zero c --- fit continuum d --- draw continuum e --- evaluate velocities f --- write PostScript file g --- multiple Gaussian fits h --- horiz. window edges i --- Cursor position j --- Pixel value m --- match horiz. window scale p --- profile analysis q --- quit r --- replot s --- show profile & Gauss. fits t --- toggle line mode v --- vert. window edges z --- toggle zero point ? --- commands ---------------------------------------------------------------------- Here is a bit more info on what each of these does: 1,2,3,4,5,6,7,8 or 9 --- Mark cloud peaks --- Identify features in both the slitless spectrum or the emission line image using numbers. The idea is that peak #1 in the slitless spectrum should be the same feature as peak #1 in the emission line image. a --- autoscale --- If you have changed the window boundaries in a panel this gets back to the default window. b --- set continuum at zero --- makes the continuum level zero if you have changed it. (The continuum is assumed zero at the start.) c --- fit continuum --- doesn't work yet! d --- draw continuum --- mark two points and the program will draw a straight line continuum through them. Choose them to be well-separated so that the line extrapolates through where the continuum ought to go. e --- evaluate velocities --- prints out results on the screen as they will appear in the log file. f --- write PostScript file --- saves current screen as a PostScript file. The files are named automatically as velocity**.ps where ** is a two digit number. These files will be erased the next time you execute the task so if you want to keep them I recommend that you print them out or rename them immediately after you are done. g --- multiple Gaussian fits --- Mark 'g' twice to indicate the range of points to be used in Gaussian fits. The algorithm will use as many Gaussians as there are peaks that fall in the fit range. h --- horiz. window edges --- Mark 'h' twice to define the x-values of the new plot boundaries. The y-boundaries will also change based on the min and max pixel values in the new window. i --- Cursor position --- print the cursor position on the graph. j --- Pixel value --- print the value of the pixel nearest the cursor. m --- match horiz. window scale --- if you have changed the window boundaries of one of the panels, typing 'm' in the other will redraw it with the same horizontal plot boundaries. p --- profile analysis --- begin an analysis of a marked peak using cuts at 80%, 50%, and 20% of the peak value (see below). q --- quit --- quit the graphics section of the task and return to the image cursor. The program will ask you if you want to save your measurements in the log file. r --- replot --- redraw the graph with the current profile analysis and Gaussian fit info. s --- show profile & Gauss. fits --- doesn't do anything yet. t --- toggle line mode --- switches between line and histogram representations of the data, similar to the histogram mode in the IRAF task splot. v --- vert. window edges --- Mark 'v' twice to indicate upper and lower bounds to the graph window. z --- toggle zero point --- By default the axes are labeled relative to the zero-point. However, it is sometimes useful to know the real pixel numbers in the original image. Type 'z' to switch back and forth between x-axis labels relative to the zero-point and simply the image pixel values. ? --- commands --- Print out command list. At this point it is useful to mark the continuum level (at least in the slitless spectrum). So far this is done by eye although I may add a routine to fit polynomials to a range of points (it will be the 'c' command). Position the cursor at two well-separated points that look like they are within the continuum noise. A straight line will be drawn through the points. Now, zoom in on the emission line of interest using the 'h', 'v' and 'm' windowing commands. 'a' will get you back to the default window boundaries. Now identify the peaks in one of the panels by placing the cursor under the peak as close to centered as possible (if you want to use the "by-eye" centers) and typing 1 for the first, 2 for the second, etc. Do the same in the other panel, this time being careful that peak #1 in the first panel is the same feature as peak #1 in the second, etc. Ideally, for each peak in the emission line slice there should be a corresponding peak in the slitless slice. Multiple Gaussians can be fitted to the peaks if they are reasonably well defined. Mark 'g' twice to indicate the range of points to be used in the fit. The program will try to fit to as many peaks as are within the range. The basic routine uses the downhill-simplex algorithm (Numerical Recipes, section 10.4) to minimize residuals using an initial guess for the center, amplitude and width of each component. The program will then color the fitted points red, draw the fits for each individual component in orange, and the sum of all the Gaussians in green. A bad fit can be changed by redoing the fit with a different range of points. The last Gaussian fit to a given peak is the one that is saved in the logfile. To try the profile cut analysis type 'p' near one of the numbered peaks. You are then asked to mark the peak and peak center simultaneously. That is, position the cursor at the top of the peak and as close to what looks like the center as you can. It then asks you to mark the wings of the feature, i.e. the two points where the profile meets the continuum. I admit that this might be less meaningful for the emission line image slice where the object is extended and probably sitting on diffuse emission. However, it is important for returning a flux measurement for the features in the slitless spectrum slice. Then you are given the choice of manual ('m') or automatic ('a') profile fitting. Automatic works well for high signal-to-noise data, manual is better for noisy data. If you choose 'm' a cut at 80% of the peak height is drawn and you are asked to mark where the cut crosses the left and right sides of the profile. The same happens for the 50% and 20% levels. Having completed these measurements, typing 'e' will display the results on the screen as they will appear in the log. If you are unhappy with them you can go back and redo any of these. The last set of results for a given peak is what is saved. If satisfied you can go on and choose a new slice by typing 'q'. Before you can proceed you will be asked whether you want to save the data or not. Respond y or n to this and the image cursor will become active in the image display window. Since the zero-points are already established simply place the cursor over the desired feature in one of the images and type 'p'. IV. Description of the Log File The results are stored in a logfile that for a given slice looks like this for the case of two marked peaks: Slitless Spectrum Zero-Point: X0 = 169.25 Y0 = 601.59 Slitless Spectrum Slice: 610: 612 --- 8: 10 (from Zero-pt.) Emission Line Image Zero-Point: X0 = 304.37 Y0 = 344.98 Emission Line Image Slice: 353: 355 --- 8: 10 (from Zero-pt.) Rest Wavelength: 5006.90 --- Dispersion: 4.882 -------------------------------------------- Centers shift velocity # Slitless Em.Line Ang. km/s -------------------------------------------- 1 0.81 0.46 1.69 101 2 -2.86 -4.38 7.43 445 ------------------------------------------------------------------------------ Slitless Spect. Gaussians Emiss. Line Image Gaussians shift velocity # Center Sigma Amplitude Center Sigma Amplitude Ang. km/s ------------------------------------------------------------------------------ 1 0.86 2.02 2.0057E-15 0.78 3.02 15.746 0.40 24 2 -3.61 2.57 4.1978E-16 -5.16 1.33 5.616 7.59 455 -------------------------------------------------------------------------------- Profile Analysis # Flux Cpeak Peak C80 W80 C50 W50 C20 W20 C00 W00 -------------------------------------------------------------------------------- S1 1.71E-14 0.7 1.98E-15 0.6 3.3 0.6 5.5 -0.2 9.6 0.7 16.2 E1 174.005 0.8 16.100 0.7 3.6 -0.3 9.0 -0.8 14.7 0.0 17.4 V1 -20.2 -17.3 0.0 263.8 0.0 164.6 0.0 222.5 0.0 S2 --- --- --- --- --- --- --- --- --- --- --- E2 --- --- --- --- --- --- --- --- --- --- --- V2 --- --- --- --- --- --- --- --- --- -------------------------------------------------------------------------------- The first five lines present some basic information about each slice: the zero-point position of the slitless spectrum, the row numbers summed to make the slitless slice and their position relative to the zero point, the zero-point position of the emission line image, the row numbers summed to make the emission line slice and their position relative to the zero point, the rest-wavelength (assumed to be in Angstroms), and the dispersion in Angstroms/pixel. Next, the positions of the marked centers are listed, including the calculated wavelength shift in Angstroms and the corresponding velocity. Then, the results of the Gaussian fitting is given. Centers and sigmas are given in pixels and the amplitudes are in the units of the image pixels. Again the calculated wavelength shift in Angstroms and the corresponding velocity are printed. For the profile analysis, three lines are printed for each peak that you marked in the velocity task. The first line is for the slitless slice (hence S), the second is for the emission line slice (E) and the third is the calculated velocities. Fluxes are the sum of all the pixels between the wings that were marked as part of the measurement procedure. The center and width results for the individual frames are in pixels, while the velocity results are in km/s. For the widths (W80, W50, W20, W00) the velocity line is simply subtraction of the emission line image results from the slitless spectrum widths in quadrature, or zero if the emission line image fit gave larger values. Measurements that were not made are entered as '---'. IV. How to Use Plotlog Another task in the SLITLESS package is plotlog. Plotlog is a fortran program that is called like an IRAF task. It reads the data in a log file and provides a simple way of plotting the data. To use it, at the IRAF prompt type: plotlog logfilename (If you neglect to include the logfile name it will ask for it, you can also use epar to put it in.) You are first asked how many plots you want per page. The default (obtained by typing a '/') is given in parenthesis as 1 in X and 1 in Y. If you entered 2 2 you would get 4 plots, 2 along each axis. Next it asks for the device for plotting. /xwindow or /xserve are probably best or you can redirect the graphics output to a postscript file by typing filename/ps. Type '?' to see other options. Next a menu of things to plot is printed: X-Y axis options: 0: Quit. 1: Distance along slit from zero-point. 2: Mark Centers. 3: Gaussian Centers. 4: Profile Centers. 5: Slitless Spectrum Flux. 6: Emission Line Image Flux. 20: Change plot parameters. 21: Overplot next. Enter X-Y axis options: Simply type in the number of the thing you want on the X-axis followed by the number of the thing you want on the Y-axis. For example, to see a plot of slit position on the X-axis versus Gaussian fit velocities on the Y-axis you would type: 1 3 If you choose the profile centers you will be prompted for which center you want with C80 as the default (type '/' to get this). It says: Use Cpeak, C80, C50, C20, or Czero (1,2,3,4,0; /=2): It then asks for the X and Y axis boundaries for the plot. '/' again accepts the default values in parentheses, but you can type in the four values if you want a larger or smaller range. After the plot appears the menu is retyped on the screen. Type 0 as an option to quit. Type 20 to change the device parameters as above, for example to produce a PostScript file. Type 21 if you want the next plot to overplot in the same window. (This works fine except that the plot symbol is the same so its hard to tell which was the original and which was overplotted. I'm working on it!) V. Some General Comments So far, this program has been used by myself and Donna Weistrop which means that there may be many little bugs (or big ones) lurking. Please if you encounter any problems call or e-mail me and I can try to track them down. Some things may not work quite so beautifully all of the time. An example is the multiple Gaussian fits which are too unconstrained to work on noisy or highly blended peaks. I plan to implement more sophisticated fitting control (similar to what splot offers in IRAF) but I haven't needed to use it yet so it doesn't exist. In using the velocity task, the key is to identify the same peaks in each image slice. I find that looking back at the image display (without getting out of the PGPLOT graphics) is very helpful. In marking the centers, if one is careful about it, the initial mark may be good enough. If you're unhappy with the position simply reposition the cursor and retype the number. The number will now be typed at the new spot. Then type 'r' to replot and the old position will be gone. A couple of things to watch out for: the rotated and magnified emission line image will be deleted every time you start the program. The same is true for the PostScript plots. To be safe you should move and/or rename them if you want to keep them. One of the weaknesses of the program is that there is no error analysis. I hope to include this, but I still need to come up with a sensible procedure. Possibilities include having you mark your best estimates for the possible error by-eye, or having a more automated approach based on the uncertainties in the data. Any suggestions would be welcome. For that matter any suggestions on any aspect of the package are welcome. Charlie Nelson