Äîêóìåíò âçÿò èç êýøà ïîèñêîâîé ìàøèíû. Àäðåñ îðèãèíàëüíîãî äîêóìåíòà : http://www.astro.louisville.edu/software/sbig/archive/xmccd-4.1/xmccd-4.1e/docs/ds9/ds9_user.pdf Äàòà èçìåíåíèÿ: Tue May 31 02:25:13 2011 Äàòà èíäåêñèðîâàíèÿ: Thu Feb 27 22:29:57 2014 Êîäèðîâêà: Ïîèñêîâûå ñëîâà: ñîçâåçäèå ëåáåäÿ

Table of Contents
DS9 Users Manual . . . . . . . . . . . . . . . . . . 1

SAOImage DS9 Users Manual

.

.

.

.

.

.

.

.

.

.

1

Introduction to the ds9 Interface - DS9 . Introduction to the ds9 Interface . . . Synopsis . . . . . . . . Contents . . . . . . . . The ds9 Interface . . . . . . Figure 1: The ds9 GUI . . . . Figure 2: The ds9 GUI, vertical layout 1. Menu bar . . . . . . Figure 3: Menu bar . . . . . Figure 4: Tearing off a Menu . . 2. Information panel . . . . Figure 5: Information panel . . . 3. Panner . . . . . . . Figure 6: Panner . . . . . 4. Magnifier . . . . . . Figure 7: Magnifier . . . . . 5. Buttons . . . . . . . Figure 8: Buttons . . . . . 6. Display frame . . . . . Figure 9: Tiled frame display . . 7. Colorbar . . . . . . Figure 10: Colorbar . . . . . Setting and Saving View Preferences . Figure 11: Preferences dialog box . History . . . . . . . . Binning and Filtering FITS Event Files - DS9 Binning and Filtering FITS Event Files . Synopsis . . . . . . . . Contents . . . . . . . . Getting Started . . . . . . Figure 1: Data loaded with default buffer Figure 2: The Bin menu . . . . Buffer Size . . . . . . . Figure 3: Buffer size set to 128x128 . Figure 4: Buffer size set to 4096x4096 Binning Basics . . . . . . Changing the binning factor . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . and . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . bin size . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2 2 2 2 2 3 5 6 6 6 8 8 8 8 9 9 9 9 9 10 11 11 11 11 12 13 13 13 13 14 14 16 17 17 19 21 21

i


Figure 5: Data binned by a factor of 4 . . . . . . Binning different columns . . . . . . . . Figure 6: The Binning Parameter dialog . . . . . Figure 7: Image binned in detector coordinates . . . . Data Cubes: Binning in three dimensions . . . . . Figure 8: Binning Parameter dialog for a data cube . . . Figure 9: Data Cube dialog box . . . . . . . Figure 10: Viewing a data cube . . . . . . . Filtering Data . . . . . . . . . . . . Figure 11: Filtering data . . . . . . . . . History . . . . . . . . . . . . . Contours - DS9 . . . . . . . . . . . . Contours . . . . . . . . . . . . . Synopsis . . . . . . . . . . . . . Contents . . . . . . . . . . . . . Creating Contours on a Dataset . . . . . . . . Figure 1: Contour Parameters dialog box . . . . . Figure 2: X-ray data with contours . . . . . . Copying the Contours to Another Frame . . . . . . Figure 3: SAO-DSS Server dialog box . . . . . . Figure 4: X-ray and optical data with contours . . . . Saving the Contours . . . . . . . . . . Converting to Polygons and Saving . . . . . . . History . . . . . . . . . . . . . Create a True Color Image in an RGB frame - DS9 . . . . Create a True Color Image in an RGB frame . . . . . Synopsis . . . . . . . . . . . . . Contents . . . . . . . . . . . . . Creating an RGB Frame . . . . . . . . . A. From the command line . . . . . . . . B. From the ds9 GUI . . . . . . . . . Figure 1: RGB window . . . . . . . . . Figure 2: Lock menu in the RGB window . . . . . Figure 3: RGB frame with three files loaded . . . . Apply Energy Filters . . . . . . . . . . Figure 4: Energy-filtered RGB data . . . . . . Smoothing the Data (optional) . . . . . . . . Figure 5: Data smoothed with a Gaussian of radius three . . Adjusting the Scale Parameters . . . . . . . . Figure 6: The adjusted pixel distribution for scaling . . . Adding a Coordinate Grid . . . . . . . . . Figure 7: Coordinate Grid parameters dialog box . . . Figure 8: Final three-color image with coordinate grid overlaid Saving the Output . . . . . . . . . . . History . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

21 . 23 . 23 . 23 . 25 . 25 . 26 . 26 . 28 . 28 . 30 . 31 . 31 . 31 . 31 . 31 . 31 . 32 . 34 . 34 . 35 . 37 . 37 . 37 . 38 . 38 . 38 . 38 . 38 . 39 . 39 . 39 . 40 . 40 . 41 . 42 . 43 . 44 . 45 . 45 . 46 . 47 . 47 . 48 . 49 .

ii


