Chandra X-Ray Observatory
Skip to the navigation links
Last modified: 26 October 2016


Scripts Package:
List of Scripts and Modules

Data Retrieval | Data Preparation | Imaging Analysis | Grating Analysis | PSFs | Utilities | Modules

Data Retrieval

find_chandra_obsid Provides command-line access to the Chandra Footprint service, allowing users to find—and optionally download—publicly-available Chandra data by position or object name

Thread: How to Download Chandra Data from the Archive

download_chandra_obsid Provides easy command-line downloads of public Chandra data

Thread: How to Download Chandra Data from the Archive

search_csc Retrieve source properties and associated data products for a single position and radius from the Chandra Source Catalog.

Thread: Simple Command Line Access to the Chandra Source Catalog

obsid_search_csc Retrieve source properties and associated data products for a given ObsID from the Chandra Source Catalog.

Thread: Simple Command Line Access to the Chandra Source Catalog

list_datasetid Displays the LaTeX dataset identifier macro used to describe observations in papers written for AAS managed publications.

See: CDA Data Literature Links for more information.

download_obsid_caldb *EXPERIMENTAL* Downloads only the subset of Calibration Database (CalDB) files required to analyze one observation at a time. As additional observations are processed, the CalDB will grow incrementally as new files are accrued.

Data Preparation

chandra_repro Data reprocessing script that runs all the recommended analysis threads for a given set of observations.

Thread: Reprocessing Data to Create a New Level=2 Event File

acis_bkgrnd_lookup Find the ACIS "blank-sky" datasets in the CALDB matching your observation

Thread: Analysing the ACIS Background with the "Blank-Sky" Files

hrc_bkgrnd_lookup Find the HRC-I background event and spectrum files in the CALDB matching your observation

Thread: The HRC-I Background Event Files, The HRC-I Background Spectra Files

[New]blanksky Tailor an unscaled blanksky background file compatible with a given observed events file that combines and reprojects the necessary background files from the CalDB. The background scaling factors for each chip are calculated and stored in the file header.

Thread: Analysing the ACIS Background with the "Blank-Sky" Files, The HRC-I Background Event Files


Run either lc_clean or lc_sigma_clip from the command line to filter flares from a lightcurve. These lightcurve routines are provided by the lightcurves module.

Thread: Filtering lightcurves

r4_header_update Check the header of the input file and add the parameter block and/or SIM-related keywords introduced in the latest archive reprocessing.
splitobs Automates the steps necessary to separate multi-ObI and interleaved-mode observations into individual directories compatible with chandra_repro. For multi-ObI grating observations, the REGION block is attached to the level 2 event file.
summarize_status_bits Create an on-screen summary of the status bits in an event file to show the number of rows with each bit set and what the bit means.
gti_align For ACIS observations only. Synchronizes the input GTIs to the ACIS exposure boundaries. For most users, this is a tiny fraction of the total exposure time; however, if the observation has many GTIs then the accumulated error can be significant.
multi_chip_gti Create a single mutli-chip GTI from individual GTIs.
monitor_photom Create light curves from the aspect camera optical monitor data.

Thread: Processing ACA Monitor Window Data

[New]correct_periscope_drift Corrects for small (~0.1″) alignment drifts over the course of recent, long (>50 ks) observations of bright, on-axis (<2′) point sources with minimal pileup.

Imaging Analysis

fluximage Create exposure-corrected images and exposure maps for an observation


merge_obs; reproject_obs; flux_obs Combine an arbitrary number of ObsIDs to create exposure maps and exposure-corrected images. These scripts replace the deprecated merge_all script.


specextract Create source and background PHA or PI spectra and the associated unweighted or weighted ARF and RMF files for point and extended sources

Thread: Extract Spectrum and Response Files for an Extended Source or a Pointlike Source

combine_spectra Sums multiple imaging source PHA spectra, and (optionally) the associated background PHA spectra and source and background ARF files

Thread: Coadding Spectra and Responses

srcflux Compute various estimates of the net source flux, given an event file and a location.

Thread: Compute Net Counts, Rate, or Flux for Point Sources


