/ ciao4.16 / ahelp / eff2evt.html

Jump to: Description · Examples · Parameters · Deprecation of 'pbkfile' parameter · Bugs · See Also

AHELP for CIAO 4.16

eff2evt

Synopsis

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

Syntax

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

Description

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 and zeroth order grating data. It is not appropriate for dispersed grating data. 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.

Examples

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.

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.

Parameters

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
rmfimg	file	input
rmfcut	real		0.01	0	1
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)

Deprecated. See below.

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 dafile parameter is ignored for HRC data.

Parameter=rmfimg (file filetype=input)

An RMF image, e.g. from the tool rmfimg

The flux returned by eff2evt is computed at the exact energy in the event file (or the parameter file value). This energy, though, is only a nominal energy. The true energy is not know, but the probability distribution of possible energies is described by the Response Matrix File (RMF). In energy ranges where small changes in energy can cause large changes in Area or detector efficiency (e.g. at low and high energy ranges and near Si and Ir edges), this can lead to anomalously low or high flux estimates. And including only a few events can substantially skew the results.

The rmfimg parameter allows a user to input an image of the RMF (e.g. created with the rmfimg tool). eff2evt uses the RMF image to determine a range of highly probable energies at which to compute the flux; the rmfcut parameter determines what probability cut-off to use. The output file then contains 3 additional columns: flux_lo, flux_hi, and flux_weighted. The flux_lo and flux_hi are the minimum and maximum flux values computed from the ensemble of highly probable energies. The flux_weighted value is the RMF probability weighted flux from all the probable energies.

This is an experimental feature. The hope is that this information can eventually be used to construct meaningful error bars on a per-event basis that can be propagated into further analysis tools. At the very least, if the flux and flux_weighted are significantly different, one should be suspicious of the fluxes eff2evt computes.

Parameter=rmfcut (real default=0.01 min=0 max=1)

RMF probability cutoff (see rmfimg)

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.

Deprecation of 'pbkfile' parameter

In CIAO 4.6, the ACIS parameter block file is no longer a required input to this tool. Therefore the 'pbkfile' parameter has been deprecated. The parameter has been retained for now but it is non functional.

This change is made possible by a series of header keyword updates that were made in Chandra standard data processing and are replicated in the chandra_repro script. Four new keywords: SUM_2X2, FEP_CCD, ORC_MODE, and OCLKPAIR have been added to the standard ACIS event file, that, in addition to existing keywords, provide the tool the information needed for the ACIS Dead Area calibration.

These keywords are required to use this tool in CIAO 4.6. Data from the archive with ASCDSVER newer than DS8.4.2 will already have these keywords. This will be the default for all but a few early observations. Users with data that was created prior to ASCDSVER=8.4.2 will need to follow one of these paths to use CIAO 4.6.

Retrieve most recent data from Chandra archive. All but a few datasets in the Chandra archive have been reprocessed to include these keywords (the earliest observations). The last bulk reprocessing included several updates including corrections for aspect "drift" within an observation as well as updated timing information. A summary of the updates can be found here: https://cxc.harvard.edu/cda/repro4.html
Reprocess the data through chandra_repro. This will update the headers with the new keywords and ensure that the other calibrations are consistent with the latest CALDB.
Just update the headers using the r4_header_update script. This will just add new keywords to the event file without any other calibration updates.

Bugs

There are no known bugs for this tool.