Introduction to CIAO

Get Started

The CIAO software is installed in /soft/ciao-4.16/ in this thread. Your installation of CIAO may be located in a different directory.

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

  • OBS_ID (observation identification number): a unique identifier used by the processing system
  • SEQ_NUM (sequence number): the primary number used for identification of a target within an observing program.
  • OBJECT: name of the target
  • OBSERVER: name of the Principal Investigator

• Pointing information

  • RA_PNT: mean right ascension in J2000 coordinates, decimal degrees of the optical axis
  • DEC_PNT: nominal declination in J2000 coordinates, decimal degrees of the optical axis
  • RA_NOM: right ascension in J2000 coordinates, decimal degrees, of the tangent point.
  • DEC_NOM: declination in J2000 coordinates, decimal degrees, of the tanget point.

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

Also see Figure 6.1 of the POG for an illustration of the ACIS focal plane.

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-4.16/contrib/param:/soft/ciao-4.16/param
  

  The default parameter files for each tool are stored in $ASCDS_INSTALL/param; in the example above, this is the /soft/ciao-4.16/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-4.16/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
  

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 takes several optional arguments:

• ahelp dmlist
  returns the full dmlist help file
• 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).

Further Assistance and Reporting Bugs

Further assistance is available from the CXC Helpdesk 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 ciaover utility:

unix% ciaover -v
The current environment is configured for:
  CIAO        : CIAO 4.16.0 Tuesday, December 05, 2023
  Contrib     : Package release 0  Tuesday, November 28, 2023
  bindir      : /soft/ciao-4.16/bin
  Python path : /soft/ciao-4.16/bin
  CALDB       : 4.11.0

System information:
Linux is.awesome.edu 4.18.0-477.13.1.el8_8.x86_64 #1 SMP Thu May 18 10:27:05 EDT 2023 x86_64 x86_64 x86_64 GNU/Linux

Additional Software

There are many other tools that can work with Chandra data. On the Other Software for Chandra Data Analysis page, the CXC provides links to some of the software of which we are aware, developed both by the CXC and by external users.