This document covers the usage of several programs I wrote in anticipation of the first Chandra data. The software kit includes programs and scripts that facilitate data filtering, image and spectra extraction, exposure map generation, and generation of ARF and RMF files for spectral fitting.
badpixfilter
Exclude bad pixels from the ACIS data.
filtevt
The script that makes it easy to filter photons by region, by GTI etc. You specify these filters in a human-understandable form in a parameter file, and filtevt will make the appropriate FITSIO filters on the fly.
extrspec
The script that extracts spectra by running FTOOL extractor.
runextrspec
Runs extrspec and optionally runs calcarf and calcrmf. Spectra are extracted in a set of regions and chips.
calcarf
Calculates the ARF file for the PHA spectrum.
calcrmf
Calculates the RMF file for the PHA spectrum.
chipmap
Create instrument maps in detector coordinates.
aspecthist
Extract the aspect offset histogram.
convaspect
Convolves instrument maps with aspect histogram,
All calibration data are defined in parameter files. You can have a
private copy of these data, or point the file names to a standard place.
???
What external packages and calibration data do I need?
You need FTOOLS and the most recent ZHTOOLS. You may also need to setup
your environment for using CIAO (no CIAO tools are called directly; the
CIAO environment is needed for a library that converts between different
CIAO coordinate systems).
This program is ACIS-only because the detector size is hard-coded.
Options:
-evtfile events.fits
Input events file name.
-o outfile
Output file name.
badpixfilter=bad_pixel_file
Bad pixels list. The bad pixel file is a text file with the format
ccdid chipxmin chipxmax chipymin chipymax
one rectangle per line.
This tool applies varies filters to the event lists. You can also define a binning filter in the FITSIO format and then filtevt outputs images.
Options:
-evtfile events.fits
Input events file name.
-o outfile
Output file name.
badpixfilter=bad_pixel_file
Bad pixels list. The bad pixel file is a text file with the format
ccdid chipxmin chipxmax chipymin chipymax
one rectangle per line.
filtbadpix=no
Bad pixel filtering may be time-consuming. You might want to do it once in the very beginning and then operate on clean event lists. The bad pixel file is still needed for programs that calculate exposure maps. So, we provide the option filtbadpix=no which means that event lists should not be filtered off the bad pixels, but exposure maps still should do.
NOTE: bad pixel filtering is performed very inefficiently. Please use the badpixfilter program to do that.
gtifile=gti.fits
File with the good time interval extension for time filtering. If not set, GTI will be searched for in the events file itself.
filtgti=no
Similar to filtbadpix=no.
-reg region_file
-exclreg region_to_exclude
SAOimage regions file that specify what areas (in sky coordinates) should be preserved or excluded. If any of these parameters is set, you need to set -regwcs
-regwcs img.fits
FITS image in whose frame reg or exclreg were made. This image must contain WCS in the header so that we know how to transfor the regions into the event file coordinate system.
-rowfilt rowfilter
Any valid FITSIO row filter.
-binfilt binfilter
Any valid FITSIO bin filter. If this is set the output will be an image.
Generally, you make spectra with the following procedure:
1) make an image in the sky coordinates. You can use filtevt for that.
2) Display the image, choose regions and save them to a file (with SAOimage or SAOtng or ds91).
3) Edit parameter file to point regwcs to your image. You will need to keep this image for the rest of spectral extraction.
4) Run extrspec or better, runextrspec, to extract spectra.
EXTRSPEC does not do any region filtering. You are supposed first to filter your events file (e.g., with filtevt) and then to use the filterevent list as an input to extrspec.
Program-specific options:
-evtfile filtered_events.fits
Region-filtered events file. Extrspec will extract the spectrum for all events in this file, with no region filtering whatsoever. Therefore, you normally should filter your events (e.g., with filtevt) and only then call extrspec.
-o outfile.pha
Output PHA file name
-chip chipname
Extract spectrum only for photons in this particular chip. Different formats of the chip names are accepted - acis-i3, s2 etc. There is a special ``chip'' acis-i which means all four i0-i3 together.
Parameter file options:
Normally, you won't need to change any of these options between different runs. Put them in the parameter file:
ecol=energy_column_name
Name of the spectral channel column. Usually, equals PI or PHA
gtifile=gti.fits
File with the good time interval. If not set, GTI extesion will be taken from the events file.
specbin=binfactor
Bin the spectral channels in the output spectrum by binfactor. If you want to do this to increase the number of photons per channel, use FTOOL grppha instead. However, you do need to bin PHA channels by two to match the current ACIS response matrices.
fixphaspec=yes/no
ACIS events file have the PHA maximum value of some 32000. Even if binned by two, this results in a spectrum with 16000 channels. Response matrices, however, cover only 2048 (binned by 2) channels. If fixphaspec=yes, the channels above maxspecchans in the PHA file will be discarded.
maxspecchans=maxchan
The number of spectral channels which should be in the output PHA file. Generally, you want fixphaspec=yes and maxspecchans=2048 if you extract spectral in PHA channels, and fixphaspec=no for PI channels.
bindetmap=binfactor
Extrspec puts an image of your region in detector coordinates into the primary header of the PHA file. This information is used for the subsequent ARF calculation. bindetmap sets the binning factor for this image. bindetmap=8, which makes 4¢¢ pixels, is a reasonable choice.
edetmapmin=energy_min,
edetmapmax=energy_max
Minimum/maximum energy (eV) for the map image. The default energy range is 500-2000 eV.
xcol=xcolname, ycol=ycolname
Name of the column with X- and Y- sky coordinates. default is X and Y.
xdetcol=xdetname, xdetcol=xdetname
Name of the column with X- and Y- detector coordinates. default is DETX and DETY.
After this, you will have those spec_s0.pha ... spec_s5.pha
with at least one photon. In the primary header of spec_*.pha there
is an image of intersection of your region and the selected chip.
There is a special ``chip'' called ACIS-I which is all four I0-I3 together.
How do I ...
How do I extract spectra in each chip separately?
1) Script runextrspec does that. 2) If you still want to use
extrspec, run something like
% foreach chip ( s0 s1 s2 s3 s4 s5 )
extrspec -evtfile temp.fits -o spec_$chip.pha -chip $chip @par.file
end
This is the program you want to use for spectral extraction. It takes an SAOimage region file, and runs extrspec for each region and for each chip. It also runs calcarf on the output spectra.
Program-specific options:
-o outkey
The root name for output files. For example, -o sp will produce output spectra named sp_reg.pha.
-regs SAOimage_region_file
The SAOimage region file with a set of regions for which you want to extract spectra. By default, runextrspec will use keywords ``reg1'', ``reg2'' and so on for the output names. You can change this by specifying the keyword name after each region:
circle(256,256,10) regA box(256,256,10,10,30) regBwill result in output spectra *_regA.pha and *_regB.pha.
-together
The region is not split into individual components. This is handy for the background spectra generation.
-chips chip_list
By default, runextrspec will run extrspec on each of the 9 chips for each region. If you know that you regions are located in chips s2 and s3, you can reduce the execution time by using -chips s2,s3.
-noarf
Do not run calcarf on the output spectra.
-dormf
Run calcrmf on the output spectra.
-noheader
If calcarf is being run, it updates the PHA headers to point to the correct RMF and ARF files. If you don't want this, use -noheader.
Other options:
runextrspec runs extrspec many times. Therefore, you have to set all the options required by extrspec expect for -reg and -chip. If -noarf is unset, runextrspec will also call calcarf, and so you need to provide options for this program as well.
Program-specific options:
-o outfile
Output ARF file
-phafile phafile
Input pha file
updateheader=no
Do not update the PHA file header. By default, the header is updated.
-correct_qe_cti yes
Apply a position-dependent correction for the CCD QE. By default, there is no correction. This option should be used with the FI chips and the focal plane temperature -110 C only.
-correct_qeu yes
Apply a position-dependent correction for the CCD QE by using the Quantum Efficieny Uniformity map.
ccd_qeu=qeu_file.fits
Calibration file for the QEU map.
wmap=wmap.fits
External weight map to be used if the WMAP in the PHA header is absent. This option serves to provide the possibility to generate ARFs for the CIAO-made PHAs.
This program generates the PI responce matrix for the input spectrum.
Program-specific options:
-o outfile
Output RMF file
-phafile phafile
Input pha file
updateheader=no
Do not update the PHA file header. By default, the header is updated.
-rmfshift shift
shift the matrix PI channels by that amount.
one_fef_in_reg=yes
Find the average detector coordinates of the photons and then calculate
the RMF at this point. The default behavior is to do a proper weighting
of the RMFs with the source flux.
The following two options are designed to fix the bug in the
response calibration data posted in the end of 1999.
-fixlowermf [yes]
This option tells to take the parameters of the negative
centriod Gaussian components from the regions close to the read-out. See
also -eminrmf.
-eminrmf minchan
Set to zero RMF fit components with centroids below minchan. As
of February 2000, this option defaults to 0 unless -fixlowermf
is in effect, in which case default minchan is -1000.
wmap=wmap.fits
External weight map to be used if the WMAP in the PHA header is absent. This option serves to provide the possibility to generate RMFs for the CIAO-made PHAs.
Calibration options:
-fptemp FP_temp
Focal plane temperature. Currently, supports only
fptemp=-110,-100,-90.
Exposure map is generated by running the three programs:
chipmap generates chip map in detector coordinates with or without vignetting.
aspecthist creates the aspect histogram from the aspect offset file.
convaspect convolves the chip mask (or any image for that matter) with the aspect histogram.
This program generates the chip map image appropriate for the aim point of your observation. Briefly, you select chips and chipmap puts them on the detector plane. If the bad pixel file is set, bad pixels and columns are subtracted from the map. Optionally, the map can be multiplied by the mirror vignetting and/or the relative average quantum efficiencies of the CCDs.
Program-specific options:
-o outfile
Output chip map name
-bin bin_factor
Set binning factor for the chip map. If bin_factor=4, the map will cover the whole detector plane with 2¢¢ pixels.
A preferred way to set the binning factor is with the -refimg parameter.
-refimg image.fits
Set the chip map binning factor to match image.fits. The program will try to read CDELT1 and CDELT2 keywords from the image and divide them by the default ACIS pixel size ( » 0.5¢¢) to determine the binning factor.
-chips list
Chip list to be included in the map. The argument is a comma separated list of chip names, i.e. s1,s2,i0,i2,i3. There is a special chip i which is equivalent to i0,i1,i2,i3.
-refspec spectral_model_file
The average vignetting and quinatum efficiency depend on the energy band and the source spectrum. This parameter points to the file that contains the user's spectral model. If it is set, you also have to define the energy band with -emin and -emax. If all three are set, the chip map will be multiplied by mirror vignetting and relative CCD QEs (see -refchip).
-refchip chip or -refccd chip
Average QEs are normalized so that the QE is 1 in the reference chip. This parameter sets the reference CCD. The default is I3
-emin emin, -emax emax
Set the energy band (in keV) for vignetting and CCD QE calculations.
useroll=yes
Rotate the output map by the average roll angle during the observation. Note: you normally don't need this. The chip map gets rotated during the convolution with the aspect histogram
General options:
evtfile=events.fits
The events file name. It will be opened to determin the PIXLIB Focal Plane system standard (e.g., fp-1.1) and the aim point. If you don't set -evtfile, you have to supply -aimpoint and -fpsys.
badpixfilter=bad_pixel_file
If this parameter is set, bad pixels and columns from the file will be excluded from the chip map.
If you include vignetting and CCD QE corrections to the chip map, you have
to supply the calibrations files hrma_onaxis_area=...,
hrma_vignetting=..., and ccd_qe_XX=... for each chip.
NOTE that rdhis is not included into XANADU Linux distribution. I
have a port to this platform. Contact me
(alexey@head-cfa.harvard.edu) if you need it.
How do I ...
How do I create the spectral model file?
1) Run XSPEC. 2) Select your model. 3) Set dummy response matrix (with
dummyrsp command). 4) Set the history file name: xhist myspec
5) dump model. 6) Quit xspec and run rdhis myspec.xhs. Save
output to a file. This file can be given to chipmap.
Can I ...
Can I use fake spectra as the spectral model?
No. The spectra produced by the XSPEC fake command do not contain
the energy boundaries of spectral channels.
Can I ...
Can I generate a vignetting map for a particular energy?
Yes. If you want it for, say, 2.0 keV, use the spectral model file:
2.0 1.0
This program reads the aspect file and saves the aspect histogram in separate roll angle bins. The prime reason for aspecthist existense is to save convaspect the trouble of reading and sorting the aspect offset file from Lev1 data.
Program-specific options:
-aspfile XXX_aoff1.fits
Set the aspect offset file from the Lev1 data.
-o outfile
Output aspect histogram file name.
-offsetbin binsize
Bin size (in 0.5¢¢ pixels) for the aspect offset histogram. It makes sense to use the same bin size as in the chip map file. Default is 1.
-rollbin rollbinsize
Bin size (in degrees) for histogramming roll angles. Default is 0.02 degrees which corresponds to ±0.25¢¢ shifts at 25¢ off-axis.
General options:
-gtifile gti.fits
List of good time intervals. NOTE: if this parameter is unset, the program issues a warning but continues execution.
The total duration of the good time interval is written to the output file as the EXPOSURE keyword.
This program convolves the chip map with the aspect histogram and applies roll angle rotations. The output map has the WCS keywords.
Program-specific options:
-chipmap chipmap.fits
Input chip map image.
-asphist aspecthist.fits
Aspect histogram file made by aspecthist.
-o outfile
Output map name.
inverse=yes
Apply inverse aspect shifts and roll angle rotations. This is useful if you want to convert sky regions into detector coordinates.
-noexp
Do not normalize the output map by the EXPOSURE keyword from the aspect histogram file. To normalize by exposure is the default behavior.
How do I ...
chipmap®aspecthist®convaspect
chain creates the exposure map that covers the entire focal plane. My
images are subsections of that plane. Can I generate exposure map
specifically for my image regions?
Yes. Generate a big map with
chipmap®aspecthist®convaspect
and then project it onto your image region. The following
ZHTOOLS command would do that
% projectimg from=bigmap.fits onto=image.fits out=smallmap.fits
Why do I ...
Why do I get a error message like
FITSIO status = 105: couldn't create the named file
failed to create the following file: (ffinit)
img.fits
Error while closing HDU number 0 (ffchdu).
This is because FITSIO cannot overwrite existing files. rm the
output file before running a program or put the exclamation mark in
front of the output file name:
% filtevt evtfile=events.fits -binfilter "[bin (X,Y) = 4]" \!img.fits
Here is a self-explanatory example of the parameter file:
xname=X ! Name of the X-column
yname =Y ! Name of the Y-column
zname = 'Z col' - name of the Z-column; note quotes because the value
has spaces.
zname = Z - this line is discarded because there is no letter in the
first position.
This line is discarded too because its begining is not in the name=value
format.
The next line tells to include the contents of /home/user/calpars.par
@include{/home/user/calpars.par}
You can use environment variables or the values of other parameters in the
parameter values. This is useful for the definition of directory trees:
CALDIR = /data/CALDB/data/chandra/
hrma_onaxis_area = $CALDIR/tel/hrma/bcf/effarea/hrmaD1999-07-22axeffaN0004.fits
@include{$HOME/calpars.par}
IRAF-style parameter files also can be parsed, although I did not do a lot of testing. Avoid IRAF par. files because they are usually incomprehensible.
My programs do not make a distinction between command-line and parameter file arguments. You are supposed to supply the parameter file as @par.file in the command line. The program behaves as if the par.file parameters are given in the command line. This provides an easy way of resetting several parameters without editing the par.file. For example,
% prog xname=XXX @par.fileis equivalent to
% prog xname=XXX xname=X yname=Y zname='Z col'and the program will determine that xname=XXX because this is found first.
Command line arguments may be given in the name=value (with optional spaces on either side of =) or in the -name value format.
1With SAOtng, make sure that you save the
region coordinates in pixels, not in degrees in the sky etc. With ds9, on
the contrary save the region in sky coordinates and do not set regwcs