Last modified: 13 Jan 2022

URL: https://cxc.cfa.harvard.edu/ciao/threads/ds9/

Using SAOImage ds9

CIAO 4.15 Science Threads


Overview

Synopsis:

The imaging application SAOImage ds9 is distributed with CIAO as the default imager. It is developed independently from CIAO but does contain some CIAO-specific features.

Purpose:

To introduce a few of the key features used in CIAO analysis ranging from simple (e.g. defining preferences) to complex (e.g. use of the XPA messaging system).

Related Links:

Last Update: 13 Jan 2022 - Reviewed for CIAO 4.14. Updated file versions.


Contents


Getting Started

Download the sample data: 1712 (ACIS-S, 3C 273); 315 (NGC 4038/NGC 4039); 1838 (G21.5-0.9)

unix% download_chandra_obsid 1712,315,1838 evt2,asol

Video Demos and Tutorials

The CXC has prepared several video demos and tutorials that complements the material presented below.


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). The lower left corner of the array will have coordinates (0.5,0.5). Coordinates increase to the right in x and up in y.

Physical/Sky

The physical (x,y) coordinate system is called "sky" in shorthand. This is the system used most often in Chandra data analysis. 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.

CIAO regions created in ds9 are saved in physical coordinates by default. This format is recommended to ensure compatibility with the CIAO tools. The CIAO and ds9 region formats section of the Using CIAO Regions thread has a discussion on the ASCII region types available for use.

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 acisf01712N005_evt2.fits cols
...cut...

8:    EQPOS(RA ) = (+187.2760)[deg] +TAN[(-0.000136667)* (sky(x)-(+4096.50))]
           (DEC)   (+2.0552  )           (+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.2760,2.0552).

