SKYMAP Users Guide

EGRET/GSFC(STX)/LM/SKYMAP/92/AUGUST

IDL SKYMAP - USER'S GUIDE

NASA CONTRACT NAS5-30440
TASK 69-233-03

Prepared for
Goddard Space Flight Center
by
HUGHES - STX

Prepared by:
L. McDonald

Printed on Jul 22, 1998
User's Guide on January 1993

Abstract

This document provides information on how to use the IDL version of SKYMAP. Section 1 contains a general description of the program. Section 2 lists the steps to execute the program. The program I/O interface is described in section 3.

General Description

Program Purpose
Program Description
Applicable Documents

Running the Program

Hardware Requirements
Preliminary Requirements
Execution

I/O Interface

Inputs
Image Display
Analysis Options
Outputs

1 General Description

1.1 Program Purpose

The IDL SKYMAP program reads and displays images stored in files that contain a valid FITS image and header or ASCII files generated from the EGRET scientific analysis program LIKE. Additionally, the program features a number of interactive data analysis tools that will allow the user to locate the maximum bin, display the value and coordinates of a bin, smooth the image, logarithmically scale the image, draw image contours, project histograms reflecting bin value totals for each axis, print the image, rescale the pixel colors and zoom in on a subimage.

1.2 Program Description

The SKYMAP program runs from within IDL. When SKYMAP is run a window will appear containing an area displaying instructions and information, an area where all files in the directory set by the environment variable FITS_DIR are listed, an image display area and data analysis tools menu. The user will select a file from the File Listing area or select one of the suboptions under the Alt File menu option to select a file that is not listed. The image stored in the selected file will be displayed and the program then waits for an analysis option, another file or the EXIT menu option to be selected. At input time, the user will only need to know what file is to be displayed and its location on the system.

1.3 Applicable Documents

Additional information related to the SKYMAP program may be found in the following documents.

MAPGEN Program Definition
Implementation of the Flexible Image Transport System NOST 100-0.3b
EGRET Telemetry and Data Formats, # 82-3-5

2 Running the Program

2.1 Hardware Requirements

The IDL version of SKYMAP will run in the windowing environment on Sun4 systems and SPARCstations onto which IDL software has been installed.

2.2 Preliminary Requirements

Prior to running the program, a number of environment variables should be properly set. The default values of these variables are normally set by adding an entry for each in the user's .cshrc file. The specific environment variable declarations that should be included in the user's .cshrc file are:


   IDL_PATH ........ directory path specifying the locations of all IDL
                      routines.

   FITS_DIR ........ directory location of files containing images that are
                      to be displayed

   MISC_DIR ........ directory location of files containing the data used
                      to display sources and the color tables.

To manually set an environment variable, use the setenv command e.g.

setenv FITS_DIR ~userid/fits

     setenv IDL_PATH  
/usr/local/lib/idl/lib/demo:/usr/local/lib/idl/lib/statlib:
     
/usr/local/lib/idl/lib/userlib:/usr/local/lib/idl/lib/widgets:/usr/local/lib/
     
idl/lib/xdemo/examples:/usr/local/lib/idl/lib/xdemo:/usr1/lib/idl.astro:/usr1
     
/lib/idl.general: /usr1/lib/idl.local

The program will use these variables to access all necessary IDL routines and data files.

2.3 Execution

The SKYMAP program may normally be run from any directory in a windowing environment. To run SKYMAP, the user can type skymap at the Unix prompt. This command runs a shell script that invokes IDL and runs the SKYMAP routine. Optionally, the user can run SKYMAP from within IDL by typing idl at the Unix prompt and then skymap at the IDL prompt.

3 I/O interface

All I/O takes place from the one SKYMAP window seen in Figure 1 as it first appears. The top left area, hereafter called the Instructions/Information area, will display instructions and information, providing a history of the user's selections. Underneath this area is the File Listing area where, initially, files located in the directory specified by the environment variable FITS_DIR are displayed. The EXIT button is below the File Listing area. On the right side of the window is the Image Display area and along the bottom is the Data Analysis Tools menu. Files and menu items are selected by moving the cursor to the file name or menu button and clicking once. Arrows displayed next to the button label of or an extra "box" around the Data Analysis Tools menu item indicate that there are suboptions for this menu item. These suboptions will appear when you click once on the menu button with the left mouse button. The user then selects one of the suboptions, again by clicking on it once. If user input is required after selecting a menu item, a separate window will be displayed to accept the input. Whenever possible, the program automatically moves the focus to this input window.

