Alexey's ACIS programs HOWTO

Alexey Vikhlinin

Feb 5, 2001

Contents

1  What can this software do?
2  Science thread
    2.1  Preparing the data
    2.2  Setting up parameter file
    2.3  Making image
    2.4  Making exposure maps
    2.5  Extracting spectra
3  Event filtering
    3.1  BADPIXFILTER - apply bad pixel filter
    3.2  FILTEVT - filter event lists
4  Spectrum extraction
    4.1  EXTRSPEC - extract a spectrum in a single region
    4.2  RUNEXTRSPEC - extract spectra in a set of regions and in individual chips.
    4.3  CALCARF - generate an ARF file for the PHA spectrum
    4.4  CALCRMF - generate the response matrix
5  Exposure and instrument maps
    5.1  Outline
    5.2  CHIPMAP - generate chip map in detector coordinates
    5.3  ASPECTHIST - create aspect histograms
    5.4  CONVASPECT - convolve the chip map with the aspect histogram
6  Troubleshooting
    6.1  I am getting a FITSIO error ...
A  Parameter files
    A.1  Parameter file format
    A.2  Command line versus parameter file arguments

1  What can this software do?

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,



??? 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).

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.

2  Science thread

2.1  Preparing the data

2.2  Setting up parameter file

2.3  Making image

2.4  Making exposure maps

2.5  Extracting spectra

3  Event filtering

3.1  BADPIXFILTER - apply bad pixel filter

This program applies the bad pixel filtering. This operation can be performed also by filtevt, but very inefficiently.

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.

3.2  FILTEVT - filter event lists

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.

4  Spectrum extraction

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.

4.1  EXTRSPEC - extract a spectrum in a single region

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.



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

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.

4.2  RUNEXTRSPEC - extract spectra in a set of regions and in individual chips.

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) regB

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

4.3  CALCARF - generate an ARF file for the PHA spectrum





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.

4.4  CALCRMF - generate the response matrix

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.

5  Exposure and instrument maps

5.1  Outline

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.

5.2  CHIPMAP - generate chip map in detector coordinates

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.





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.

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.



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

5.3  ASPECTHIST - create aspect histograms

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.

5.4  CONVASPECT - convolve the chip map with the aspect histogram

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

6  Troubleshooting

6.1  I am getting a FITSIO error ...



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

A  Parameter files

A.1  Parameter file format

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.

A.2  Command line versus parameter file arguments

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

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


Footnotes:

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


File translated from TEX by TTH, version 2.87.
On 5 Feb 2001, 22:16.