Last modified: 6 December 2023

URL: https://cxc.cfa.harvard.edu/ciao/guides/quick_start.html

Quick Start Guide / Crib Sheet


This page provides an abridged set of CIAO threads to get started with the most common Chandra data reduction tasks.

I want to ...



... install CIAO

Check the system requirements to make sure that your machine is ready to install CIAO. Then,

Using conda:

$ conda -v
$ conda create -n ciao -c https://cxc.cfa.harvard.edu/conda/ciao -c conda-forge \
  ciao pyciao ciao-contrib sherpa ds9 marx caldb_main

% conda activate ciao
  -or-
$ source activate ciao

$ cd $ASCDS_INSTALL
$ bash test/smoke/bin/run_smoke_tests.sh

Users can replace caldb_main with caldb if they require the ACIS and HRC blank sky files.

Users may also wish to install additional packages such as jupyter, astropy, or scipy at this point.

Or using the ciao-install script:


... setup for CIAO

If you installed CIAO using conda:

$ conda activate ciao
  -or-
$ source activate ciao

If you installed CIAO using the ciao-install script:

bash$ alias ciao="source /soft/ciao/bin/ciao.sh"
  or
tcsh% alias ciao "source /soft/ciao/bin/ciao.csh"

then

$ ciao  

We recommend that you add the ciao alias to your login shell: $HOME/.bashrc or $HOME/.cshrc.


... get help about a CIAO command or concept

$ ahelp dmlist
$ ahelp images
$ ahelp regions

CIAO includes over 1200 help files covering all the Sherpa commands, individual tools & scripts, and Chandra & CIAO concepts.


... find observations of my source

find_chandra_obsid only works for public, non-proprietary, data. It can also search by position and radius, filter by instrument and grating, and download data. For proprietary data, users must use the ChaSER web interface.


... download data

$ download_chandra_obsid 4425
$ chandra_repro 4425 outdir=

download_chandra_obsid can also be used to download individual files, as well as data for multiple observations.

We encourage users to apply the most recent calibrations to their datasets using the chandra_repro script when the data are retrieved from the archive.


... view the contents of a file (data, columns, keywords, blocks)

$ download_chandra_obsid 635 evt2
$ dmlist 635/primary/acisf00635N004_evt2.fits.gz header,clean

dmlist can also display information about coordinate systems and any filters ("subspace"). It works with images and tables and mutli-extension FITS or ASCII files.

There are various other tools that can be used to extract header info from a file including dmkeypar, dmmakepar, and dmlist.


... extract spectrum for a point-like source

$ download_chandra_obsid 4425
$ chandra_repro 4425 outdir=
$ ds9 4425/repro/acisf04425_repro_evt2.fits
Create a region and save as src.reg
$ specextract  "4425/repro/acisf04425_repro_evt2.fits[sky=region(src.reg)]" mysrc

specextract has options for including background, extended sources, PSF corrections, grouping, and combining datasets.


... extract high-resolution grating spectrum

$ download_chandra_obsid 13721
$ chandra_repro 13721 13721/repro

Grating data retrieved from the Chandra archive already includes the PHA file, pha2.fits, for the brightest source in the field. Additionally, data run through chandra_repro already has the response files created so users are ready to begin their anlaysis.

To customize the 0-th order location or the extraction regions, users can use: tg_create_mask and tgextract or tgextract2. The grating ARF and RMF files are created using mktgresp


... combine spectra

$ specextract "@myevents.list[sky=region(ds9.reg)]" mydata combine=yes

specextract can extract and optionally combine multiple spectra using stacks

With a region defined in world coordinates, the event files do not need to be reprojected to a common tanget point (WCS).

$ search_csc CXOJ123538.4+621643 radius=0.1 outfile=src.tsv download=all file=pha,rmf,arf
$ combine_spectra "2CXOJ123538.4+621643/*/*pha*" cxo

combine_spectra can be used to combine spectra and their response file that have already been extracted.

$ combine_grating_spectra tgcat/obs_5422_tgid_3921/pha2 outroot=obs5422 add_plusminus=yes \
   arf="tgcat/obs_5422_tgid_3921/*.arf" rmf="tgcat/obs_5422_tgid_3921/*.rmf

combine_grating_spectra can be used to either combine grating orders or to combine grating spectra from multiple observations, or both.


... convert count rate to flux