3.1 Inputs

Figure 1: Skymap window larger

Skymap Window (figure 1)

Select a file: the user must specify the file that contains the image that is to be displayed. There are three ways to select this file.
1. Point and click once on the file in the File Listing area.
2. Select the Alternate File suboption under the Alt File menu item that is located in the Data Analysis Tools menu along the bottom of the window and enter the full path of the file. This file may contain a FITS or ASCII format image.
3. Select the Display Alternate Directory suboption from the Alt File menu item, enter the directory that contains the desired file or select one of the default "commonly used" directories displayed. Edit the default file name filter, if required, and then point and click on this file after the selected directory is displayed in the File Listing area.
If the selected file does not contain a header that is recognizable by the program, an error message will appear in the Instructions/Information area and the user will be prompted to select a different file.
Select an energy range: if the selected file is in FITS format and contains image data for more than one energy level, a menu will appear indicating the available energy levels. An option to quit will also be part of the menu and, if selected, will allow the user to abandon the current selection. If an energy level is selected or if the selected file contains data for only one energy level, the image is displayed in the Image Display area.

3.2 Image Display
The image is displayed in the Image Display area with a grid overlay reflecting the coordinate system of the image.
Along with the selected image the Image Display area contains the image color legend and information about the image that was extracted from the header of selected file.
The color legend is located to the right of the image plot and is used to determine the values of bins. The legend initially consists of twelve color sections each corresponding to a range of bin values. When an image is originally displayed, the top and bottom section represent only one value, the highest bin value and the lowest bin value respectively. The other ten sections correspond to all other values divided into ten ranges of bin values. By locating the color section that matches the color of any bin, the user can determine in what range of values the bin value is. The ranges of the color legend can be changed by selecting the analysis option Rescale Pix. The colors of the bins in the image and the color legend can be changed by selecting the Change Color Table suboption under the Display menu option. The number and values of the color legend labels can be changed by selecting the Change Colorbar suboption also under the Display menu option.
If the image is in FITS format and the corresponding keywords are present in the FITS header the following information is displayed along the left side of the image plot. This information can also be picked up from headers in certain files that contain images in ASCII format.
- Map Units: if the file containing the displayed image is a standard EGRET FITS exposure, counts or intensity map, units will be displayed. Additionally, if the displayed map is an exposure map, a note indicating whether the map has been scaled to be in units of cm² s will be displayed.
- Start Time: the date and time that the accumulation of image data started.
- End Time: the date and time that the accumulation of image data ended.
- Map Type: the type of map.
- Energy Range: the range of energy the displayed image represents.
- Pointing Direction: the pointing direction of the spacecraft at the time the image data was accumulated. The coordinate system is indicated by the text along each axis of the image. The pointing direction is always in degrees.
- File Name: the name of the file. If the file name is too large to be displayed along the left side of the image display, it is displayed at the top of the image.
Depending on which analysis options have been performed on the image, the following information may also appear in this area of the display.
- If an image has been smoothed the sigma value in degrees will be displayed.
- If the image has been logarithmically scaled the words Log Scaling will be displayed.
- If the pixels have been rescaled the words Rescaled Pixels will be displayed.
3.3 Analysis Options
Along the bottom of the window are buttons used to select the image analysis options. Some buttons have a submenu indicated by the arrow next to the button label or an extra box around the button. The submenu is displayed when the user clicks anywhere on the button.
Hardcopy: the options associated with this feature are Default Printer, PostScript File Only, Choose Printer, Print Setup, Mosaic Mode, Aitoff Projection and Write to FITS File
- Default Printer: the current image will be saved in a PostScript file named idl_skymap.ps in the user's HOME directory and, if the user is running IDL and SKYMAP from a local machine, it is also sent to the default printer. The default printer for a black & white image is lpr and the default for a color image is the printer indicated by the environment variable EGRET_PRINTER. If the user is not on a local machine, the PostScript file will be created but will not be sent to a printer. The PostScript file name and default printers can be changed by selecting the Print Setup option.
- PostScript File Only: the current image will be saved in the user's HOME directory in a PostScript file named idl_skymap.ps. The name of this file can be changed within the Print Setup option. No files will be sent to the printer.
- Choose Printer: the user will be prompted for the name of the printer to which the PostScript file is to be sent. Only the current image will be sent to this print. Print Setup can be used to change the default printers for the remainder of the current SKYMAP session.
- Print Setup: the user selects this option to change the format of the output. A user interface will be displayed to allow the user to remove the header information, remove the color bar, change the size of the axis characters, erase or change the title above the image and change the axis labels. The options to save the image as encapsulated PostScript and to change the name of the PostScript file from the default name are also included. Also, the default printer can be changed. To do this the user should select the Alternate printers button and then change one or both printer names. These new printers will be used for printer output for the remainder of the current SKYMAP session or until the user changes them. To change back to the default system printers the button Default system printers should be selected.
- Mosaic Mode: this option was added to allow users to generate printouts of enlarged sections of images to use for posters. The current image is divided into sections and each section is then enlarged as much as possible to fill the printout page. A slight overlap will be included in each section to make cutting and pasting easier. The user is prompted to select the number of sections. Only numbers that will result in an even division of sections will be displayed for selection. PostScript files will be created for each section and will be located in the user's HOME directory. These files will be named skymap_sectX.ps where X is the section number starting from the left side of the map. The header information will be in a separate PostScript file named skymap_section_head.ps. No files will be sent to the printer.
- Aitoff Projection: this option was added to allow users to display the current image in Aitoff projection. There are three options under this menu item, Display Aitoff, Print Aitoff and Return to Rectangular Projection . Display Aitoff displays the image in Aitoff projection to the screen. Print Aitoff will display a user interface that provides the user with print options. Return to Rectangular Projection will switch the image back to its original rectangular projection. All image manipulation or plotting functions such as smoothing, plotting sources, plotting circles, etc. should be performed before selecting this option. Only the Print Aitoff and the Return to Rectangular Projection functions under the Aitoff Projection menu can be performed while the image is Aitoff projection. The selection of any other function will result in a change back to the original rectangular projection before the function is performed.
- Write to FITS File: the user will be prompted for the name of the FITS file into which the current image will be written. Not all aspects of the current image will be perserved in the new FITS file. Smoothing and zooming will be perserved but rescaling and any overlays of contours and sources, etc. will not.
Alt File: the user selects this option to select a file that is not listed in the File Listing area. When the user clicks on the option two suboptions will appear.
- Alternate File: the user selects this option to select a file that does not appear in the File Listing area. An input box will appear and the user types the full path name of the file that contains the image to be displayed. The ~ character can be used.
- Alternate Directory: the user selects this option to display in the File Listing area the files from any directory. An input box will appear and the user can type the full path of the directory or select one of the default directories listed. When entering a directory path, the ~ character can be used. The user can enter a Unix filter to limit the number of files displayed otherwise all files located in the entered directory will be listed in the File Listing area. Subdirectories are not listed. The user can then select a file by clicking on the file name.
- Refresh Directory: the user selects this option to redisplay the current directory. This option may be useful if image files are being created in the currently displayed directory as SKYMAP is running.
Histogram: the user selects this item to plot histograms showing the total bin values for each axis. A separate window will appear to accept changes to the default bin ranges and to display the plots. The user presses the button labeled Display Histogram after making any range changes and the histogram plots will be displayed. The user may continue to change the range values and plot the histograms, send the current histogram display to a PostScript file, or press the button labeled Done to exit.
Smooth: the user selects this item to perform Gaussian smoothing on the image. There are two options under this menu item, Linear and Logarithmic.
- Linear: the user selects this option to perform standard linear gaussian smoothing. The user is prompted for the sigma value in degrees and the image is smoothed and displayed accordingly.
- Logarithmic: the user selects this option to perform both linear gaussian smoothing and logarithmic scaling. The user will be prompted for the smoothing sigma value in degrees and after the image has been smoothed, logarithmic scaling is performed. The resulting image is then displayed.
Smoothing is always performed on the original image data even if prior logarithmic scaling and smoothing have been performed. To smooth a logarithmically scaled image the user should select the Smoothed suboption under the Log Scaling menu option. If linear smoothing is selected after the color scheme has been changed using the Rescale Pix option, the revised color scheme will remain. However, if logarithmic smoothing has been selected, the revised color scheme will be eliminated and the color legend will be recalculated to reflect the color scheme of the new image. If the displayed image is a subimage of the original image the smoothing will be performed on the original image and then the subimage will be taken from that and displayed.
Log Scaling: the user selects this item to perform logarithmic scaling on the displayed image. There are two options under this menu item, Unsmoothed and Smoothed.
- Unsmoothed: if this option is selected, the image is logarithmically scaled and displayed.
- Smoothed: the user selects this option to smooth a logarithmically scaled image. The user will be prompted for the sigma value in degrees and smoothing will be performed after the logarithmic scaling has taken place.
Logarithmic scaling is always performed on the original image data even if prior logarithmic scaling and smoothing have been performed. To logarithmically scale a smoothed image the user should select the Logarithmic option under the Smooth menu option. Any pixel rescaling that was performed before this item is selected will be eliminated and the color legend will be recalculated to reflect the color scheme of the new image. If the displayed image is a subimage of the previous image the scaling will be performed on the original image and then the subimage will be taken from that and displayed.
Contours: the user selects this item to draw contours on the displayed image. There are two options under this item, LHOOD Predefined and Other.
- LHOOD Predefined: the user selects this item to draw contours in one or both of the standard likelihood contour modes. A listing of the two modes are displayed as suboptions when this option is selected.
  - Fine: the user selects this suboption to display the 4 contours Fine map contours. These 4 contour levels are defined as the peak minus 1.4, peak - 2.3, peak - 6.0 and peak - 9.1. These contours represent confidence levels of 50%, 68%, 95% and 99%, respectively.
  - Survey: the user selects this suboption to display contours at the absolute test statistic values. These values are 3.9, 16.5 and 27.5.
