CIAO 3.3 Contributed Scripts

• Introduction
• Installation
• Download the Scripts
• Scripts included in the Package (by category)

Introduction

Many data analysis tasks, particularly those that involve a formulaic procedure or many repetitions of a process, can be greatly simplified with scripts. Analysis scripts allow users to extend the functionality of a software package by writing custom "tools" to fit their specific needs. CIAO provides extensive support for the S-Lang scripting language, but shell and Perl scripts can also be used.

The scripts on this page are written and maintained by local CIAO users at the CXC. We provide them here because many users have found them helpful in their data analysis. In addition, scripts are sometimes written to address known problems or limitations of the CIAO software that affect many users. Most of the scripts have an associated analysis thread that explains their use.

We hope you will find these scripts helpful in your own data analysis. However, please be aware that these are not official CIAO tools, meaning that they are not fully supported by the CXC. When using one of these scripts, you should always be aware of exactly what the script is doing, as you are responsible for the validity of any scientific results obtained from it. If you find a problem with a script, please notify the CXC Helpdesk so that we can alert the script's maintainer. However, some scripts are no longer maintained by their original author, so we cannot guarantee when or if problems with scripts will be fixed.

Installation

The script installation process changed slightly with the CIAO 3.1 release. There is no longer the option to download individual scripts; users must install the full CIAO_scripts.tar package, which contains all the contributed scripts.

This change was made to simplify the process for users and to ensure seamless integration with CIAO. The installation instructions explain how to install the script package, as well as how to run individual scripts.

Download the Scripts

A VERSION.CIAO_scripts file is included in the scripts package. This allows you to check if you are working with the newest set of scripts:

unix% cat $ASCDS_CONTRIB/VERSION.CIAO_scripts 
15 May 2006  15:17:03 EDT

The VERSION.CIAO_scripts file is updated when you install a newer scripts package.

History of Changes

The Script Update History has a record of all changes made to the scripts package since the most recent CIAO release.

Scripts included in the Package (by category)

• Introductory
• Data Preparation
• Imaging
• Imaging Spectroscopy
• Grating Spectroscopy
• Sherpa

Introductory
Script	Associated thread(s)	Language	Version	Last update
getcounts.sl	Using SAOImage ds9	slsh	1.1	23-Mar-2005
	Example ds9 analysis script; calculates net counts in image
example1.sl - example12.sl	S-Lang tips help page	S-Lang		23-Oct-2001
	Code and examples of use from ahelp slang tips
Data Preparation
Script	Associated thread(s)	Language	Version	Last update
acis_bkgrnd_lookup	Using the ACIS "Blank-Sky" Background Files	slsh	1.8	8-Jul-2005
	Find the ACIS "blank-sky" datasets in the CALDB matching your observation; acis_bkgrnd_lookup help page
acis_set_ardlib	Use Observation-specific Bad Pixel Files	slsh	1.5	21-Jan-2005
	Update ardlib.par files to find bad pixel lists
analyze_ltcrv.sl	Filtering Lightcurves	S-Lang	1.5	25-Jun-2003
	An alternative algorithm for cleaning lightcurves
lc_clean.sl	Using the ACIS "Blank-Sky" Background Files	S-Lang	1.9	20-Jun-2003
	Clean a lightcurve to match the ACIS "blank-sky" datasets
monitor_photom	Processing ACA Monitor Window Data	slsh	1.0	23-Jun-2005
	Generate a photometric light curve for a Chandra target which was observed using an ACA monitor window.
show_tgain_corr	Why topic: ACIS Time-dependent Gain	slsh	1.4	21-Sep-2004
	Determine the size of the ACIS time-dependent gain adjustment for a given source location.
show_tgain_corr.sl	Why topic: ACIS Time-dependent Gain	slsh	1.5	15-May-2006
	Called by show_tgain_corr. Determine the size of the ACIS time-dependent gain adjustment for a given source location. The calibration files used by this script were released in CALDB 3.2.2.
Imaging
Script	Associated thread(s)	Language	Version	Last update
acis_expmap	Detecting Sources in Imaging Observations - Using celldetect	sh	3.3	27-Sep-2005
	Generate ACIS exposure maps for celldetect recursive blocking
color_image	Create A True Color Image	sh	3.0	27-Feb-2001
	Make a color JPG image
get_sky_limits	Match the Binning of an Image	slsh	1.6	2-Nov-2004
	Find the required binning to match two images; get_sky_limits help page
merge_all	Use merge_all Script to Compute ACIS Exposure Maps and Fluxed Images; Merging Data from Multiple Imaging Observations	Perl	3.3	27-Sep-2005
	Combine arbitrary number of ObsIDs, create exposure maps and fluxed images; merge_all help page
