Using SAOImage ds9

Getting Started

Sample ObsID used: 1712 (ACIS-S, 3C 273)

File types needed: evt2; asol1

The preferences set in ds9 are stored in a file called $HOME/.ds9.prf (see the section on Command Line Arguments and Preferences). It is possible that a .ds9.prf file created for a different version of ds9 may cause problems with the ds9 packaged in CIAO. To avoid a possible conflict, delete or rename this file before using ds9 in CIAO.

unix% which ds9
/opt/local/bin/ds9


unix% ciao
CIAO configuration is complete... 
 CIAO version     :  CIAO 3.4 Sunday, November 19, 2006
 Proposal Toolkit version :  Cycle 9 Sunday, November 19, 2006
 bin dir          :  /soft/ciao/bin


unix% which ds9
/soft/ciao/ots/saord/ds9

unix% which xpaget
/opt/local/bin/xpaget


unix% ciao
CIAO configuration is complete... 
 CIAO version     :  CIAO 3.4 Sunday, November 19, 2006
 Proposal Toolkit version :  Cycle 9 Sunday, November 19, 2006
 bin dir          :  /soft/ciao/bin


unix% which xpaget
/soft/ciao/bin/xpaget

Coordinate Definitions: Image, Physical/Sky, Celestial, and WCS

There are a few terms needed to discuss coordinate systems:

• Image: image coordinates specify a location in an image. The lower, left pixel of the array will have the image coordinates (1,1). Coordinates increase to the right in x and up in y. Note that the lower left corner of the array will have coordinates (0.5,0.5).

• Physical/Sky: "sky" is shorthand for (x,y) coordinates, the system used most commonly in Chandra data analysis. Physical coordinates are the generalized system used by ds9. The sky coordinates of an event are defined as the point where an event crosses the imaginary tangent plane for a given pointing of the telescope's mirrors. This is calculated (by the CIAO tools reproject_events and acis_process_events / hrc_process_events) from knowledge of the location of the event on the detector, the location of the detector in the observatory, and the pointing of the telescope. For Chandra data, the range of sky coordinates is 0.5:8192.5 for ACIS, 0.5:32768.5 for HRC-I, and 0.5:65536.5 for HRC-S.

  When saving regions in ds9, use "Ciao" formatted regions to ensure total compatibility with the CIAO tools. "Ciao" format regions are saved in physical coordinates by default. The CIAO and ds9 region formats section of the Using CIAO Regions thread has a discussion on the ASCII region types available for use. If necessary, it is possible to convert region formats/coordinate systems by loading one type (e.g. ds9 format in celestial coordinates) and saving it in a different format/coordinate system (e.g. CIAO format in physical coordinates).

