Introduction to CIAO

Get Started

For illustration, this thread utilizes the ObsID 1843 (ACIS-I, G21.5-0.9) data that was downloaded in the How to Download Chandra Data from the Archive thread.

If this is your first time using CIAO, please read the Starting CIAO thread to ensure that your environment is configured properly. That thread also contains details on running multiple versions of CIAO and avoiding conflicts with FTOOLS.

Dictionary of terms

CIAO uses a number of specialized terms some of which are common in X-ray astronomy data analysis, but not used elsewhere, and some of which are new to CIAO. We have provided a dictionary for some of these terms.

Command-line Completion

From the unix% prompt it is not necessary to type the full name of a tool, application, or filename. <ESC><ESC> or <TAB> will complete the name as long as sufficient letters/numbers are given for it to be unique:

unix% dml<TAB> --> dmlist

and

unix% cel<ESC><ESC> --> celldetect

Note that command-line completion is a function of the shell, not CIAO. This will not work in Bourne shell (and perhaps others).

Special Characters

As in most systems, there are restrictions on the use of special characters. Special characters are symbols that are reserved for use by the system or have special meaning to the application. The standard set (defined as special by most operating systems) of "special" characters is:

  & ( ) [ ] ; | * ? ' " ` $ < > ; { } ^ # / \ (space character)

In general, files and directories should not contain these characters.

Header Keywords

There are many header keywords in the Chandra FITS files. The most important ones for data analysis are described here:

• Identification

  • SEQ_NUM (sequence number): the primary number used for identification, unique to each observation
  • OBS_ID (observation identification number): a unique identifier used by the processing system
  • OBJECT: name of the target
  • OBSERVER: name of the Principal Investigator

• Pointing information

  • RA_NOM: nominal right ascension in J2000 coordinates, decimal degrees
  • DEC_NOM: nominal declination in J2000 coordinates, decimal degrees

• Timing information

  • DATE-OBS: time and date of start of observation
  • DATE-END: time and date of end of observation
  • TSTART: time of start of observation in seconds since 1998 Jan 1 00:00:00
  • TSTOP: time of end of observation in seconds since 1998 Jan 1 00:00:00
  • MJDREF: modified Julian Date of the time zero point (1998 Jan 1 00:00:00)
  • DTCOR: deadtime correction
  • ONTIME: sum of time in GTIs in seconds
  • LIVETIME: ONTIME multiplied by DTCOR
  • EXPOSURE: final exposure time, including all corrections

• Instrument Information

  • MISSION: AXAF
  • TELESCOP: Chandra
  • INSTRUME: the instrument used for the observation
  • DETNAM: the chip number(s) of the observation, if relevant. The ACIS chip numbering scheme is provided in Table 1.
  • DATAMODE: mode in which the instrument was used
  • GRATING: grating used (or NONE)

Parameter Files

Most CIAO tools make use of parameters, which are stored in parameter files. Parameters may be set by editing the parameter file or by specifying parameter settings on the command line; see the Using Parameter Files thread for details and examples.

A few things to know about using CIAO parameter files:

• If you wish to use FTOOLS as well as CIAO, then start FTOOLS before you start CIAO; this is discussed in detail in the CIAO startup thread.

• To check the current setting for parameter-file storage in your environment

  unix% echo $PFILES
  /home/username/cxcds_param4;/soft/ciao/contrib/param:/soft/ciao/param
  

  The default parameter files for each tool are stored in $ASCDS_INSTALL/param; in the example above, this is the /soft/ciao/param directory.

• The filename of a tool's parameter file is the tool name with a .par extension. When you edit a parameter file or run a tool, the tool's parameter file is placed and/or updated in $HOME/cxcds_param4 by the software.

• One way to view the contents of a parameter file is to use plist:

  unix% plist dmlist
  
  Parameters for /soft/ciao/param/dmlist.par
  
          infile =                  Input dataset/block specification
             opt = data             Option
        (outfile = )                Output file (optional)
           (rows = )                Range of table rows to print (min:max)
          (cells = )                Range of array indices to print (min:max)
        (verbose = 0)               Debug Level(0-5)
           (mode = ql)              
  

  Those parameters not within parentheses are called "positional parameters;" those parameters that are within parentheses are called "hidden parameters."