Scripting ds9 - DS9 . . . . . . . . . . . Scripting ds9 . . . . . . . . . . . . Synopsis . . . . . . . . . . . . . Contents . . . . . . . . . . . . . Command-line Scripting . . . . . . . . . Figure 1: Command line: x-ray data with contours . . . Figure 2: Command line: x-ray and optical data with contours XPA Scripting . . . . . . . . . . . Figure 3: XPA: x-ray data with contours . . . . . Figure 4: XPA: x-ray and optical data with contours . . SAMP: Simple Application Messaging Protocol . . . . History . . . . . . . . . . . . . Catalogs - DS9 . . . . . . . . . . . . Catalogs . . . . . . . . . . . . . Synopsis . . . . . . . . . . . . . Contents . . . . . . . . . . . . . Displaying a Catalog . . . . . . . . . . Figure 1: 2MASS Sources for the Antennae Galaxies . . Figure 2: Catalog Tool of 2MASS Sources . . . . . Selecting Sources with the Cursor . . . . . . . Displaying Multiple Catalogs . . . . . . . . Figure 3: CSC and 2MASS Sources for the Antennae Galaxies Clearing Catalog Sources . . . . . . . . . Sorting and Filtering . . . . . . . . . . Figure 4: 2MASS Sources Sorted by Decreasing Jmag . . Figure 5: Filtering 2MASS Sources: Jmag<14 . . . . Figure 6: Filtering 2MASS Sources: Jmag<14 or Jmag>16.5 . Specifying Symbols with Conditional Expressions . . . Figure 7: Symbol Editing: Jmag<14 Rule . . . . . Figure 8: Symbol Editing: Jmag<14 Sources Displayed . . Figure 9: Symbol Editing: Jmag>16.5 Sources Added . . Figure 10: Symbol Editing: Rule to Add a Label . . . Figure 11: Symbol Editing: Jmag Labels Displayed . . . Saving the Sources: Catalog Files and Region Files . . . Citing a Catalog in Publication . . . . . . . . History . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

50 . 50 . 50 . 50 . 50 . 51 . 52 . 54 . 54 . 56 . 58 . 58 . 59 . 59 . 59 . 59 . 60 . 60 . 62 . 63 . 63 . 63 . 65 . 65 . 65 . 67 . 68 . 69 . 69 . 70 . 71 . 72 . 72 . 74 . 74 . 74 .

iii



SAOImage DS9 Users Manual

The DS9 Users Manual leads the user step-by-step through many features of ds9, such as data binning and contours. For an in-depth description of all of ds9's capabilities, refer to the Reference Manual Introduction to the ds9 Interface Binning and Filtering FITS Event Files Contours Create a True Color Image in an RGB frame Scripting ds9 Catalogs If there are topics that you would like to see covered in the Users Manual, please email: saord @ cfa.harvard.edu.

1


Introduction to the ds9 Interface
Return to the DS9 Users Manual

Synopsis
This thread provides an overview of the key components of the ds9 graphical user interface (GUI). If you encounter any problems, please email saordá @á cfa.harvard.edu.

Contents
The ds9 Interface 1. Menu bar 2. Information panel 3. Panner 4. Magnifier 5. Buttons 6. Display frame 7. Colorbar Setting and Saving View Preferences History Images Figure 1: The ds9 GUI Figure 2: The ds9 GUI, vertical layout Figure 3: Menu bar Figure 4: Tearing off a Menu Figure 5: Information panel Figure 6: Panner Figure 7: Magnifier Figure 8: Buttons Figure 9: Tiled frame display Figure 10: Colorbar Figure 11: Preferences dialog box

The ds9 Interface
This thread uses Chandra data from an observation of the Trapezium Cluster (ObsID 1522). The default ds9 GUI is shown in Figure 1. The main components are numbered:

2


1. 2. 3. 4. 5. 6. 7.

Menu bar Information panel Panner Magnifier Buttons Display frame Colorbar

Figure 1: The ds9 GUI

3


The default setup is a "horizontal layout", with the information panel, panner, magnifier, and buttons displayed horizontally across the window. This may be changed to "vertical layout" in the View menu (Figure 2).

4


Figure 2: The ds9 GUI, vertical layout

Note that the colorbar remained horizontal at the bottom of the display frame. This may be changed with the "vertical colorbar" option in the "View" menu.

5


1. Menu bar
The menu bar provides access to all of ds9's capabilities. For a complete description of each menu, refer to the Menu bar section of the Reference Manual.

Figure 3: Menu bar

All ds9 menus can be "torn off" to be a separate window from the main GUI. To tear off a menu, select the dashed line, which is the first item of each menu (shown in Figure 4). The menu will become its own window.

Figure 4: Tearing off a Menu

6


7


2. Information panel
The information panel displays information about the data file and the values at the cursor position. In Figure 5, the object name has been loaded from the header of the data file. The image value and position (in WCS, physical, and image coordinates) are updated in real time as the cursor is moved. The fields of the information panel can be customized from the "View" menu. Any of the default entries can be removed, and additional fields can be added (e.g. detector coordinates, min/max data values).

Figure 5: Information panel

3. Panner
The panner allows the user to view areas of the frame which are outside of the current field of view. Although the display frame is filled by the data, the panner indicates that more of the image is available. Clicking and dragging the viewing bounding box in the panner - shown in blue in Figure 6 - will display a different portion of the image. The panner also contains axes to indicate the directions of North and East and the directions of the physical (x,y) data axes.

Figure 6: Panner

8


4. Magnifier
The magnifier displays a magnified view of the current cursor location. The magnifier cursor - the small square in the center of Figure 7 - outlines the size and orientation of one pixel, taking into account the current frame zoom and orientation.

Figure 7: Magnifier

5. Buttons
The button bar duplicates many of the options available from the menu bar. The buttons provide quick access to change the most frequently-used ds9 actions (e.g. changing the scale and color bar, blinking and tiling frames). When a category is chosen from the top row, the options within that category are displayed in the bottom row of buttons. In Figure 8, the color category is chosen and the bottom row shows the ten most-used colormap options (additional colormaps are available from the "Color" menu).

Figure 8: Buttons

6. Display frame
The display frame is the area of ds9 where the FITS image is shown. In Figure 1, a single frame is shown. Multiple frames can be opened in ds9 at the same time. In Figure 9, nine frames have been opened and set to "tile" display from the "frame" button. The current frame is indicated by a blue outline around it (second row, center frame). How the frames are tiled is set in the "Frame Á Frame Parameters Á Tile" menu; the default is to tile the frames in a grid.