mkBgReg.pl, mkSubBgReg.pl	Create an Image of Diffuse Emission	Perl	1.1	11-Oct-2002
	Create a smoothed, exposure-corrected image of diffuse emission
spectrum.sl	Calculating Spectral Weights	S-Lang	2.1	11-Jul-2004
	Calculate spectral weights for creating an instrument map using S-Lang
sstats.sl	Calculating Statistics of Images	S-Lang	0.4	4-Oct-2001
	Use S-Lang to calculate statistics of images
Imaging Spectroscopy
Script	Associated thread(s)	Language	Version	Last update
acis_fef_lookup	Extract ACIS Spectra for Pointlike Sources and Make RMFs and ARFs and Step-by-Step Guide to Creating ACIS Spectra (among others)	slsh	1.11	21-May-2003
	Find the FITS Embedded Function file for use by mkrmf; acis_fef_lookup help page
acisspec	Extracting Extended Source Spectra and Responses and Coadding Spectra and Weighted Responses	sh	3.6	16-Feb-2006
	Extract point-like and extended ACIS spectra with weighted responses or coadd acis spectra; acisspec help page
psextract	Extract ACIS Spectra for Pointlike Sources and Make RMFs and ARFs	sh	3.3	27-Sep-2005
	Extract source and background ACIS spectra for point-like sources and build associated ARFs and RMFs; psextract help page
regions.sl	Displaying the FEF Regions Covered by a Source	S-Lang	1.2	17-Jul-2003
	Display the FEF regions covered by a source
show_wgt.sl	Weighting ARFs and RMFs: multiple sources	S-Lang	1.2	22-Oct-2001
	Examine the weights file created by mkwarf
Grating Spectroscopy
Script	Associated thread(s)	Language	Version	Last update
add_grating_orders	Extract Coadded and Grouped Nth-Order Source & Background Spectra and ARFs	sh	2.2	22-May-2001
	Add positive and negative diffraction orders of a grating PHA spectra and the corresponding ARFs; add_grating_orders help page
add_grating_spectra	Add Grating Spectra and Average ARFs	sh	3.2.0	9-Dec-2004
	Add two source and background grating PHA spectra, average the corresponding ARFs, and group the coadded spectrum; add_grating_spectra help page
chips_tgscript.ch		S-Lang	1.0	20-Oct-2001
	Example of grating-event data inspection, using ChIPS and S-Lang
fullgarf	Create Grating ARFs for HETG/ACIS-S and LETG/ACIS-S data	sh	3.3.1	13-Sep-2005
	Create a grating ARF for a particular order; fullgarf help page
mk_tggrid	Create Grating ARFs for HETG/ACIS-S, LETG/ACIS-S, LETG/HRC-S, and LETG/HRC-I data	sh	1.0	7-Dec-2001
	Extract spectra into a grid for use in tools like mkgarf
tg_bkg	Create PHA Background File for Use in XSPEC	sh	1.1	28-Jul-2005
	Create PHA background file for use in XSPEC
tg_osort_img	Create an Order-Sorting Image	slsh	0.7	12-Dec-2005
	Create an image that shows the density of events in different orders
tg_scale_reg	Measure Grating Dispersion Distance	slsh	1.4	12-Dec-2005
	Display dispersion distance on the sky image of a grating observation
Sherpa
Script	Associated thread(s)	Language	Version	Last update
chart_spectrum.sl	Preparing to Run ChaRT	S-Lang	1.0.1	18-Feb-2004
	Create a source spectrum for input to ChaRT
paramest.sl	Computing Confidence Levels	S-Lang	1.12	2-Nov-2004
	Simplify the calculation of confidence levels using a S-Lang interface to the Sherpa parameter-estimation commands; paramest help page
setplot.sl	Changing the look of Sherpa plots using setplot.sl	S-Lang	1.3	2-Nov-2004
	Simplify configuration of Sherpa plots; setplot help page
sherpa_plotfns.sl	Fitting FITS Image Data Advanced customization of Sherpa plots	S-Lang	1.29	2-Nov-2004
	Customize Sherpa plots using S-Lang function hooks as described in ahelp sherpa_plotfns. Create a radial (circlular or elliptical) profile of a two-dimensional fit; see the help pages for the plot_rprof() and plot_eprof() functions.
sherpa_utils.sl	Changing the grouping scheme of a dataset within Sherpa Calculating K-corrections using S-Lang and Sherpa	S-Lang	1.26	2-Nov-2004
	A collection of useful functions for users of Sherpa. Includes: re-grouping spectra within Sherpa; calculating the k-correction of a model; as well as other miscellaneous functions. See ahelp sherpa_utils for more information.
simspec	Simulating 1-D Data: the S-lang Script simspec	slsh	1.1	9-Feb-2006
	Create and fit a simulated PHA spectrum; simspec help page