- Other: A separate window will appear displaying the default number of contour levels and values. The user may change the number of contour levels, at which time new contour level values will be calculated. The contour values can also be editted by changing the maximum and minimum values which will result in the values being recalculated, or by directly editting the displayed values. The user also has the option to erase the image when the contours are drawn, select the line style of the contours, disable the labelling of the contour lines, and draw the default Fine map contours. The actual labels can also be changed. (The default labels are the contour values.) In the lower section of the window a color bar is displayed to allow the selection of the color of the contour lines. The ability to change the color table is also provided. The user presses the Change Color Table button to perform this function. When the window reflects all desired contour criteria, the user presses the Draw Contours button. If contours have been drawn previously with the image erased, the next time this Contour option is selected the user will have the option to redraw the image or to select new contour criteria as just described.
Figure 2: Contour window larger

Contour Window (figure 2)
Reset: the user selects this option to re-display the original image in the most recently selected file. All changes to this image made after it was originally displayed will be eliminated.
Zoom: the user selects this item to display a subimage of the currently displayed image. The maximum and minimum coordinates of this image are displayed in the Instruction/Information area to remind the user of the size of the original image. A window will appear giving the user three options to define the subimage: Point and Click, Enter Coordinates from Keyboard and Wrap-Around Zoom. At any time The user may select CANCEL to exit the Zoom function without further processing.
- Point and Click: if this button is pressed the user will click on two diagonal corners of the desired subimage. To aid in selecting specific coordinates, the coordinates of the cursor position are displayed as the cursor moves across the image.
- Enter Coordinates From The Keyboard: if this button is pressed, entry boxes will be enabled to accept the new beginning and ending coordinates along the X and Y axis. Error checking will be performed to ensure that the new coordinates are within the limits of the current map.
- Wrap-Around Zoom: this option allows the user to connect the outer edges of the map and display the resulting image. In other words, if the map is a full sky map with coordinates ranging from 180 to 180 degrees the image can be displayed as a full sky map with coordinates ranging from 0 to 360. A subimage can also be displayed, e.g., a subimage of the 180 to 180 map ranging from 150 to 210, centered on the 180 degree line.
After new coordinates have been successfully entered or clicked upon the subimage will then be displayed. The subimage will reflect any scaling or smoothing that has been performed on the previous image.
Bin Info: the user selects this item to get coordinate and bin value information. The user points and clicks the left mouse button on any location on the image and the value of the bin and the coordinates in both coordinate systems will be displayed in the Instructions/Information area. The right mouse button is pressed to exit this function.
MaxBin: the user selects this item to locate the bin with the maximum bin value. A circle will be drawn around and a crosshair drawn through the bin with the maximum value. The bin value and coordinate information will be displayed in the Instructions/Information area. If more that one bin contains the maximum bin value, the first of these bins nearest the bottom of the display will be used.
Rescale Pix: the user selects this item to change the color scheme of the map. The color legend along the right side of the image shows the colors and their respective range of values. When the image is originally displayed, the top color (white) is the color of the bin with the highest bin value and the color at the bottom of the color legend is the color of the bin with the lowest bin value. The other colors represent the bin values between the highest and lowest value and the these value ranges are divided according to the color distribution of the EGRET Skymap color table. The user may change this color range by entering the new values to be represented by the top and bottom colors of the color legend. The color legend will be recalculated to reflect these new maximum and minimum values and the pixels of the image will be changed accordingly.
When this item is first selected, a window appears with the calculated minimum and maximum pixel values. At this point the user can select Done to set these values as the rescale values, or edit the displayed values. If the user wants to see how any new values will affect the image, the Show Changes To The Screen option can be selected. Cancel is selected to abandon any changes made (i.e., previous minimum and maximum values will be restored). Done is selected to accept the currently displayed values.
Pixel rescaling can be performed on any image no matter what other analysis options have been performed (i.e., Smooth, Log Scaling).
Maps: this option allows the user to process Fine maps generated in the LIKE program. There are two suboptions Process Fine Maps-One Per Page and Process Fine Maps-Six Per Page. If the first option is selected, the processing includes displaying the image, drawing the default Fine map contours, plotting sources from the source list or from a different source list formatted in the same way as the standard source list, displaying the history from the FITS header and saving the image in a PostScript file. The user will be prompted for the location of the Fine maps which can be in the displayed directory, the current working directory or the directory indicated by the environment variable FITS_DIR. A Unix filter will can also be used to select the files. The default filter is GROJ*[0-9] which is the default name format from the LIKE program. The user also has the option to draw contours with no image. The second option Process Fine Maps-Six Per Page processes maps in the same way as the first option except that the plots are 6 per page with contours but no image and no history is displayed. The option to create encapsulated PostScript files is included in this second option.
Overlay: the user selects this option to overlay the contours of one image onto another image. To implement this option the user displays the image to be overlaid on a second image and then draws contours on the image using the Other option under Contours menu item. The user then selects the Save Contours option under the Overlay menu item to save the current image and contours to a file named skymap_overlay.dat in the user's HOME directory. The user can then display another image and select the Overlay Contours option under the Overlay menu item to draw the saved contours on the current image.
Display: the user selects this option to perform miscellaneous display functions. When selected a sub menu appears listing seven suboptions, Change Color Table, Grid Off/On, Alternate Coordinate Grid, Display/Erase History, Draw/Erase Circle around Pointing Direction, Exp Map unit conversion Off/On and Change Colorbar.
- Change Color Table: the user selects this option to change the color scheme of the image by changing the color table. A menu listing all possible color tables will appear and the image and color legend will change according to the table that is chosen. The menu will remain until the user has selected the QUIT button which is located at the end of the menu.
- Grid Off/On: the user selects this item to remove the grid that overlays the image. If the grid has already been removed, selecting this option will cause the grid to reappear.
- Alternate Coordinate Grid: the user selects this item to display the grid of coordinate systems other than the one that is currently displayed. The original grid will be removed. To re-display the original grid the user selects the Grid Off/On option.
- Display/Erase History: the user selects this item to display information from the FITS file header associated with the first ten occurences of the keyword HISTORY. If the keyword HISTORY does not exist in the header no information will be displayed. If this history information has been displayed, it will disappear the next time the option is selected.
- Draw/Erase Circle around Pointing Direction: the user selects this item to display circles on the image around the pointing direction or around some user-defined set of coordinates. The user can also select the radius and color of the circle. There is also the option to erase the circle.
- Exp Map unit conversion Off/On: if the map being displayed is a EGRET exposure map (the value of the FITS keyword BUNIT is 'Exposure') the image will be converted to cm² s. This option is selected to prevent this conversion from taking place. If this option has been turned off, selecting this option again will turn it back on.
- Change Colorbar: with this option the user can change the color bar legend. A user interface will be displayed that will allow the user to change the number of labels, change the location of the labels and change the actual label text. The initial color bar legend displayed with each image displays labels at the border of each color section (according to the EGRET skymap color table) reflecting the associated bin value. If the number of label sections is changed, the new labels will be be calculated to display at even intervals along the color bar.
  As an example, imagine the current image contains bin values between 0 and 152. The initial color legend will display 12 labels, one at the border of each color section, with values 0, .597, 15.5, 30.5, 46.0, 61.5, 76.5, 92, 107, 122, 137, and 152. If the user selects 4 as the new number of label sections, the new labels will be 0, 36.1, 76.2, 114 and 152.
  The interface also allows the user to change the value of the labels individually, thus changing the location of the label along the color bar. The text of the labels can also be changed. By default the text is the same as the value of the label.