9


Figure 9: Tiled frame display

10


If the display is set back to "single", then the current frame fills the display area. The other frames can be accessed via the "previous" and "next" options in the buttons bar (or from the "Frame" menu). The "blink" option may also be used with multiple frames. When blink is turned on, ds9 cycles through all the available frames. The blink interval is set in the "Frame Á Frame Parameters Á Blink Interval" menu.

7. Colorbar
The colorbar displays the colormap, bias, and contrast settings. The colormap correlates the colors used in the image with the pixel values in the data. To change the colormap, use the "Color" menu or button. The contrast and bias can be adjusted by right-clicking and dragging on the ds9 display. The "Color Á Colormap Parameters" dialog box can also be used to change contrast and bias.

Figure 10: Colorbar

Setting and Saving View Preferences
All of the view options described in this thread can be set and saved as a preference. Open the "Preferences" dialog box from the "Edit" menu and select the "View" tab, shown in Figure 11.

Figure 11: Preferences dialog box

11


The "Default" menus are used to set the defaults of the "View" menu and buttons. For instance, uncheck the "Panner" item under "Menu" and the panner won't be displayed when ds9 is launched. (Note that some options require ds9 to be restarted before they take effect.) After setting the desired preferences, select "Save". User preferences are stored in .ds9.prf. At startup, ds9 looks for the preferences file in the following directory order: ./, $HOME, /usr/local/lib, /opt/local/lib.

History
06á Julá 2009 Original version

Return to the DS9 Users Manual

12


Binning and Filtering FITS Event Files
Return to the DS9 Users Manual

Synopsis
When an x-ray event file is loaded, ds9 makes a virtual image for display by binning on one or more axes. This threads describes how to adjust the binning and buffer sizes. Interactive data filtering is described, as well as binning in three dimensions. Note that the terms "binning" and "blocking" are used interchangeably in this thread. They both refer to combining pixels in an image. If you encounter any problems, please email saordá @á cfa.harvard.edu.

Contents
Getting Started Buffer Size Binning Basics Changing the binning factor Binning different columns Data Cubes: Binning in three dimensions Filtering Data History Images Figure 1: Data loaded with default buffer and bin size Figure 2: The Bin menu Figure 3: Buffer size set to 128x128 Figure 4: Buffer size set to 4096x4096 Figure 5: Data binned by a factor of 4 Figure 6: The Binning Parameter dialog Figure 7: Image binned in detector coordinates Figure 8: Binning Parameter dialog for a data cube Figure 9: Data Cube dialog box Figure 10: Viewing a data cube Figure 11: Filtering data

13


Getting Started
This thread begins with Chandra data from an observation of the Antennae Galaxies (NGC 4038/NGC 4039, ObsID 315). Open the file in ds9:
unix% ds9 acisf00315N002_evt2.fits &

A small section of the data is visible when the file is loaded, as shown in Figure 1. The target of the observation is partially visible in the display frame.

Figure 1: Data loaded with default buffer and bin size

14


15


By default, the buffer size is set to 1024x1024 and the binning factor is set to 1. These values will be adjusted in the following sections to illustrate how to make more of the data visible. The "Bin" menu, shown in Figure 2, will be used to change the setting in the following examples. From top to bottom, this menu contains the bin function setting, blocking factor, buffer size options, and access to the binning parameters dialog box.

Figure 2: The Bin menu

16


Buffer Size
The buffer size determines the size of the image generated by ds9. By default, a full-resolution 1024x1024 image of the data is created. If your input data file has larger dimensions, it is clipped to 1024x1024 in ds9. The buffer settings range from 128x128 to 8192x1892. Setting the buffer to the smallest size, 128x128, illustrates how it works. The data was centered on the sources in ds9 before the buffer size was changed, creating Figure 3.

Figure 3: Buffer size set to 128x128

17


18


Setting the buffer to a large size, e.g. 4096x4096, produces Figure 4. The display frame is filled by the data, and the panner in the upper right indicates that more of the image is available. Clicking and dragging the viewing bounding box in the panner will display a different portion of the image.

Figure 4: Buffer size set to 4096x4096

19


20


Binning Basics
Changing the binning factor
While increasing the buffer size loads more of the file into ds9, binning the data makes more of it visible in the frame. Binning combines the specified number of pixels into one new pixel; the new pixel has a value equal to the sum of the original pixels. (Note that if the bin method is changed to "average", the pixel values are averaged instead of summed.) The binning can changed from the "Bin" menu or from the "Bin" item in the button bar. It's also possible to step through different binning values with the -/+ buttons or the "Block In"/"Block Out" menu items. In Figure 5, the buffer size is set to 1024x1024, but the block factor has been set to 4. A larger section of the data is visible in the frame.

Figure 5: Data binned by a factor of 4

21


22


Binning different columns
ds9 has the ability to display any of the other columns stored in the event file, although it is generally only meaningful to use the spatial vector columns. Begin by opening the "Bin Á Binning Parameters" dialog box, shown in Figure 6. The "Bin Columns" menus are used to select the columns to be binned. To create an image in detector coordinates, set the first to "detx" and the second to "dety"; the block is set to "2" for both. The "or center of data" box is checked so that the center of the data is recalculated for the new columns.

Figure 6: The Binning Parameter dialog

Click "Apply" and the ds9 frame is updated, as shown in Figure 7.

Figure 7: Image binned in detector coordinates

23


24


Alternatively, one can display an event file in specific coordinates when starting ds9 from the command line:
unix% ds9 "acisf00315N002_evt2.fits[bin=detx,dety]" &