• Parameters are set with the pset command:

  unix% pset dmlist infile=acisf01843N002_evt2.fits
  unix% plist dmlist
  
  Parameters for /home/username/cxcds_param4/dmlist.par
  
          infile = acisf01843N002_evt2.fits Input dataset/block specification
             opt = data             Option
        (outfile = )                Output file (optional)
           (rows = )                Range of table rows to print (min:max)
          (cells = )                Range of array indices to print (min:max)
        (verbose = 0)               Debug Level(0-5)
           (mode = ql)              
  

Further information and examples are available in the Using Parameter Files thread.

Running a Tool

• All the CIAO tools that make use of parameter files are directly executed from the command line:

  unix% dmlist
  Input dataset/block specification (acisf01843N002_evt2.fits): 
  Option (data): block
   
  --------------------------------------------------------------------------------
  Dataset: acisf01843N002_evt2.fits
  --------------------------------------------------------------------------------
   
       Block Name                          Type         Dimensions
  --------------------------------------------------------------------------------
  Block    1: PRIMARY                        Null
  Block    2: EVENTS                         Table        15 cols x 490795   rows
  Block    3: GTI7                           Table         2 cols x 1        rows
  Block    4: GTI6                           Table         2 cols x 1        rows
  Block    5: GTI3                           Table         2 cols x 2        rows
  Block    6: GTI2                           Table         2 cols x 1        rows
  Block    7: GTI1                           Table         2 cols x 1        rows
  Block    8: GTI0                           Table         2 cols x 1        rows
  

• The prism and peg tools possess their own graphical user interface (GUI) environments. For example, the following command launches the Prism GUI:

  unix% prism
  

  Choose "Exit" from the GUI's "File" menu to quit.

Session Management & GUIs

A "session" is a conceptual notion of the integrated data-analysis environment formed by the interaction of CIAO applications. Most of this interaction is "under-the-hood" and not seen by the user, such as when filtwin reads a region drawn on an image displayed in ds9. Presently, only filtwin and prism provide the ability to save and restore the current state of the session.

The user-configurable preferences for session support are stored in ciao.par; documentation on this parameter file, the CIAO guis, and the session concept can be accessed using

unix% ahelp ciao.par
unix% ahelp gui
unix% ahelp session

The appearance of the GUI applications can be controlled by the .CXCdefaults file in your home directory. Start by copying the version from the CIAO installation into your home directory with:

unix% cp $ASCDS_INSTALL/config/system/CXCdefaults ~/.CXCdefaults

and then make your changes. While it contains many configuration options, it is most useful for defining the colors used by the GUI applications; see the colormap FAQ for an example.

Accessing CIAO Help

CIAO Help is available from the command line or from the "Help" button on the graphical interfaces. The command to access CIAO Help is ahelp and one of the following arguments may be added to it:

• ahelp -s dmlist
  returns a synopsis and the tool's syntax
• ahelp -m dmlist
  returns a synopsis, the syntax, and examples
• ahelp -l dmlist
  returns the maximum amount of text-based help, describes all parameters in detail
• ahelp -k list
  returns a list of subjects that are cross-referenced to the help string (akin to unix's apropos command).

The user may find the following special help commands useful:

• ahelp dmintro - an introduction to the Data Model
• ahelp dmsyntax - an overview of the Data Model syntax
• ahelp tools - all CXC tools (such as dmcopy, csmooth, or lightcurve)
• ahelp acis - ACIS tools
• ahelp hrc - HRC tools
• ahelp detect - Detect tools
• ahelp grating - grating tools
• ahelp convolution - convolution tools
• ahelp timing - timing tools

Further Assistance and Reporting Bugs

Further assistance is available from the Helpdesk, the Chandra Users email list, or the CIAO FAQ. Bug reports and suggestions should be submitted to the Help Desk, but please check the Bug List first to see if the problem is already known.

When reporting bugs, please include the version of CIAO you are using. This can be found using the ciao alias used to start CIAO:

unix% ciao -v
This script sets the user's CIAO environment to utilize:
 CIAO version     :  CIAO 4.0 Thursday, December 6, 2007
 Proposal Toolkit version :  Cycle 10 Thursday, December 6, 2007
 bin dir          :  /soft/ciao/bin

If CIAO is already running in the window, you will see:

unix% ciao -v
The current environment is configured for:
 CIAO version     :  CIAO 4.0 Thursday, December 6, 2007
 Proposal Toolkit version :  Cycle 10 Thursday, December 6, 2007
 bin dir          :  /soft/ciao/bin

Additional Software

The CXC provides two additional software resources:

1. A number of command-line scripts, which are designed to simplify repetitive tasks, or work around bugs in the system.
2. Other Software for Chandra Data Analysis, which contains user-contributed code.