A command-line interface to the save_instmap_weights Sherpa command. The output from this script can be used as input to the bands parameter of merge_obs, flux_obs, and fluximage or the spectrumfile parameter of mkinstmap.

Thread: Calculating Spectral Weights for mkinstmap

ecf_calc Extract encircled counts fraction profile, as a function of distance, for a circular region around a source position.
apply_fov_limits Creates an image of an event file using the limits from the FOV file.
readout_bkg Model the Out of Time (OOT) contribution of bright and extended sources to the ACIS background. The OOT events are detected during the ~0.04s it takes to transfer each exposure into the readout array during which source events are detected at a random CHIPY location.
[New]blanksky_image Create scaled background and background-subtracted images given an observation-specific blanksky background file and a reference image file.

Grating Analysis

A number of scripts for grating data analysis which use ISIS, the Interactive Spectral Interpretation System, are available from the MIT/CXC S-Lang Packages webpage. Note that ISIS is not packaged with CIAO; users have to download and install it separately.

combine_grating_spectra Combine Chandra gratings PHA files and their associated response files. Replaces add_grating_orders and add_grating_spectra.

Thread: Extract Coadded and Grouped Nth-Order Source & Background Spectra and ARFs and Add Grating Spectra and Average ARFs

add_grating_orders REMOVED This script has been removed in CIAO 4.8 as it has been replaced by combine_grating_spectra.
add_grating_spectra REMOVED This script has been removed in CIAO 4.8 as it has been replaced by combine_grating_spectra.
fullgarf Create a grating ARF for a particular order

Thread: Create Grating ARFs for HETG/ACIS-S and LETG/ACIS-S data

tg_bkg Create PHA background file for use in XSPEC

Thread: PHA Background File for XSPEC

mktgresp Create the ARF and RMF files for each grating-order and arm for Type II PHA file outputted by tgextract and tgextract2.
tgsplit Split a Type II grating PHA file into several Type I files
tgmask2reg; reg2tgmask Create custom region extraction masks for tgextract2.

Thread: Applying Customized Background Regions to LETG/HRC-S Observations

detilt Corrects the time-dependent tilt by adjusting the TG_D value of events from HRC-S/LETG observations by applying a linear correction as a function of TG_MLAM.

Thread: LETG/HRC-S Extraction Region and Recalibrated EEFRACs

dewiggle Removes small "wiggles" and straighten the dispersed HRC-S/LETG spectrum by correcting the TG_D value of events which cannot be corrected by the HRC-S degapping procedure in reprocessing.

Thread: LETG/HRC-S Extraction Region and Recalibrated EEFRACs

symmetrize Adjusts the TG_D values of all HRC-S/LETG events to make the cross-dispersion profiles more symmetric about TG_D=0 so that EEFRAC values will be accurate even when using narrower-than-standard spectral extraction regions.

Thread: LETG/HRC-S Extraction Region and Recalibrated EEFRACs


save_chart_spectrum Create a source spectrum for which you would like a PSF to be simulated; the spectrum is used as input to ChaRT

Thread: Preparing to Run ChaRT

make_psf_asymmetry_region Creates a region file indicating the location of the PSF asymmetry found in HRC and ACIS data, as discussed in the Probing higher resolution: an asymmetry in the Chandra PSF
psfsize_srcs Create a circular region that encloses the specified fraction of the PSF at specified energy.
src_psffrac Determine the PSF fraction a circular region encloses at a specified energy.
simulate_psf An interface to simplify running MARX for both raytrace PSF simulations or projecting ChaRT/SAOTrace rayfiles to the detector-plane for an existing observation.

Thread: Using MARX to Simulate an Existing Observation


acis_clear_status_bits Clear (set to 0) ACIS status bits before reprocessing with acis_process_events

Thread: Reprocessing Data to Create a New Level=2 Event File and the chandra_repro script.

acis_fef_lookup Find the FITS Embedded Function file for use by mkrmf

Thread: Extract a Spectrum and Response Files for a Pointlike Source and Step-by-Step Guide to Creating a Spectrum (among others)

acis_set_ardlib Update ardlib.par files to find bad pixel lists

Thread: Setting the Observation-specific Bad Pixel Files

