Last modified: 16 Feb 2022

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

Introduction to CIAO

CIAO 4.16 Science Threads


Overview

Synopsis:

A basic introduction to using CIAO, the Chandra Interactive Analysis of Observations software package.

Last Update: 16 Feb 2022 - Review for CIAO 4.14. No changes.


Contents


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.


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)
Table 1. ACIS chip numbering scheme
Number
(DETNAM)
Name
0 I0
1 I1
2 I2
3 I3
4 S0
5 S1
6 S2
7 S3
8 S4
9 S5

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.


History

04 Jan 2005 updated for CIAO 3.2: version numbers
01 Dec 2005 updated for CIAO 3.3: version numbers
01 Dec 2006 updated for CIAO 3.4: CIAO, ChIPS, and Sherpa versions
14 Dec 2007 updated for CIAO 4.0: added links to ChIPS and Sherpa websites; updated CIAO version and parameter directory name; filename and screen output updated for reprocessed data (version N002 event file)
15 Sep 2008 the Chandra Contributed Software page is now called Other Software for Chandra Data Analysis and has a new URL
30 Dec 2008 updated for CIAO 4.1: the GUIs no longer use sessions or ciao.par (removed "Session Management & GUIs" section)
12 Mar 2009 changed CIAO installation directory to /soft/ciao-4.1/ to match the Installing CIAO thread
11 Jan 2009 updated for CIAO 4.2: CIAO installation directory is /soft/ciao-4.2/, the same directory used in the Installing CIAO thread; updated the output of 'ciao -v'
11 Jan 2011 updated for CIAO 4.3: version numbers
03 Jan 2012 reviewed for CIAO 4.4: updated version numbers
03 Dec 2012 Review for CIAO 4.5; updated versions, updated keywords list.
25 Nov 2013 Review for CIAO 4.6.
11 Dec 2014 Review for CIAO 4.7.
09 Dec 2015 Review for CIAO 4.8
10 Feb 2016 Updated for CIAO 4.8.1 package versions.
09 Apr 2018 Updated for CIAO 4.10.
06 Dec 2018 Updated for CIAO 4.11
02 Nov 2020 Remove reference to 'peg' which has been withdrawn from CIAO 4.13.
16 Feb 2022 Review for CIAO 4.14. No changes.