CIAO regions may be saved in celestial coordinates, but only sexagesimal (not decimal) coordinates are supported (e.g. circle(17:46:14.065,-28:51:39,1.0')).

WCS

The World Coordinate System (WCS) is a generalized name for the celestial coordinate system. The default coordinate system in CIAO and ds9 is the J2000 system. The physical (x,y) coordinate system is related to WCS by specifying the (RA,Dec) of a reference pixel in the file's header.

A complete description of the WCS standard is given on the WCSTools home page.

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 acisf01712N005_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 acisf01712N005_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:

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 the preferences are written to $HOME/.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 acisf01712N005_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.

Figure 1: Image in (x,y) binned by a factor of 16

[Thumbnail image: An image of the event file, created by binning the (x,y) axes by a factor of 16]

[Version: full-size]

[Print media version: An image of the event file, created by binning the (x,y) axes by a factor of 16]

Figure 1: Image in (x,y) binned by a factor of 16

Change the binning factor of an image by using the "Bin" button or the "Bin" menu.

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 "Block" to 4, select the "or center of data" button, and click "Apply". Figure 2 shows the results.

Figure 2: An image in (detx,dety) binned by a factor of 4

[Thumbnail image: An image of the event file, created by binning the (detx,dety) axes by a factor of 4]

[Version: full-size]

[Print media version: An image of the event file, created by binning the (detx,dety) axes by a factor of 4]

Figure 2: An image in (detx,dety) binned by a factor of 4

The columns to bin are selected in the "Bin Parameters" section of the "Bin" menu. This coordinate system is unaffected by the dither, so point sources appear as limb-brightened squares.

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.

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 "acisf01712N005_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 acisf01712N005_evt2.fits -cmap b -scale log ../../315/primary/acisf00315N004_evt2.fits \
          -cmap b -scale log /data/1838/primary/acisf01838N004_evt2.fits -cmap b -scale log &
    

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

    Figure 3: Displaying multiple frames

    [Thumbnail image: Three images are displayed in ds9: ObsID 1712 (upper left), ObsID 315 (upper right), and ObsID 1838 (lower left).]

    [Version: full-size]

    [Print media version: Three images are displayed in ds9: ObsID 1712 (upper left), ObsID 315 (upper right), and ObsID 1838 (lower left).]

    Figure 3: Displaying multiple frames

    The images are displayed in the order in which they were loaded, starting at the upper-right corner. The fourth space in this layout (lower-right) is empty.

  2. Use the "Frame → New Frame" menu option. This process can be repeated to create as many frames as desired. To load the data, select the desired frame and then choose the file 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:

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

unix% ds9 acisf01712N005_evt2.fits -scale log &

A. Contours and the DSS

To apply contours to the data, open the "Contour Parameters" window from "Analysis → Contours Parameters". There are four parameters to adjust: the number of contours ("Contour Levels"), the smoothness of the contours, the flux at the lowest contour, and the flux at the highest contour. The flux at each contour is displayed in the "Levels" portion of the window. Be sure to click "Generate" whenever an adjustment is made to the contour parameters; this will recalculate the levels to be applied to the image.

In this example, four levels were created for the flux limits 5 to 365 at a smoothness of 5. Figure 4 shows the "Contour Parameters" window and the resulting contours on the image. Smoothing the contours can make the number of contours displayed less than the number generated.

Figure 4: X-ray image with contours

[Thumbnail image: The "Contour Parameters" dialog box is open with the levels set to 4 and the smoothness set to 5.]

[Version: full-size]

[Print media version: The "Contour Parameters" dialog box is open with the levels set to 4 and the smoothness set to 5.]

Figure 4: X-ray image with contours

Apply contours to data via the "Contour Parameters" window from the menu "Analysis → Contours Parameters."

It is also possible to access Digital Sky Survey (DSS) optical images matching your observation via the "Analysis → Image Servers" menu in ds9. There are several DSS server options; we used "SAO-DSS". The "SAO-DSS Server" window 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. You may also want to use the menus in the dialog box to select a different server for quicker access from your location. In this example, none of the values determined by ds9 were changed before clicking on "Retrieve".

To overlay the X-ray contours on the optical image:

  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".
  6. Adjust the parameters in the "Contours Parameters" dialog box that pops up, if desired, then click "OK". In this example, the contour color was changed from green to red.

The final product should look similar to Figure 5. Adjust the contrast and the jet is identifiable in both the xray and optical image, extending a few arcseconds to the southwest (lower right).

Figure 5: X-ray and optical images with contours

[Thumbnail image: The x-ray data is in the left frame and the optical data is in the right frame; both have the x-ray contours displayed on the data.]

[Version: full-size]

[Print media version: The x-ray data is in the left frame and the optical data is in the right frame; both have the x-ray contours displayed on the data.]

Figure 5: X-ray and optical images with contours

Access Digital Sky Survey (DSS) optical images matching your observation via the "Analysis → Image Servers" menu.

The contours can also be saved to disk by choosing "Save Contours" from the "File" menu. They can then be loaded back into ds9 with the "Load Contours" option.

This image is used as the starting point for the next example (Locking Crosshairs), so do not exit ds9 if you are planning on continuing in the thread.


B. Locking Crosshairs

Having WCS defined for two images can be valuable in their simlutaneous analysis, as shown in the previous section where the images were matched via WCS. This information, combined with the "locking crosshairs" feature in ds9, can be used to examine the same region in several frames simultaneously.

Starting from the previous example, change the cursor to crosshair by means of the "Edit" menu. To lock the crosshairs into the same coordinate system for correlating features between the two images, go to "Frame → Lock Crosshairs → WCS". After locking crosshairs and zooming in on the central portion of the image, the display looks like Figure 6.

Figure 6: Images with contours and locked crosshairs

[Thumbnail image: The x-ray data is in the left frame and the optical data is in the right frame; the ds9 crosshair is on the first knot of the jet.]

[Version: full-size]

[Print media version: The x-ray data is in the left frame and the optical data is in the right frame; the ds9 crosshair is on the first knot of the jet.]

Figure 6: Images with contours and locked crosshairs

To correlate features between two images, change the cursor to crosshair and lock the crosshairs into the same coordinate system.


C. Using Analysis Scripts

The "Load Analysis Commands..." function allows the user to define menu items which call scripts. The displayed file (and optionally regions) are exported to the script which is executed, returning the results to a ds9 text window.

This process requires two things: an analysis file which defines the menu item and the script which is called by the menu item. A shell script named "script.sh" is used for this example, but any type of script is possible.

Multiple menu items may be defined in a single analysis file. For each analysis menu item, four things must be given:

Menu label to be used 
A space-separated list of file templates 
Command type [menu | bind <event>] 
The command line for the analysis program

This is described in more detail in the Analysis section of the ds9 manual. The analysis file used in this example also includes a comment line:

#Define a menu item to call "script.sh"

Get Counts in Regions
*.fits *.fits.gz
menu
/workingpath/script.sh $filename $regions(source,ciao) $regions(background,ciao) | $text

where "/workingpath" is the path to the script. To define the menu item, create an analysis file containing this text. For this example, the file is saved as ciao.ds9:

unix% cat ciao.ds9
#Define a menu item to call "script.sh"

Get Counts in Regions
*.fits *.fits.gz
menu
script.sh $filename $regions(source,ciao) $regions(background,ciao) | $text

The final line defines the script's three input fields:

  • $filename - the name of the event file
  • $regions(source,ciao) - the source regions defined, in CIAO format
  • $regions(background,ciao) - the background regions defined, in CIAO format

The script output is sent to $text, which will appear in a new ds9 window. More information on the analysis file variables is given in the Analysis section of the ds9 manual.

This analysis file can also be loaded automatically when ds9 is launched. To do so, either supply the pathname in the preferences or rename the file .ds9.ans and keep it in your home directory.


Running CIAO tasks from the Analysis menu

There is a suite of scripts, called dax, that allows users to run some common CIAO tasks from within ds9. The tasks in dax are implemented in the same manner as Analysis Scripts, and are automatically loaded from the file $ASCDS_INSTALL/config/ciao.ds9 when ds9 is launched from within CIAO.

The scripts are accesible from "Analysis → CIAO", as shown in Figure 7.

Figure 7: Selecting the CIAO dax task menu

[Thumbnail image: The menu contains analysis categories such as "statistics" and "histograms".]

[Version: full-size]

[Print media version: The menu contains analysis categories such as "statistics" and "histograms".]

Figure 7: Selecting the CIAO dax task menu

Each category expands to show the available options. From the Detect menu, it's possible to run celldetect, vtpdetect, or get_src_region on an image.

The ahelp file for dax has more information on the scripts, as well as some known limitations.


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).

Launch ds9:

unix% ds9 acisf01712N005_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.27699 username

Now that ds9 is running and linked to an XPA server, mark the desired point on the image with the crosshairs. Recall that the "Edit" menu is used to change the cursor.

xpaget is used to retrieve the cursor location, which is then input to the tool dmcoords (note that the "set" command syntax given is correct for the csh or tcsh shell):

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=acisf01712N005_evt2.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 = acisf01712N005_evt2.fits Input dataset/block specification
      asolfile =    Input aspect solution file
#
# Position of photon in different coord systems
#
       chip_id = 7                Chip ID number
         chipx = 188.7071503462198 Chip X [pixel]
         chipy = 390.1592564498173 Chip Y [pixel]
         tdetx = 4105.707150346219 TDETX [pixel]
         tdety = 2092.159256449817 TDETY [pixel]
          detx = 4067.131532836975 FPC X [pixel]
          dety = 4104.326797652676 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.264     RA [deg or hh:mm:ss]
           dec = +02:03:00.48     Dec [deg or dd:mm:ss]
         theta = 0.2492268040240001 Off axis angle [arcmin]
           phi = 165.0773142314044 Azimuthal angle [deg]
         order = 0                Grating order
...etc...


unix% pget dmcoords theta
0.2492268040240001

The point at (4101.375,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.2761 2.0501338

unix% xpaget ds9 crosshair wcs sexagesimal
12:29:06.263 +02:03:00.48

The results are the same coordinates reported by dmcoords. Note that to get (RA,Dec) in degrees with dmcoords, it is necessary to set celfmt=deg and re-run the tool.

XPA redirects

XPA redirects ("%xpa()") also allow you to get information from ds9 and use it with the CIAO tools. This method differs from the previous example in that the values are automatically updated when the crosshairs are moved.

This example uses the XPA redirect to read the x and y coordinates of the crosshairs into dmcoords:

unix% ds9 acisf01712N005_evt2.fits &

unix% punlearn dmcoords
unix% pset dmcoords infile="%xpa(ds9,file)"

unix% pset dmcoords opt=sky
unix% pset dmcoords x="%xpa(ds9,x)"
unix% pset dmcoords y="%xpa(ds9,y)"

# place the crosshairs at some location in the ds9 window

unix% dmcoords mode=h verb=1 | grep SKY
SKY(X,Y):         4101.38       4066.50

# move the crosshairs in ds9

unix% dmcoords mode=h verb=1 | grep SKY
SKY(X,Y):         4087.75       4083.00

Since the x and y coordinates are set in the parameter file as redirects, the values are automatically updated when the crosshairs are moved. The parameter file looks like:

unix% plist dmcoords

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

        infile = %xpa(ds9,file) -> acisf01712N005_evt2.fits[EVENTS] Input dataset/block specification
      asolfile =                 Input aspect solution file
#
# Position of photon in different coord systems
#
       chip_id = 7                Chip ID number
         chipx = 209.3624694289583 Chip X [pixel]
         chipy = 384.4581321490172 Chip Y [pixel]
         tdetx = 4126.362469428958 TDETX [pixel]
         tdety = 2086.458132149017 TDETY [pixel]
          detx = 4087.76202058092 FPC X [pixel]
          dety = 4110.007783521776 FPC Y [pixel]
             x = %xpa(ds9,x) -> 4087.75 Sky X [pixel]
             y = %xpa(ds9,y) -> 4083 Sky Y [pixel]
...

Because the values are read from ds9, they are not available after ds9 has been closed:

unix% plist dmcoords

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

        infile = %xpa(ds9,file) ->  Input dataset/block specification
      asolfile =                  Input aspect solution file
#
# Position of photon in different coord systems
#
       chip_id = 7                Chip ID number
         chipx = 209.3624694289583 Chip X [pixel]
         chipy = 384.4581321490172 Chip Y [pixel]
         tdetx = 4126.362469428958 TDETX [pixel]
         tdety = 2086.458132149017 TDETY [pixel]
          detx = 4087.76202058092 FPC X [pixel]
          dety = 4110.007783521776 FPC Y [pixel]
             x = %xpa(ds9,x) ->   Sky X [pixel]
             y = %xpa(ds9,y) ->   Sky Y [pixel]
...

ds9 and XPA Versions

Since ds9 and XPA can both be used independently of CIAO, it is possible that your system has a different version installed than the one that is packaged with CIAO. Also, in order to run CIAO scripts from ds9, the imager must have been launched from a term window already running CIAO. For these reasons, we recommend that you make sure CIAO is running in the current window before beginning any analysis task using ds9 or XPA. Otherwise, incompatibilities between the imager and the commands in the thread may arise.

Here we show that the ds9 accessed from the term window changes after starting CIAO:

unix% which ds9
/usr/local/bin/ds9

unix% ciao
CIAO configuration is complete... 
CIAO 4.15 Monday, November 21, 2022
  bindir      : /soft/ciao-4.15/bin
  CALDB       : 4.10.7

unix% which ds9
/soft/ciao/bin/ds9

The same applies to XPA:

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

unix% ciao
CIAO configuration is complete... 
CIAO 4.15 Monday, November 21, 2022
  bindir      : /soft/ciao-4.15/bin
  CALDB       : 4.10.7

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

Any CIAO thread that refers to ds9 and/or XPA assumes that the version being used is the one packaged with CIAO.


Using a newer version of ds9

When a CIAO release is being prepared, the most recent version of ds9 available is used in testing and then packaged with the software. Since updates to ds9 are released on a much shorter timescale than CIAO, users may wish to upgrade independently of CIAO to take advantage of new features and bug fixes.

If you wish to use a different version of ds9 than the one packaged with CIAO, please refer to this FAQ. It is not guaranteed that CIAO will work flawlessly with a newer release of ds9! It is possible that changes to the imager may cause unexpected problems in the CIAO software.


History

23 Dec 2004 updated for CIAO 3.2: version of ds9
23 Mar 2005 updated contours images to match ds9 v3.0b9
19 Dec 2005 updated for CIAO 3.3: ds9 v4.0b7 is packaged with CIAO 3.3, ds9 v4.0 region format is slightly different than v3.0; getcounts.sl has not yet been updated for CIAO 3.3/ds9 v4.0
01 Dec 2006 updated for CIAO 3.4: CIAO version in screen output
09 Jan 2007 created Using a newer version of ds9 subsection
08 Jan 2008 updated for CIAO 4.0: removed "Known Issues" section; ds9 v5.0 packaged with CIAO; filename and screen output updated for reprocessed data (version N003 event file); expanded XPA section
13 Jun 2008 updated image display to place figures inline with text
05 Jan 2009 updated for CIAO 4.1: ds9 v5.4 is packaged with CIAO; new section: dax: running CIAO tasks from the Analysis menu; ds9 and slsh have moved from /soft/ciao/ots to /soft/ciao/bin; "-xpa local" workaround no longer needed
20 Apr 2009 updated for CIAO 4.1.2: the asolfile parameter in dmcoords has changed from hidden to automatic (updated parameter file listing)
25 Jan 2010 reviewed for CIAO 4.2: no changes
11 Jan 2011 updated for CIAO 4.3: minor update to contour images
05 May 2011 updated the Coordinate Definitions section
03 Jan 2012 reviewed for CIAO 4.4: no changes
10 Oct 2012 add link to video guides
18 Oct 2012 checked for ds9 v7.1 compatibility; updated .ds9.prf; update file names for repro-4 versions;
03 Dec 2012 Review for CIAO 4.5; no changes.
25 Nov 2013 Review for CIAO 4.6.
04 Dec 2014 Review for CIAO 4.7. Updated for dmcoords change in CIAO 4.6 that now automatically accounts for SIM drift. asolfile parameter is now hidden.
01 Feb 2016 Updated ds9 links.
13 Jan 2022 Reviewed for CIAO 4.14. Updated file versions.