Restore Session: this option can be selected to restore the image and directory listing that were displayed when the most recent SKYMAP session was exited. This information from the previous session is stored in the user's HOME directory in a file named skymap_session.dat.
Sources: the user selects this item to mark the location of sources. There are six suboptions for this item, five of which are the possible locations from which the source coordinates are read.
- From Source List: the user selects this option to display sources with coordinates located in the file MISC_DIR/src.list. A window will appear to prompt the user for the symbol to be plotted at the source locations and the symbol color.
- From Keyboard: the user selects this option to enter coordinates from the keyboard. A window will appear to accept any number of coordinate pairs. The user must press RETURN after each set of coordinates is entered. The coordinates will then be stored and the input area will be cleared to accept a new pair. The user presses the DISPLAY SOURCES button when the coordinate entry is complete. The symbol to be plotted at the source locations and the symbol color will also be selected in this window.
- From User-created File: the user selects this option to read coordinates from a user-created file. A window will appear to accept the name of the file and to provide the option to select the symbol to be plotted and the symbol color. In order for the coordinates to be read correctly, the format of the user-created file should be the same as that of the file MISC_DIR/src.list. Galactic coordinates are read from offset positions 66 and 75, and celestial coordinates from offset positions 84 and 93. The coordinates used for plotting will match the coordinate system of the current image.
- Proposal Sources: the user selects this option to display Phase 3 and Phase 4 proposal sources that are within 30 degrees of the pointing direction. The user will be prompted for the symbol to be plotted, the symbol color and the viewing period.
- From PSF File: the user selects this option to display sources from an output file generated in the LIKE program under the PA/O option. The user is prompted for the file name, the symbol to be plotted and the symbol color. If the coordinate system of the PSF and the current image differs, coordinate conversion will be attempted.
- Erase Sources: the user selects this option to erase all sources that have been plotted on the current image
A legend will be displayed above the image to enable the user match the symbol with the source type. The plotted symbols will remain on the image after other image manipulation tools have been selected.

3.4 Outputs

When EXIT is selected, a file named skymap_session.dat is created in the user's HOME directory. This file contains all current local and system variables and will be read in the user's next SKYMAP session if the Restore Session option is selected. The only other output from SKYMAP occurs if the Hardcopy option has been selected and is in the form of a PostScript file. This PostScript file is named idl_skymap.ps and is located in the user's HOME directory unless Print Setup has been used to change the name and location of this file. If the user is running SKYMAP from a local machine the PostScript file may be sent to a local printer.

File translated from T_EX by T_TH, version 1.56.