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
- ... setup for CIAO
- ... get help about a CIAO command or concept
- ... find observations of my source
- ... download data
- ... view the contents of a file (data, columns, keywords, blocks)
- ... extract spectrum for a point-like source
- ... extract high-resolution grating spectrum
- ... combine spectra
- ... convert count rate to flux
- ... estimate the flux for a point-like source
- ... make exposure corrected images
- ... create 3-color (RBG) image
- ... compute source centroid
- ... detect sources
- ... extract light curve (check for variability)
- ... make a radial profile
- ... search Chandra Source Catalog
- ... remove background flares
- ... register (ie align) fields
- ... create mosaic
- ... smooth image for publication
- ... model spectra (and images and generic datasets)
- ... do something else?
... 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:
- Go to http://cxc.cfa.harvard.edu/ciao/download/ciao_install.html
- Save the ciao-install script
-
$ bash ~/Download/ciao-install
- Answer the questions when prompted.
... 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
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 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.
... 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
... 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
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.