Skip to the navigation links
Last modified: 3 April 2024


Scripts Package:
List of Scripts and Modules

Data Retrieval | Data Preparation | Imaging Analysis | Grating Analysis | PSFs | Utilities | Python Modules | Removed Code

Data Retrieval

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
Provides easy command-line downloads of public Chandra data
Retrieve source properties and associated data products for a single position and radius from the Chandra Source Catalog.
Retrieve source properties and associated data products for a given ObsID from the Chandra Source Catalog.
*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

Data reprocessing script that runs all the recommended analysis threads for a given set of observations.
Find the ACIS "blank-sky" datasets in the CALDB matching your observation
Find the HRC-I background event and spectrum files in the CALDB matching your observation
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.
Create a scaled background events file by using the scale factor calculated by and sampling the blanksky background file generated by the blanksky script for an observation; may also be used to "fill in the hole" with events.

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.

Check the header of the input file and add the parameter block and/or SIM-related keywords introduced in the latest archive reprocessing.
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.
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.
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.
Create a single mutli-chip GTI from individual GTIs.
Create light curves from the aspect camera optical monitor data.
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

Create exposure-corrected images and exposure maps for an observation
Combine an arbitrary number of ObsIDs to create exposure maps and exposure-corrected images. These scripts replace the deprecated merge_all script.
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
Sums multiple imaging source PHA spectra, and (optionally) the associated background PHA spectra and source and background ARF files
Compute various estimates of the net source flux, given an event file and a location.
Compute upper-limits for the detection of a source using data obtained from backgroun apertures in event lists, images, and exposure maps.

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.

Extract encircled counts fraction profile, as a function of distance, for a circular region around a source position.
Creates an image of an event file using the limits from the FOV file.
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.
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 Chandra gratings PHA files and their associated response files. Replaces add_grating_orders and add_grating_spectra.
Create a grating ARF for a particular order
Thread: Create Grating ARFs for HETG/ACIS-S and LETG/ACIS-S data
Create PHA background file for use in XSPEC
Create the ARF and RMF files for each grating-order and arm for Type II PHA file outputted by tgextract and tgextract2 or the specified Type I PHA file.
Split a Type II grating PHA file into several Type I files
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.
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.
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.


Create a source spectrum for which you would like a PSF to be simulated; the spectrum is used as input to ChaRT
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
Create a circular region that encloses the specified fraction of the PSF at specified energy.
Determine the PSF fraction a circular region encloses at a specified energy.
An interface to simplify running MARX for both raytrace PSF simulations or projecting ChaRT/SAOTrace rayfiles to the detector-plane for an existing observation.
Create a source region file from a simulated monochromatic PSF that is created with MARX.
Create an annular background region with a fixed number of counts based on the ECF-derived PSF size at a specified location.


Clear (set to 0) ACIS status bits before reprocessing with acis_process_events
Estimate the actual energy range for an ACIS observation.
Find the FITS Embedded Function file for use by mkrmf
Update ardlib.par files to find bad pixel lists
A tool to test the installation of the CIAO Calibration Database (CALDB)
A tool to test the installation of the CIAO and the Calibration Database (CALDB)
Generate a color-color diagram by computing hardness ratios from simulated spectra folded through a user-provided ARF.
Experimental: compile an XSpec user-model for use in Sherpa.
Experimental: convert a XSpec (xcm) save file to a file that can be used in Sherpa or a Python program. It is intended to simplify checking out fits from XSec in Sherpa, but is not guaranteed to create exactly the same results due to differences in how XSpec and Sherpa work.
Calculates the sky limits (i.e. bounding box) for all the chips in a Chandra FOV file.
Find the required binning to match two images.
Determine the approximate dither period and amplitude used during an observation.

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

Take a stack of roi output files and assign the overlapping area to "the best" source. Users can choose which metric to use to determine the source ranking: most counts, largest area, etc.

Compute simple statistics for events in each map region.

This script is used in dax to convert from DS9 regions to CIAO format. This may be useful for other users, but please be aware that interpreting a DS9 region file can be a surprisingly complex task.
Convert a region stored in physical coordinates, including FITS region files, into DS9-format regions in celestial coordinates. This can be especially useful when using srcflux with multiple observations which requires that user supplied regions be specified in celestial coordinates.
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

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

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

The ciao_contrib module loads in all the routines from the sherpa_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;

  • the ciao_contrib.psf_contrib module adds the PSF class and the psfFrac() and psfSize() functions to simplify the use of the CIAO psf module.

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

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.
Provides save_chart_spectrum, plot_chart_spectrum, and get_chart_spectrum which are used when using Sherpa to generate model spectra for ChaRT/SAOTrace. They are similar to the routines provided by sherpa_contrib.marx.
Provides save_marx_spectrum, plot_marx_spectrum, and get_marx_spectrum which are used when using Sherpa to generate model spectra for MARX. They are similar to the routines provided by sherpa_contrib.chart.
[New] Experimental: provides interactive control over Sherpa model settings within a Jupyter notebook.
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.

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

Load compiled XSpec user-model with Python lmod function.

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.

The TGPixlib Python introduced to help convert from sky coordinates to grating coordinates: dispersion angles and energy.

Removed Code

This section describes a number of scripts and routines that were included in the script package but have since been removed.

This script has been removed in CIAO 4.8 as it has been replaced by combine_grating_spectra.
This script has been removed in CIAO 4.8 as it has been replaced by combine_grating_spectra.
The list_datasetid script was removed in the CIAO 4.10 release. It displayed the LaTeX dataset identifier macro used to describe observations in papers written for AAS managed publications.

See: CDA Data Literature Links for more information.

This Python module has been removed in CIAO 4.12 as ChIPS functionality was replaced with Python's Matplotlib package.