$ download_chandra_obsid 4425
$ chandra_repro 4425 outdir=
$ ds9 4425/repro/acisf04425_repro_evt2.fits
Create a region and save as src.reg
Get count rate using Analysis -> CIAO -> Statistics -> Net Counts
$ specextract  "4425/repro/acisf04425_repro_evt2.fits[sky=region(src.reg)]" mysrc
$ modelflux mysrc.arf mysrc.rmf emin=0.5 emax=7.0 rate=0.1 \
    model='xspowerlaw.p1' paramval='p1.PhoIndex=2.0' absmodel='xsphabs.a1' absparams='a1.nH=0.02' \

modelflux has access to all sherpa models and can be used with arbitrary energy ranges and model parameters


... estimate the flux for a point-like source

$ download_chandra_obsid 4425
$ chandra_repro 4425 outdir=
$ srcflux 4425/repro/acisf04425_repro_evt2.fits '11:33:05,+25:53:55.4' mysrc

srcflux has options for PSF corrections, energy bands, confidence intervals (including upper-limits), spectral models, and user supplied regions.


... make exposure corrected images

$ download_chandra_obsid 635
$ chandra_repro 635 635/repro
$ fluximage 635/repro/acisf00635_repro_evt2.fits rhoOph

fluximage has options for energy bands, binsize (resolution), and for HRC background subtraction.


... create 3 color (RGB) image

$ download_chandra_obsid 214
$ chandra_repro 214 214/repro
$ fluximage  214/repro/acisf00214_repro_evt2.fits cas_a bands="soft,medium,hard" bin=4
$ ds9 -rgb -red cas_a_soft_flux.img -green cas_a_medium_flux.img -blue cas_a_hard_flux.img

There are multiple ways to perform tasks in ds9 , including through the GUI, on the command line, via XPA or SAMP, and even through HTML

$ dmimg2jpg cas_a_soft_flux.img cas_a_medium_flux.img cas_a_hard_flux.img out=cas_a.jpg

dmimg2jpg is nice to use in scripts but takes some trial and error to get the hidden parameters set to produce optimal results.


... compute source centroid

$ download_chandra_obsid 4425
$ chandra_repro 4425 outdir=./
$ dmstat "acisf04425_repro_evt2.fits[sky=region(src.reg)][bin sky=1]"

dmstat computes some basic statistics (min, max, mean, median, standard deviation) for columns in a table, or for image pixel values


... detect sources

$ download_chandra_obsid 635
$ chandra_repro 635 out=
$ fluximage "635/repro/acisf00635_repro_evt2.fits[ccd_id=0:3]" acis_I_rOph binsize=1 clob+ psfecf=0.9
$ wavdetect infile=acis_I_rOph_broad_thresh.img psffile=acis_I_rOph_broad.psfmap \
  expfile=acis_I_rOph_broad_thresh.expmap scales="1.4 2 4 6 8 12 16 24 32" outfile=acis_I_rOph.src \
  scellfile=acis_I_rOph.cell imagefile=acis_I_rOph.recon defnbkg=acis_I_rOph.nbkg

wavdetect has options for setting significance threshold (false source rate) and user supplied background.

wavdetect is not a photometric tool. While it does provide an estimate of the counts, we strongly recommend users compute flux separately, eg using srcflux

$ srcflux 635/repro/acisf00635_repro_evt2.fits pos=acis_I_rOph.src outroot=acis_I_rOph

... extract light curve (check for variability)

$ download_chandra_obsid 635
$ chandra_repro 635 out=./
$ dmextract "acisf00635_repro_evt2.fits[energy=500:7000][sky=ellipse(4053,3210,16,10,38)][bin time=::3000]" \
  flare.lc op=ltc1 clob+

or

$ glvary "acisf00635_repro_evt2.fits[energy=500:7000][sky=region(ciao.reg)]" vary.prob vary.lc none clob+

Both dmextract and glvary make use of Good Time Intervals (GTIs) and an optional time-dependent efficiency factors file


... make a radial profile

$ download_chandra_obsid 17395
$ chandra_repro 17395 outdir=./
$ fluximage hrcf17395_repro_evt2.fits coma
$ dmextract "hrcf17395_repro_evt2.fits[bin sky=annulus(16635,15690,0:3200:100)]" coma_prof.rad \
  exp=coma_wide_thresh.expmap clob+ op=generic