Data Cubes: Binning in three dimensions
It is possible to add a third column to the binning, creating a 3-dimensional image also known as a "data cube". In this example, an (x,y,time) data cube is created of a Chandra observation of Jupiter (ObsID 1463). A cube may be created from any three columns that make sense in the analysis. For instance, you may want to create a PHA or energy axis to see how the spectral characteristics of a source change over time. The data file is loaded into a new frame in ds9 and the "Bin Á Binning Parameters" dialog box is opened again. The "time" column of the file is selected from the "Bin 3rd Column" menu. The limits of the data in that column are filled in automatically. The "depth" field determines how many intervals the column is divided into; a depth of 25 is used. The completed parameter box is shown in Figure 8.

Figure 8: Binning Parameter dialog for a data cube

After clicking "Apply", two things happen: the "Data Cube" dialog box (Figure 9) is launched and the frame is updated to show only the (x,y) image of the first time slice (Figure 10). (If the data cube dialog box doesn't launch, open it from the "Frame" menu.)

25


Figure 9: Data Cube dialog box

When "Play" is chosen, ds9 cycles through the bins of the time axis, essentially creating a movie of the (x,y) position of the object over time. The speed of the frame changes is controlled from the "Interval" menu of the dialog box. Any of the 25 intervals may be selected with the slider bar.

Figure 10: Viewing a data cube

26


27


The data cube can be saved as an MPEG movie from the "File Á Save Image..." menu. Select "MPEG-1 (Movie)" and click "OK"; after setting the filename, choose an MPEG Quality Factor. The Jupiter data was saved at a quality factor of 15: jupiter.mpg.

Filtering Data
The "Bin Filter" field in the "Binning Parameters" dialog box is used to apply filters to the data. A filter can be applied to any of the columns present in the input file. A colon is used to indicate a range of values. Filters can also use < (less than) or > (greater than). For instance, to include only the hard-band photons (2500-8000 eV):
energy=2500:8000

Clicking "Apply" updates the ds9 display and keeps the dialog open for adjusting the filters. Multiple filters may be specified, separated by commas:
energy=2500:8000, ccd_id=7

The resulting image is shown in Figure 11.

Figure 11: Filtering data

28


29


The filtered dataset can be saved as a FITS file for use in data analysis from the "File Á Save Frame as Fits..." menu.

History
26á Juná 2009 Original version

Return to the DS9 Users Manual

30


Contours
Return to the DS9 Users Manual

Synopsis
Contours are curves along which the pixels have a constant value. ds9 can create and display contours as an overlay on a data image. The contours can be copied between frames in the current session or saved to file for future use with ds9. If you encounter any problems, please email saordá @á cfa.harvard.edu.

Contents
Creating Contours on a Dataset Copying the Contours to Another Frame Saving the Contours Converting to Polygons and Saving History Images Figure 1: Contour Parameters dialog box Figure 2: X-ray data with contours Figure 3: SAO-DSS Server dialog box Figure 4: X-ray and optical data with contours

Creating Contours on a Dataset
This thread uses Chandra data from an observation of the galaxy cluster Abell 2142 (ObsID 5005). After loading the data into ds9 and setting the desired scale, click on the "Contours" item in the "Analysis" menu to turn on contour display. Open the "Contour Parameters" window from "Analysis Á Contours Parameters". There are two sliding scales which are used to set the number and smoothness of the contours and fields for setting the range of values to use.

Figure 1: Contour Parameters dialog box

31


Typically, you will want to generate between 1 and 10 contours; larger numbers will take longer to generate and display. A smoothness level of 1 will evaluate the contour at each image pixel, while a level of 2 will evaluate the contour at every other pixel, and so on. A larger smoothing will generate contours more quickly, but less detail will be available. By default, the range of the data scale is filled in as the limits. Under the "Method" menu, there are two choices: 1. block (the default) - blocks down the image by the smoothness factor before contours are calculated. The larger the smoothness, the faster the result. 2. smooth - smooths the image before calculating contours. The larger the smoothness, the slower the result. In this example, the number of levels is set to 6 and the smoothing is set to 5. The contours will be generated over the limit 1 to 100. The default method (block) is used. After clicking the "Generate" button, the list of contours is calculated and displayed in the "Levels" portion of the window. Click "Apply" and the ds9 display is updated with the new contour levels, as shown in Figure 2.

Figure 2: X-ray data with contours

32


33


The contour parameters can be adjusted until the desired result is achieved. Be sure to click "Generate" whenever an adjustment is made so that the levels are recalculated.

Copying the Contours to Another Frame
In this section, we take the X-ray contours just generated and display them on an optional image from the Digital Sky Survey (DSS). From the "Analysis Á Image Servers" menu, select one of the DSS server options (e.g. "SAO-DSS"). The server dialog box allows you to retrieve an optical image of the field of your observation and load it into a new frame. The default retrieval image size and (RA,Dec) is equal to the size and center of the field currently displayed. Here the width and height have been set to 40, but the (RA,Dec) determined by ds9 are used.

Figure 3: SAO-DSS Server dialog box

Click on "Retrieve" and the data is loaded into a new ds9 frame. To copy the x-ray contours: 1. Select the frame with the X-ray data in it. 2. Use "Frame Á Match Frames Á WCS" to align the two images. 3. To copy the contours, open the "Contour Parameters" dialog again and select "Copy Contours" from the "File" menu. Leave the window open, as it is needed in a future step. 4. Select the frame with the optical data in it. 5. Using the "File" menu of the "Contour Parameters" dialog, select "Paste Contours".

34


6. Adjust the parameters (if desired) in the small dialog box that is displayed, then click "OK". The optical image now has the x-ray contours overlaid. Since the WCS is the same, correlation between x-ray and optical features may be seen.

Figure 4: X-ray and optical data with contours

35


36


To delete contours which have been pasted into a frame, select "Clear" from the "File" menu of the "Contour Parameters" dialog.

Saving the Contours
To save the contours to a text file, choose "Save Contours" from the "File" menu of the "Contour Parameters" dialog. The contours are saved in a text file which can be loaded back into ds9 with the "Load Contours" menu item. The contours generated in this thread have been saved as ds9.con.

Converting to Polygons and Saving
The contours can be converted to ds9 polygon regions for use in filtering data. Converting to polygons also allows you to select and/or delete specific contours. Note that the contours cannot be saved in ds9 format after converting. If you wish to save the contours, do so before continuing. To convert the contours, select "Convert to Polygons" from the "File" menu of the "Contour Parameters" dialog. The contours are now defined as ds9 polygons, e.g.
polygon(3535.2112,4184.5,3540.5,4179.1154,3548.5,4176.8219,3555.9012,4184.5,3548.5,4191.9558,3540.5,4190.3926)

The polygon-shaped contours can be saved as a ds9 region file from the "Region Save Á Regions" menu. The region file for these contours has been saved as a2142.reg.

History
24á Juná 2009 Original version

Return to the DS9 Users Manual

37


Create a True Color Image in an RGB frame
Return to the DS9 Users Manual

Synopsis
Most astronomical images map color to intensity level, e.g. lighter tones may correspond to a brighter intensity level in a greyscale image. An alternative way of presenting data is via an image that correllates color and energy. ds9 has the capability to create an RGB image and interactively adjust many of its parameters to achieve optimal display results. If you encounter any problems, please email saordá @á cfa.harvard.edu.

Contents
Creating an RGB Frame A. From the command line B. From the ds9 GUI Apply Energy Filters Smoothing the Data (optional) Adjusting the Scale Parameters Adding a Coordinate Grid Saving the Output History Images Figure 1: RGB window Figure 2: Lock menu in the RGB window Figure 3: RGB frame with three files loaded Figure 4: Energy-filtered RGB data Figure 5: Data smoothed with a Gaussian of radius three Figure 6: The adjusted pixel distribution for scaling Figure 7: Coordinate Grid parameters dialog box Figure 8: Final three-color image with coordinate grid overlaid

Creating an RGB Frame
To use the three-color capabilities of ds9, the data must be loaded into a special RGB frame. This frame will contain all three files, stacked together in separate layers.

38


This thread uses Chandra data from an observation of Cas A (ObsID 198); the level=2 event file is named "casa.fits". The same file is loaded into each layer of the RGB frame; different energy filters will be applied to the layers in a later step. There are two options for creating the RGB frame:

A. From the command line
The command-line syntax can be used to create the RGB frame and load the three files into the red, green, and blue layers:
unix% ds9 -rgb -red casa.fits \ -green casa.fits \ -blue casa.fits &

ds9 will open with the three files in one frame. The RGB window (Figure 1) should open as well. If it doesn't, open it from the "Frame Á RGB..." menu.

B. From the ds9 GUI
To load the files from the ds9 GUI: 1. Launch ds9 2. Choose "New Frame RGB" from the "Frame" menu. When the new frame is created, the RGB window (Figure 1) should open as well. If it doesn't, open it from the "Frame Á RGB..." menu. 3. Make sure the "Red" band is selected in the "Current" column of the RGB window, then choose "File Á Open..." in the main ds9 window and select the red file. 4. Change the current band to "Green" in the RGB window and open the green file. 5. Change the current band to "Blue" in the RGB window and open the blue file.

Figure 1: RGB window

39


Each frame of the RGB image may have different binning, scaling, smoothing, and colorbars applied to it. You can "lock" the frames together, so that the setting is applied to all three frames at once. This is done with the Lock menu in the RGB window (Figure 2); all four options are checked in this thread.

Figure 2: Lock menu in the RGB window

Use the binning and zoom options in ds9 to adjust the image so that the full region of interest is visible. Figure 3 uses binning=2 and zoom=1. The "Scale" is set to "log: minmax"

Figure 3: RGB frame with three files loaded

40


Apply Energy Filters
The following energy bands are used for the RGB layers: red (soft band): 200-1500 eV green (medium band): 1500-2500 eV blue (hard band): 2500-8000 eV

41


The values are just guidelines and may need to be adjusted for your analysis. To filter the data, first select the Red frame from the RGB window. Open the Bin Á Binning Parameters dialog box and type "energy=200:1500" in the Bin Filter field. Choose "Apply" and the ds9 display will be updated to reflect the energy filter. Without closing the Binning Parameters box, select the Green frame. Type "energy=1500:2500" in the Bin Filter field and choose "Apply" again. Repeat these two steps for the Blue layer, using the filter "energy=2500:8000". The colors in the image, as seen in Figure 4, are correlated to the energy of the data.

Figure 4: Energy-filtered RGB data

42


Smoothing the Data (optional)
Smoothing can help bring out finer features in the data by removing statistical noise. It is an optional step; experiment with smoothing to see if it improves the appearance of your data. The smoothing capability in ds9 lets you interactively smooth the data. Note that for quantitative data analysis, smoothing should be done with the appropriate data analysis software; ds9 does a nice job for publication purposes.

43


Choose "Smooth" from the "Analysis" menu and the ds9 display is updated with the results of smoothing. The "Smooth" option can be toggled on and off during your ds9 session. Open the "Smoothing Parameters..." dialog box from the same menu to adjust the function and kernel radius of the smoothing. This data were smoothed with a Gaussian function with radius of two. The results are shown in Figure 5.

Figure 5: Data smoothed with a Gaussian of radius three

44


Adjusting the Scale Parameters
This data is being displayed with a "log: minmax" scale. That means that ds9 stretches the scale to encompass the range of pixel values in the file. Adjusting the minimum and maximum scale values sets a threshold for the background data and brings out features. To change the minimum and maximum values, open the "Scale Á Scale Parameters" dialog box. The pixel distribution shown is for the band selected as "Current" in the RGB window; when the a different band is selected, the histogram of pixel values is updated to match. To adjust the values, use the cursor to grab the red (minimum) or green (maximum) vertical lines on the plot and drag them to the desired location. You can type a value in to the "Low" or "High" field and hit "Apply" to set the limits. A basic guideline for setting the low value is to minimize the contribution of the background. That is, adjust the minimum of each band until the background of the image is flat (i.e. solid black). For the maximum value, bringing it in to the last data point in the pixel distribution is usually sufficient. For ObsID 198 with the smoothing applied, the following limits were chosen (listed as "low:high" pairs): Red - 0.4 : 20 Green - 0.3 : 35 Blue - 0.1 : 10 Figure 6 shows the image with the new pixel value limits set.

Figure 6: The adjusted pixel distribution for scaling

45


Adding a Coordinate Grid
To add a coordinate grid to the image, choose the "Coordinate Grid" option from the "Analysis" menu. Then choose "Coordinate Grid Parameters" from the same menu to open the preferences dialog (Figure 7).

46


Figure 7: Coordinate Grid parameters dialog box

From the preferences box, you can change the color, font, line style (solid or dash), and line thickness for all elements of the grid. The font style, size, and color can be edited, and you can add titles. It is also possible to turn off the display of individual items via the "View" menu. In Figure 8, we have turned off the grid lines and border. The axes have been changed to "Exterior Axes" (from the "Type" menu).

Figure 8: Final three-color image with coordinate grid overlaid

47


Saving the Output
Once you are happy with your true color image, there are a number of output options in ds9. Image formats: from the "File Á Save Image As..." menu, you can choose JPG, PNG, or TIFF file formats.

48


Postscript: to create a postscript file, go to "File Á Print..." and select "Print To: File". Currently it is not possible to save the state of the ds9 imager, meaning that you cannot save the composite RGB frame and reopen later for further analysis.

History
04á Juná 2009 Original version

Return to the DS9 Users Manual

49


Scripting ds9
Return to the DS9 Users Manual

Synopsis
Scripting with ds9 can be done in several ways: by invoking the GUI with a number of command-line options or via the XPA messaging system. A third option, Simple Application Messaging Protocol (SAMP), is introduced but not included in the examples. To illustrate how to script ds9, we repeat the contours example with both methods,. The examples use Chandra data from an observation of the galaxy cluster Abell 2142 (ObsID 5005). If you encounter any problems, please email saordá @á cfa.harvard.edu.

Contents
Command-line Scripting XPA Scripting SAMP: Simple Application Messaging Protocol History Images Figure 1: Command line: x-ray data with contours Figure 2: Command line: x-ray and optical data with contours Figure 3: XPA: x-ray data with contours Figure 4: XPA: x-ray and optical data with contours

Command-line Scripting
The ds9 Reference Manual has an extensive list of the available command line options. The most important thing to note is that the commands are executed one at a time in the order they are listed. To create contours on a data image:
unix% ds9 acisf05005N002_evt2.fits -bin about 3800 3800 -bin factor 2 \ -scale log -cmap b \ -contour yes -contour limits 1 100 \ -contour smooth 5 -contour nlevels 6 -contour save ds9.con &

This command line produces Figure 1.

50


Figure 1: Command line: x-ray data with contours

The options direct ds9 to: 1. 2. 3. 4. -bin about 3800 3800 : center the image display at (x,y)=(3800,3800) -bin factor 2 : bin the data by a factor of 2 -scale log : set the display to log scale -cmap b : use the "b" colormap

51


5. 6. 7. 8. 9.

-contour -contour -contour -contour -contour

yes : display contours limits 1 100 : set the minimum and maximum contour limits smooth 5 : set contour smoothness to "5" nlevels 6 : create six contour levels save ds9.com : save the contours to the file "ds9.con"

If you wish to add options to the command line after it has been processed, the whole command must be run again from the beginning. It is, however, possible to interact with the ds9 GUI that has been created. For instance, instead of including the "-bin about 3800 3800" modifier, the image could be recentered in ds9 interactively. The following command line builds on the previous example by retrieving a DSS image and copying the contours to the new frame:
unix% ds9 acisf05005N002_evt2.fits -bin about 3800 3800 -bin factor 2 \ -scale log -cmap b \ -contour yes -contour limits 1 100 \ -contour smooth 5 -contour nlevels 6 -contour copy \ -dsssao A2142 -cmap grey -contour paste \ -frame first -match frames wcs &

The resulting image is shown in Figure 2.

Figure 2: Command line: x-ray and optical data with contours

52


The options which have been added from the previous command line are: 1. -contour copy : copy the x-ray contours 2. -dsssao A2142 : retrieve a DSS image of A2142 from the DSS-SAO server (there are also a "dsseso" and "dssstsci" options) 3. -cmap grey : use the "grey" colormap in the DSS frame 4. -contour paste : paste the x-ray contours onto the optical data

53


5. -frame first : select the first ds9 frame 6. -match frames wcs : match the WCS of the DSS frame to the current (x-ray) frame At this point, we can end the ds9 session or modify the display interactively via the ds9 GUI.

XPA Scripting
X Public Access (XPA) is a messaging system which provides communication between Unix programs through a set of access points. The two most common actions are retrieving information (xpaget) and issuing commands (xpaset). For more information, see the XPA Messaging System page and the XPA Access Points section of the ds9 manual. XPA commands may be issued one at a time from the terminal or collected in a script to run in batch mode. Unlike the command line syntax, there is no predetermined stopping point - commands may be sent to ds9 as long as the GUI is open. First, open ds9 with the data file:
unix% ds9 acisf05005N002_evt2.fits &

The xpans name server is used to manage the names and ports of XPA access points. Use "xpaget xpans" to see the list of available access points:
unix% xpaget xpans DS9 ds9 gs /tmp/.xpa/DS9_ds9.22972 username

Now that ds9 is running and linked to an XPA server, we can use xpaset to modify the display and add contours. (Refer to the XPA documentation for details on xpaset syntax.)
unix% unix% unix% unix% unix% unix% unix% unix% unix% xpaset xpaset xpaset xpaset xpaset xpaset xpaset xpaset xpaset -p -p -p -p -p -p -p -p -p ds9 ds9 ds9 ds9 ds9 ds9 ds9 ds9 ds9 bin about 3800 3800 bin factor 2 scale log cmap b contour yes contour limits 1 100 contour smooth 5 contour nlevels 6 contour save xpa.con

This command line produces Figure 3.

Figure 3: XPA: x-ray data with contours

54


The options direct ds9 to: 1. 2. 3. 4. 5. xpaset xpaset xpaset xpaset xpaset -p -p -p -p -p bin about 3800 3800 : center the image display at (x,y)=(3800,3800) bin factor 2 : bin the data by a factor of 2 scale log : set the display to log scale cmap b : use the "b" colormap contour yes : display contours

55


6. 7. 8. 9.

xpaset xpaset xpaset xpaset

-p -p -p -p

contour contour contour contour

limits 1 100 : set the minimum and maximum contour limits smooth 5 : set contour smoothness to "5" nlevels 6 : create six contour levels save xpa.com : save the contours to the file "xpa.con"

As long as the ds9 GUI remains open, we can continue to modify the display. Here we build on the previous example by retrieving a DSS image and copying the contours to the new frame:
unix% unix% unix% unix% unix% unix% xpaset xpaset xpaset xpaset xpaset xpaset -p -p -p -p -p -p ds9 ds9 ds9 ds9 ds9 ds9 contour copy dsssao A2142 cmap grey contour paste frame first match frames wcs

The resulting image is shown in Figure 2.

Figure 4: XPA: x-ray and optical data with contours

56


The options which have been added from the previous command line are: 1. xpaset -p contour copy : copy the x-ray contours 2. xpaset -p dsssao A2142 : retrieve a DSS image of A2142 from the DSS-SAO server (there are also a "dsseso" and "dssstsci" options) 3. xpaset -p cmap grey : use the "grey" colormap in the DSS frame 4. xpaset -p contour paste : paste the x-ray contours onto the optical data

57


5. xpaset -p frame first : select the first ds9 frame 6. xpaset -p match frames wcs : match the WCS of the DSS frame to the current (x-ray) frame At this point, we can end the ds9 session, issue further XPA commands, or modify the display interactively via the ds9 GUI.

SAMP: Simple Application Messaging Protocol
A third method of scripting ds9 is via SAMP, a messaging protocol that enables astronomy software tools to interoperate and communicate. SAMP is also used by such applications as TOPCAT, an interactive graphical viewer and editor for tabular data and Aladin, an interactive software sky atlas. Information on the ds9 SAMP implementation is available in the ds9 Reference Manual.

History
21á Sepá 2009 Original version

Return to the DS9 Users Manual

58


Catalogs
Return to the DS9 Users Manual

Synopsis
DS9 provides full support for loading, displaying, filtering, and saving catalogs. DS9 allows you to overlay symbols from multiple catalogs on the current image and to create expressions to style the source symbols based on catalog properties. If you encounter any problems, please email saordá @á cfa.harvard.edu.

Contents
Displaying a Catalog Selecting Sources with the Cursor Displaying Multiple Catalogs Clearing Catalog Sources Sorting and Filtering Specifying Symbols with Conditional Expressions Saving the Sources: Catalog Files and Region Files Citing a Catalog in Publication History Images Figure 1: 2MASS Sources for the Antennae Galaxies Figure 2: Catalog Tool of 2MASS Sources Figure 3: CSC and 2MASS Sources for the Antennae Galaxies Figure 4: 2MASS Sources Sorted by Decreasing Jmag Figure 5: Filtering 2MASS Sources: Jmag<14 Figure 6: Filtering 2MASS Sources: Jmag<14 or Jmag>16.5 Figure 7: Symbol Editing: Jmag<14 Rule Figure 8: Symbol Editing: Jmag<14 Sources Displayed Figure 9: Symbol Editing: Jmag>16.5 Sources Added Figure 10: Symbol Editing: Rule to Add a Label Figure 11: Symbol Editing: Jmag Labels Displayed

59


Displaying a Catalog
This thread uses an optical image of the Antennae Galaxies (NGC 4038/NGC 4039) from the Digital Sky Survey (DSS). It was retrieved via the "Analysis Á Image Servers" menu in ds9. A number of the most popular catalogs are listed by wavelength in the "Analysis Á Catalogs" menu. More options can be accessed via the "Search for Catalogs" option in that menu. First we overlay sources from 2MASS by choosing "Analysis Á Catalogs Á Infrared Á 2MASS point sources". The source matches are displayed on the ds9 display (Figure 1) and listed in a "Catalog Tool" window (Figure 2).

Figure 1: 2MASS Sources for the Antennae Galaxies

60


A set area centered on the field of view is used for the first catalog search. The center and size of the search area may be adjusted in the Catalog Tool by setting the RA, Dec, height, and width fields. The "Coordinate" and "Size" menus may be used to set the units for those values (degrees/sexagesimal and degrees/arcmin/arcsec, respectively). After changing the values, click the "Retrieve" button to update the Catalog Tool.

61


Figure 2: Catalog Tool of 2MASS Sources

62


Note that ds9 attempts to select the correct (RA,Dec) columns from the catalog data file in order to display the sources. In some cases, the user will have to explicitly set the column names by using the drop-down menus in the Catalog Tool. In this example, ds9 correctly chose "_RAJ2000" and "_DEJ2000".

Selecting Sources with the Cursor
From the "Edit" menu in ds9, choose the "Catalog" cursor type. Clicking on a source in the ds9 display highlights the corresponding row in the Catalog Tool. Multiple sources may be selected by holding down the SHIFT key while clicking them. Similarly, highlighting a row in the Catalog Tool will blink the source region in ds9. If the "Pan to" option in the Catalog Tool "Preferences" menu is checked, the ds9 display also centers on the chosen source. Mutiple rows may be selected by holding down the SHIFT or CTRL key while selecting them.

Displaying Multiple Catalogs
More than one catalog can be displayed in the same frame. By default, the sources are displayed as green circle points. The color and shape can be changed in the "Symbol" menu of the Catalog Tool to distinguish between the different catalogs. In Figure 3, the Chandra Source Catalog has been added to the display (Analysis Á Catalogs Á High Energy Á Chandra Source). The symbols for the CSC sources are set to red diamonds.

Figure 3: CSC and 2MASS Sources for the Antennae Galaxies

63


To toggle the display of each catalog, use the "Show Regions" option in the Catalog Tool "Preferences" menu.

64


Clearing Catalog Sources
Simply closing the Catalog Tool will not remove the sources from the display. It is necessary to choose "Clear" from the corresponding Catalog Tool. To remove all the sources from the display, use "Analysis Á Catalogs Á Clear All". For the rest of this thread, only the 2MASS sources will be used.

Sorting and Filtering
The source listing is sorted on position by default. A different column for sorting may be selected from the "Sort" menu in the Catalog Tool. Related checkboxes determine whether the results are listed in increasing or decreasing order. The Catalog Tool in Figure 4 is sorted on the "Jmag" column in decreasing order.

Figure 4: 2MASS Sources Sorted by Decreasing Jmag

65


66


The "Filter" field in the Catalog Tool is used to filter out specific rows from the source matches. A filter is conditional expression that is evaluated for each row of the catalog. The column name must be referenced with a dollar sign in the expression, e.g. "$_RAJ2000". To select the sources with low Jmag values, the filter "$Jmag<14" is used. Click the "Filter" button to update the Catalog Tool and the ds9 display. The results are shown in Figure 5.

Figure 5: Filtering 2MASS Sources: Jmag<14

67


TCL expression syntax can be used to construct more complex filters. The filter "$Jmag<14 || $Jmag>16.5" uses the logical "OR" syntax ("||") to select any source with Jmag less than 14 or greater than 16.5, as shown in Figure 6.

Figure 6: Filtering 2MASS Sources: Jmag<14 or Jmag>16.5

The uniformity of the symbols doesn't distinguish between the low-Jmag sources and the high-Jmag sources. The advanced symbol editing in the next section improves on this display.

68


Before continuing the thread, clear the filter in the Catalog Tool so that all the sources are displayed.

Specifying Symbols with Conditional Expressions
The advanced symbol editing in the Catalog Tool allows you to specify the shape, size, color, and text of each symbol based on catalog column values. Open the "Symbol Editor" from the "Symbol Á Advanced..." menu in the Catalog Tool. A conditional statement, written in the TCL expression syntax, is entered in the "If" field. The styles that should be applied are set by the other fields (shape, color, text, etc.). First, define a rule that sets the sources with Jmag<14 to be red boxcircle points. The completed form is shown in Figure 7. After clicking the "Apply" button, the ds9 display is updated (Figure 8).

Figure 7: Symbol Editing: Jmag<14 Rule

69


Figure 8: Symbol Editing: Jmag<14 Sources Displayed

The "Add" button in the Symbol Editor is used to create a new, empty form. The second rule is defined such that sources with Jmag>16.5 will be cyan diamonds. After clicking the "Apply" button again, the ds9 display is as shown in Figure 9.

70


Figure 9: Symbol Editing: Jmag>16.5 Sources Added

To edit an existing rule, highlight the rule in the Symbol Editor and adjust the parameters. In Figure 10, both rules have been updated so that the Text field is set to "$Jmag". This displays the Jmag column value next to the symbol (Figure 11).

71


Figure 10: Symbol Editing: Rule to Add a Label

Figure 11: Symbol Editing: Jmag Labels Displayed

72


The ds9 Reference Manual has further examples of symbol expressions. The set of rules may be saved from the "File" menu in the Symbol Editor. The output for these rules looks like:
condition --------$Jmag<14 $Jmag>16.5 shape color --------boxcircle point diamond point text ---red cyan size ---$Jmag $Jmag size2 ----units ----angle ----physical physical

73


The file can be loaded into a later ds9 session by opening the Symbol Editor and using the "File Á Load" menu item. Note that the column names in the symbol rules may have to be updated in order to use them with a different catalog.

Saving the Sources: Catalog Files and Region Files
Saving a Catalog File The contents of the Catalog Tool may be saved from the "File Á Save" menu. If any filters are applied, the filtered output is saved in the catalog file. ds9 supports three catalog formats: VOTable, Starbase, and tab-separated file. If the catalog file will be loaded back into ds9 in the future, any of the three formats may be chosen. Saving the Sources in a Region File The sources may also be converted to a ds9 region file for use in data analysis, e.g. spectra extraction or calculating sources counts. Select "Copy to Regions" from the Catalog Tool "File" menu. Once the sources are converted to regions, individual ones may be selected and edited or deleted, if desired. Save the regions from the "Region Á Save Regions..." menu.

Citing a Catalog in Publication
If you wish to use the source information in a publication, refer to the "Acknowledgment" item under the "File" menu in the Catalog Tool. For instance, the 2MASS acknowledgment reads:
Acknowledgments for CDS This research has made use of the VizieR catalogue access tool, CDS, Strasbourg, France. VizieR is a joint effort of CDS (Centre de Donnö©es astronomiques de Strasbourg) and ESA-ESRIN (Information Systems Division).

History
08á Janá 2010 Original version

Return to the DS9 Users Manual

74