• Celestial: the celestial coordinate system is the standard method of measuring positions in the sky. The transformations from sky (x,y) to celestial (RA, Dec) are described at the end of the event file "columns" listing:

  unix% dmlist acisf01712N002_evt2.fits cols
  ...cut...
  
  8:    EQPOS(RA ) = (+187.2761) +TAN[(-0.000136667)* (sky(x)-(+4096.50))]
             (DEC)   (+2.0539  )      (+0.000136667)  (   (y) (+4096.50)) 
  

  The two systems are related by the aimpoint of the observation. When events are projected onto the celestial sphere, RA increases to the left (hence the minus sign in the definition) and Dec increases upward. In this example, the celestial coordinates of the reference pixel in degrees (J2000) are (187.2761,2.0539).

  Although CIAO regions may be saved in celestial coordinates, only sexagesimal coordinates are currently supported (e.g. circle(17:46:14.065,-28:51:39,1.0')). Since some tools are not yet able to transform from celestial to sky coordinates, we recommend using the physical format.

• WCS: the World Coordinate System (WCS) is a generalized name for the celestial coordinate system. The default celestial coordinate system in CIAO and ds9 is the J2000 system. A complete description of the WCS standard is given on the WCSTools home page.

  As described above, the (x,y) coordinate system is related to the celestial coordinate system by specifying the (RA, Dec) of a reference pixel in the file's header. It is sometimes necessary to edit these header keywords to improve upon Chandra's pointing accuracy. For more information, see the Aspect caveats and the Improving the Astrometry of your Data: Correct for a Known Processing Offset thread.

For a detailed discussion of the relationships between Chandra instrument coordinate systems, see the Chandra Coordinate Systems: Imaging document (PS, 25pp).

Command Line Arguments and Preferences

Command line arguments may be used to perform a task when opening the application. For example, to specify log scaling when loading an event file:

unix% ds9 acisf01712N002_evt2.fits -log

A more involved example overlays a region onto the file, sends the image to the printer, and then closes ds9:

unix% ds9 acisf01712N002_evt2.fits -region sources.reg -print -exit

A short list of the available command line arguments can be found by typing "ds9 --help" in a term window. Detailed descriptions of the arguments are available from the Command Line Options section of the ds9 manual.

Preferences are user-defined default settings accessed from the "Edit -> Preferences" menu. Dozens of settings are available for modification, such as:

• color scale
• display buffer size
• window layout
• region shape
• analysis file (see the Using Analysis Scripts section)

Most of the options are self-explanatory, but there is more information on each in the Preferences section of the ds9 manual. Note that under the "Information Panel" is an option to display "Detector" coordinates. This does not refer to the Chandra detector coordinates (i.e. det or tdet).

If these settings are changed and "Save Preferences" is chosen, the preferences are written to /home/username/.ds9.prf. The next time ds9 is started, this file is read and the preferences are used.

Important: as mentioned before, the preference files are generally not backward-compatible. This means a .ds9.prf created by a newer version of ds9 may react badly with the ds9 packaged in CIAO. Please reference the Preferences section of the ds9 manual for information on avoiding this problem when supporting multiple versions of ds9.

Displaying an Event File in Different Coordinates

The most direct way of checking quality and content of an event file is to view it in ds9:

unix% ds9 acisf01712N002_evt2.fits &

The imager will display a 1k x 1k array of pixels by default (this may be changed in the preferences). The typical Chandra image will need to be binned to see the entire field of view. Using the "Bin" button or menu, try a binning factor of 16. If the Scale is also set to "Log", the image should look like Figure 1 .

ds9 also has the ability to display any of the other columns stored in the event file, although it is only meaningful to use one of the spatial vector columns. In order to display the file in other coordinates, use the "Bin -> Binning Parameters" menu to select the two columns to display. To create an image in detector coordinates (detx,dety), select them from the "Bin Columns" menus. Change "Bin Factor" to 4, select the "or center of data" button, and click "Apply". Figure 2  shows the results.

Displaying the event file in detector coordinates reveals details about how the observation was done. Bad columns (removed in the level=2 event file, so not visible here) are displayed as dark lines and point sources appear as limb-brightened squares due to the telescope dither. This demonstrates the value of dithering the telescope; instrumental artifacts are blurred, providing more regular coverage across the field.

Alternatively, one can display an event file in specific coordinates when calling ds9 from the command line. The syntax is similar to the CIAO binning syntax:

unix% ds9 "acisf01712N002_evt2.fits[bin=detx,dety]" &

The file is loaded into ds9 and displayed in detector coordinates.

Using Multiple Frames

ds9 allows the simultaneous viewing of multiple images through the use of frames, which are memory areas used to store images for viewing.

There are two ways to create multiple frames:

1. Specify all the filenames when starting ds9:

   unix% ds9 acisf01712N002_evt2.fits -cmap b -log ../../315/primary/acisf00315N002_evt2.fits \
         -cmap b -log /data/1838/primary/acisf01838N001_evt2.fits -cmap b -log &
   

   Notice that the pathnames may be relative or absolute. Issuing this command created Figure 3 .

2. Use the "Frame -> New Frame" menu option. This process can be repeated to create as many frames as desired. The event files are then loaded into the frames from the "File -> Open..." dialog box.

Displaying multiple images can be helpful when trying to compare them. Images may be displayed side-by-side using the "Tile Frames" option or sequentially using the "Blink Frames" option, both found in the "Frame" menu. If the WCS info is defined for each system (or if they have the same image pixel scale), use "Frame -> Match Frames" to align them for comparison.

The Analysis Menu

The "Analysis" menu has several features which are useful in the analysis of Chandra data. The following examples illustrate how to apply contours, retrieve Digital Sky Survey data, perform comparative analysis of the two datasets, and define custom analysis functions. There is information on each of the commands used in these examples in the ds9 manual:

• Contours
• Digital Sky Survey
• Crosshair Mode
• Analysis

Each of the following examples assumes that an event file has been loaded into ds9:

unix% ds9 acisf01712N002_evt2.fits -log &

XPA: Public Access to Data and Algorithms

X Public Access (XPA) is a messaging system which provides communication between Unix programs. XPA allows users to interact with ds9 and CIAO through a set of access points; access points are simply keywords that allow command-line interaction with the application. 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. As a general rule, functions which are available in the ds9 GUI can be accessed through XPA.

For comparison, consider getting the crosshair coordinates from ds9 and inputting them to dmcoords (e.g. to find the off-axis angle). First, load the event file:

unix% ds9 acisf01712N002_evt2.fits &

and mark the desired point with the crosshairs. Recall that the "Edit" menu is used to change the cursor. Using the csh (or tcsh) shell, the analysis could be done as follows:

unix% xpaget ds9 crosshair physical
 4101.375 4066.5 
unix% set x = `xpaget ds9 crosshair physical | cut -d" " -f2`
unix% set y = `xpaget ds9 crosshair physical | cut -d" " -f3`
unix% dmcoords infile=acisf01712N002_evt2.fits asolfile=pcadf077378077N002_asol1.fits opt=sky x=$x y=$y

The set commands are added to show the utility of xpaget; the values could simply be given directly to dmcoords as "x=4101.375 y=4066.5". The results are stored in the dmcoords parameter file:

unix% plist dmcoords

Parameters for /home/username/cxcds_param/dmcoords.par


        infile = acisf01712N002_evt2.fits Input dataset/block specification
#
# Position of photon in different coord systems
#
       chip_id = 7                Chip ID number
         chipx = 189.0798128897544 Chip X [pixel]
         chipy = 389.9706842765111 Chip Y [pixel]
         tdetx = 4106.079812889754 TDETX [pixel]
         tdety = 2091.970684276511 TDETY [pixel]
          detx = 4067.131529566298 FPC X [pixel]
          dety = 4104.326785380114 FPC Y [pixel]
             x = 4101.375         Sky X [pixel]
             y = 4066.5           Sky Y [pixel]
      logicalx = 4101.375         X coordinate in binned image [pixel]
      logicaly = 4066.5           Y coordinate in binned image [pixel]
            ra = 12:29:06.106     RA [deg or hh:mm:ss]
           dec = +02:02:59.16     Dec [deg or dd:mm:ss]
         theta = 0.24922680928807 Off axis angle [arcmin]
           phi = 165.0773381742928 Azimuthal angle [deg]
         order = 0                Grating order
...etc...

The point at (4101.38,4066.5) has an off-axis angle of 0.25 arcmin.

To calculate the crosshair coordinates in degrees or sexagesimal format using XPA directly:

unix% xpaget ds9 crosshair wcs 
 187.27543 2.049769 

unix% xpaget ds9 crosshair wcs sexagesimal
12:29:06.104 +02:02:59.17

The two methods give identical results. Note that to get (RA,Dec) in degrees with dmcoords, it is necessary to set celfmt=deg and re-run the tool.