Skip to the navigation links
Last modified: December 2009

AHELP for CIAO 4.2


Context: tools


Compute the flux and look up the QE & effective area for event positions


eff2evt  infile outfile [energy] [pbkfile] [dafile] [mirror]
[detsubsysmod] [ardlibpar] [geompar] [clobber] [verbose]


eff2evt takes an input event file and looks up the QE (Quantum Efficiency) and EA (Effective Area) for the event position. The QE is determined from the chip coordinates and the EA from the off-axis angle; theta and phi are determined via a WCS transform on the DETX & DETY coordinates. The FLUX in ergs/cm**2/sec is also computed.

The output is a copy of the input event file with three additional columns: EA, QE, and FLUX.

This tool should only be used on imaging data. It is not appropriate for grating data, not even zeroth orders. There are two primary reasons: it does not include grating efficiencies, and the off-axis position for diffracted events does not correspond the the event position but to the zeroth order position, so the vignetting correction will be wrong.

Example 1

eff2evt acis_evt.fits acis_mod_evt.fits

For each event in acis_evt.fits, look up the QE and EA values based on the energy of each event, the chip position, and the off-axis angle. The parameter block filename is supplied so that the ACIS dead area correction is applied.

Example 2

eff2evt hrc_evt.fits hrc_mod_evt.fits energy=1.4

For each event in hrc_evt.fits, look up the QE and EA values for each event based on the chip position, the off-axis angle all at an energy of 1.4keV.


name type ftype def min max units reqd
infile file input         yes
outfile file output         yes
energy real   INDEF     keV no
pbkfile string input         no
dafile string input CALDB        
mirror string   HRMA        
detsubsysmod string            
ardlibpar file   ardlib        
geompar file   geom        
clobber boolean   no       no
verbose integer   0 0 5    

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

Input event file (imaging data only)

Input event file; must have SKY, CHIP,CCD_ID, and DET coordinates with appropriate WCS to get MSC(theta and phi). The SIM_X|_Y|_Z keywords along with correct DETNAM|INSTRUME.

Parameter=outfile (file required filetype=output)

Output event file

Contains a complete copy of the input event list (including data-subspace/GTIs). Three new columns are created: "EA" (effective area), "QE" (quantum efficiency), and "FLUX" (event energy convert from keV to ergs divided by the EA, QE, and livetime).

Parameter=energy (real not required default=INDEF units=keV)

Energy to use for responses

This parameter controls at what energy the QE and EA are determined. For ACIS where there is an ENERGY column in the input event file, setting this value to 'INDEF' will trigger the tool to use the value in the ENERGY column. However, for HRC which has no ENERGY column, you can select a mono-chromatic energy to be used for all the events.

Parameter=pbkfile (string not required filetype=input)

The parameter block file, which defines ACIS pixel clocking parameters, is a standard product of pipeline processing and is available for every observation. This file contains information which defines how long any pixel is exposed before being read-out, which is related to the probability that any pixel will be disabled ("deadened") by cosmic rays. See the description of the "dafile" parameter for more information on ACIS dead area.

Parameter block files have names of the form, "acisf146860615N001_pbk0.fits". The long string of digits refers to the time of observation (seconds since reference date) and "N001" is a revision number.

If the pbkfile is set to "NONE", no dead area correction is applied; dafile is assumed to have the value "NONE". If pbkfile is set to a valid file, then the dafile parameter must refer to a calibration file.

The pbkfile parameter is ignored for HRC data.

Parameter=dafile (string filetype=input default=CALDB)

ACIS "dead area" coefficients file, which may have the values "NONE" (no dead area computation), CALDB (for automatic lookup), or an explicit file reference to an ACIS "dead area" coefficients FITS table.

The ACIS dead area refers to a slight decrease in detector efficiency due to the background cosmic ray flux which temporarily renders some pixels useless. The calibration product is a coefficient (per CCD) which gives the fractional area lost (or "deadened") per second. Since the area lost increases with time, the magnitude of the effect depends upon the ACIS clocking parameters (number of rows, window location, frame-time) which determine how long a pixel was exposed to the background cosmic ray flux during the primary exposure and during electronic readout from the frame-store area. For full-frame timed-exposure, the dead area is about 4% at maximum CHIPY and about 2% at the readout. It is smaller for subarrays.

The ACIS clocking parameters required to scale the coefficients in the dafile are contained in the observation-specific parameter block file, which can be set by the associated parameter of this tool, "pbkfile". If dafile=NONE, then pbkfile=NONE is assumed.

The dafile parameter is ignored for HRC data.

Parameter=mirror (string default=HRMA)

The ARDLIB mirror parameter; can use additional qualifiers to change mirror response.

Parameter=detsubsysmod (string default=)

A modifier that is added to the detector name sent into ARDLIB.

Unlike some other ARDLIB enabled tools; eff2evt runs on multiple chips and as such does not have a detsubsys parameter. This parameter allows one to modify the internal detsubsys value to allow the response product to be modified. Things such as detector QE/U can be overridden (see "ahelp ardlib" for more information).

Parameter=ardlibpar (file default=ardlib)

The name of the ARDLIB parameter file.

Parameter=geompar (file default=geom)

The name of the Pixlib Geometry parameter file.

Parameter=clobber (boolean not required default=no)

Remove existing output files?

Parameter=verbose (integer default=0 min=0 max=5)

Controls amount of output sent to screen.


Two new parameters have been added to eff2evt to allow the ACIS dead area correction to be taken into account: "pbkfile" and "dafile". By default, the correction is "on": the parameter block file should be set in the pbkfile automatic. The default value of the dafile parameter is "CALDB".

Users who wish to continue analysis without the dead area correction should set both of these parameters to "NONE":

unix% pset mkarf pbkfile=NONE dafile=NONE


See the bugs page for this tool on the CIAO website for an up-to-date listing of known bugs.

See Also

acis_bkgrnd_lookup, acis_fef_lookup, acis_set_ardlib, acisspec, add_grating_orders, add_grating_spectra, asphist, dither_region, dmarfadd, dmextract, fullgarf, hrc_bkgrnd_lookup, make_instmap_weights, merge_all, mkacisrmf, mkarf, mkexpmap, mkgarf, mkgrmf, mkinstmap, mkpsf, mkpsfmap, mkrmf, mkwarf, psextract, psf_project_ray, rmfimg, specextract

Last modified: December 2009