check_ciao_caldb A tool to test the installation of the CIAO Calibration Database (CALDB)

Thread: What CALDB version are you using?

check_ciao_version A tool to test the installation of the CIAO and the Calibration Database (CALDB)
convert_xspec_user_model Compile an XSpec user-model for use in Sherpa.
get_fov_limits Calculates the sky limits (i.e. bounding box) for all the chips in a Chandra FOV file
get_sky_limits Find the required binning to match two images

Thread: Match the Binning of an Image


A script for splitting the source and background regions created by the roi tool.

Thread: An Image of Diffuse Emission

install_marx Automates the standard steps necessary to download, build, and install the latest version of MARX. MARX can be used to simulate Chandra observations and can used with ChaRT to simulate the Chandra PSF.


Python modules must be imported into an interpreter - such as ChIPS, Sherpa, or IPython - in order to use the functions. For example:

chips> from lightcurves import *
chips> lc_sigma_clip("lc_c7.fits")

The ciao_contrib module loads in all the routines from the sherpa_contrib, chips_contrib, and crates_contrib modules. The available modules include:

  • the ciao_contrib.runtool module for running CIAO tools as if they were Python functions;

  • the ciao_contrib.smooth module for smoothing 2D data (gaussian, top hat, box car, and using a kernel read from a file or an image);

  • the ciao_contrib.stacklib module for converting between CIAO stacks and Python arrays;

  • the ciao_contrib.caldb module for access to version information of the installed CALDB;

  • and the and modules for searching and accessing publically-available data from the Chandra Data Archive.



The ciao_utils module contains simple data-analysis routines: simple_stats and simple_hist.


Python class supports stacks of field-of-view (FOV) files that can be queried to see which ObsIDs include a given celestial position.


Python interface to the Chandra proposal tools: colden, precess, and dates.


Utility routines for ChIPS users including xlabel, ylabel, title, xlog, ylog, xylog, xlin, ylin, xylin, xlim, ylim, xylim, and add_ds9_contours.


Provides the add_fov_region routine for displaying a Chandra FOV file as a set of polygons in a ChIPS plot.


Provides a limited emulation of matplotlib pyplot module, allowing for pyplot commands to be used in ChIPS.


Python decorators for ChIPS, allowing multiple ChIPS commands to appear all together.


Provides routines to create a Cube Helix color lookup table, that monotonically increases in brightness.


Utility routines for Crates users, including write_columns, write_arrays, make_table_crate, make_image_crate, add_colvals, scale_image_crate, smooth_image_crate, read_ds9_contours, and simplecoordtransform.



The lightcurves module contains two routines for identifying flares in lightcurves:

  1. lc_clean: clean a lightcurve to match the ACIS "blank-sky" datasets;
  2. lc_sigma_clip: an alternative algorithm for cleaning lightcurves that uses sigma clipping to reject outliers.


sherpa_contrib.profiles Allows users to create radial (or elliptical) profiles of 2D imaging data, including model fits, from within Sherpa to allow users to visually inspect the quality of the results.

Thread: Radial and elliptical profiles of Image Data


Utility routines for Sherpa users. The sherpa_utils module contains routines for calculating the weights file for mkinstmap.


sherpa_contrib.xspec.local Load compiled XSpec user-model with Python lmod function.
sherpa_contrib.xspec.xsconvolve Provies an interface to the XSpec convolution models in Sherpa.

Provides the imextent routine that creates a linear 2D transform for an image, which can then be used in add_image.


Provides routines for converting between sexadecial format and decimal degrees, including dec2deg, deg2dec, ra2deg, deg2ra, and sex2deg.


The identify_name routine uses the CADC name resolver to try and identify the location of a source by name.


A collection of routines for spherical and cartesian coordinate systems, based on the code from the pyslalib module.

Last modified: 26 October 2016
Smithsonian Institute Smithsonian Institute

The Chandra X-Ray Center (CXC) is operated for NASA by the Smithsonian Astrophysical Observatory. 60 Garden Street, Cambridge, MA 02138 USA.   Email: Smithsonian Institution, Copyright © 1998-2016. All rights reserved.