eff2evt

Synopsis

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

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.

Example 1

eff2evt acis_evt.fits acis_mod_evt.fits
pbkfile=acisf063875928N002_pbk0.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.

Parameters

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. The dafile should also be set to "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".

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.

Changes in CIAO 4.5

• New Tool!

  The eff2evt tool calculates the energy flux in ergs/cm**2/sec for each input event, taking the quantum efficiency (QE) and effective area (EA) into account. The QE, EA, and flux values are recorded in new columns in the output file. The Calculate the Flux for a Position thread shows how to use the tool.

  This tool was initially developed for use with the Chandra Source Catalog.

Bugs

There are no known bugs for this tool.

See Also

calibration

ardlib

psf

psf

tools

acis_bkgrnd_lookup, acis_fef_lookup, acis_set_ardlib, add_grating_orders, add_grating_spectra, addresp, aprates, asphist, combine_spectra, dither_region, dmarfadd, dmextract, fullgarf, hrc_bkgrnd_lookup, make_instmap_weights, mean_energy_map, mkacisrmf, mkarf, mkexpmap, mkgarf, mkgrmf, mkinstmap, mkpsfmap, mkrmf, mkwarf, psextract, psf_project_ray, rmfimg, sky2tdet, specextract