dmextract can also extract the radial profile from an image rather than an event file. It can also extract the background and provide net quantities.


... search Chandra Source Catalog

$ search_csc 3c273 radius=1 outfile=coma.tsv 

searchc_csc searches by location for sources included in the Chandra Source catalog. It can also query the CSC limiting sensitivity service to check for coverage when a source is not found.

$ obsid_search_csc 635 outfile=rho_oph_635.tsv download=all file=pha,arf,rmf

obsid_search_csc searches the CSC by Chandra OBS_ID. Both tools can also retrieve any of the observation or master level properties as well as the available data products.


... remove background flares

$ download_chandra_obsid 2233
$ chandra_repro 2233 out=./
$ dmextract "acisf02233_repro_evt2.fits[energy=500:7000][bin time=::254]" flare.lc op=ltc1  
$ deflare flare.lc flare.gti clean plot+
$ dmcopy "acisf02233_repro_evt2.fits[@flare.gti]" clean_evt2.fits

deflare has different flare cleaning options and parameters that can be adjusted to optimize flare rejection.

Users should carefully consider whether the time lost for their source is more important than the increased background during the flare.


... register (ie align) fields

$ download_chandra_obsid 2423,2233
$ chandra_repro 2423,2233 outdir=./
$ fluximage acisf02423_repro_evt2.fits acisf02423 bin=1 psfecf=0.9
$ wavdetect acisf02423_broad_thresh.img exp=acisf02423_broad_thresh.expmap psf=acisf02423_broad.psfmap \
  outfile="acisf02423_broad.src" scellfile="acisf02423_broad.cell" imagefile="acisf02423_broad.recon"\
  scales="1.4 2 4 8 12 16 24 32"
$ fluximage acisf02233_repro_evt2.fits acisf02233 bin=1 psfecf=0.9
$ wavdetect acisf02233_broad_thresh.img exp=acisf02233_broad_thresh.expmap psf=acisf02233_broad.psfmap \
  outfile="acisf02233_broad.src" scellfile="acisf02233_broad.cell" imagefile="acisf02233_broad.recon"\
  scales="1.4 2 4 8 12 16 24 32"

$ wcs_match acisf02423_broad.src acisf02233_broad.src cdfn_match.out  \
  wcsfile=acisf02423_broad_thresh.img method=trans radius=2

$ wcs_update pcadf099299289N003_asol1.fits updated_asol1.fits cdfn_match.out wcs=acisf02423_broad_thresh.img
$ wcs_update acisf02423_repro_evt2.fits none cdfn_match.out wcs=acisf02423_broad_thresh.img
$ dmhedit acisf02423_repro_evt2.fits op=add key=ASOLFILE value=updated_asol1.fits file=none

wcs_match has several options to control the quality of the cross match.

The dmhedit command is necessary to keep the updated output files in sync.


... create mosaic

$ download_chandra_obsid 2423,2233
$ chandra_repro 2423,2233 outdir=./
$ merge_obs acisf02233_repro_evt2.fits,acisf02423_repro_evt2.fits cdfn

merge_obs creates a merged event file as well as combined images and exposure maps. Users can also select their own tangent point location and binning.


... smooth image for publication

$ download_chandra_obsid 635
$ chandra_repro 635 635/repro
$ fluximage "635/repro/acisf00635_repro_evt2.fits[ccd_id=0:3]" acis_I_rOph
$ csmooth "acis_I_rOph_broad_thresh.img[bin sky=4]" none rOph.asm mode=h verb=2 clob+ sigmin=3 sigmax=5 sclmax=50

csmooth creates an adaptively smoothed, highly processed image. While not appropriate for photometric analysis it is very useful to help identify features in their images.


... model spectra (and images, and generic datasets)

sherpa> load_data("mysrc.pi")
sherpa> set_source(xsphabs.a1*xspowerlaw.p1)
sherpa> a1.nH=0.1
sherpa> freeze(a1)
sherpa> fit()
sherpa> plot_fit()
sherpa> conf()

sherpa is a general modeling and fitting application. It supports 1D and 2D datasets, various optimization methods, and produces confidence limits.


Still looking for more?

CIAO has over 200 tools and scripts!

CIAO supports specialized Chandra analysis such as Solar System Objects and Optical Monitor data as well as generic multi-mission and multi-wavelength analysis.