Search https://cxc.harvard.edu/ciao/
Contact the CXC HelpDesk
Last modified: 19 December 2024

URL: https://cxc.cfa.harvard.edu/ciao/guides/quick_start.html
/ 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.

For more details see the Installing CIAO with conda thread.

Or using the ciao-install script:

For more details see the Installing CIAO 4.17 Using the ciao-install Script thread.

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

For more details see the Starting CIAO thread.

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

For more information see the Introduction to CIAO thread.

... find observations of my source

$ find_chandra_obsid 3c273

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.

For more details see the How to download Chandra Data from the Archive thread.

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

For more details see the How to download Chandra Data from the Archive thread.

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

For more details see the Making Images & Filtering Data: an Introduction to the Chandra Data Model thread.

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

For more details see the Extract Spectrum and Response Files for a Pointlike Source thread.

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

For more details see the collection of threads released to gratings data processing.

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

For more details see the Coadding Spectra and Responses and Add Grating Spectra and Average ARFs threads.

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

For more details see the Calculate source count rates and fluxes thread.

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

For more details see the Calculate source count rates and fluxes thread.

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

For additional details see the Multiple Chip ACIS Exposure Map and Exposure-corrected Image, HRC-I Exposure Map and Exposure-corrected Image, and HRC-S Exposure Map and Exposure-Corrected Image threads.

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

For additional details see the True Color Images in ds9 thread.

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

For additional details see the True Color Images thread.

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

For additional details see the Running wavdetect, Running celldetect, and Running vtpdetect threads.

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

For more details see the Basic Lightcurves thread.

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

For more details see the Obtain and Fit a Radial Profile thread.

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

For more details see the Simple Command Line Access to the Chandra Source Catalog thread.

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

For more details see the Removing ACIS Background Flares thread.

... register (ie align) fields

$ download_chandra_obsid 2423,2233
$ chandra_repro 2423,2233 outdir=./
$ fine_astro 2423,2233 outroot=my_out

[New] fine_astro automates the typical threads used to align Chandra data. It supports both both relative and absolute offsets by allowing the user to input an external reference source list.

For more details see the Correcting Absolute Astrometry thread.

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

For more details see the Making an exposure-corrected mosaic thread.

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

For more details see the CIAO gallery example.

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

$ sherpa

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.

For more details see the Sherpa website.

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.

/ ciao / guides / quick_start.html