HEADAS help file

NAME

eeftable - Create an encircled energy function (EEF) file based on the output history file from the raytracing tool xrtraytrace

USAGE

eeftable infile outfile numRadVals deltaRadVals

DESCRIPTION

'eeftable' is a script that creates an EEF FITS file from an output history event file from the tool xrtraytrace. This script allows the user to create EEF files without needing to run the xrtraytrace tool repeatedly. The tool reads each row in the history file, determines which are valid double reflections (meaning it had a single reflection from the primary mirror, a single reflection from the secondary mirror, and hit the results plane). The radii and energy of those photons are then used to calculate the EEF.

INPUT

The input file must be in the same format as output from the tool xrtraytrace, containing information about the event history of every raytraced photon and details of its path. The history file must be large enough to contain at least one valid photon for each radius.

OUTPUT

The output file have an extension containing the EEF for each off-axis angle, azimuthal angle, and energy. Each row is the EEF for a radial value. Off-axis angle, azimuthal angle, and/or energy may be merged in the output file using the 'mgOffaxis', 'mgAzimuth', and 'mgEnergy' parameters. If any of these are set to true, EEF values across that parameter are merged. For example, if mgEnergy=true, there is only one extension for energy instead of one extension for each energy. The EEF values for each off-axis and azimuthal angle is averaged across all the energies. If all three mgOffaxis, mgAzimuth, and mgEnergy are true, then there is a single extension in the output file and all the EEF values are merged into a single extension. Each extension in the output file contains keywords listing the values used to create the file, such as CBD10000, CBD20000, CBD30000, and OFFAXIS, AZIMUTH, and Energy. If no parameters are merged, those keywords are the exact value of the off-axis angle, azimuthal angle, and energy for that extension. If any of those values of merged, the appropriate keyword reflects the range. The CBDnnnnn keywords contains the range from first unique value to last. The OFFAXIS, AZIMUTH, and Energy keywords are the average of the unique values. The TOTCTS keyword contains the total number of photons that contributed to the EEF for that extension. If any values are merged, the sum of the photons for each parameter is used. For example, if energy is merged, then all the photons that contributed to each energy iteration are summed.

PARAMETERS

infile [filename]: Name of the input photon history file.
outfile [filename]: Name of the desired output file containing EEF for history file.
numRadVals [integer]: The number of radial values to use, which measure the radii of circles centered on the peak of the photon distribution on the focal plane.
deltaRadVals [real]: The size of each radial value, in units of arsec.
(alpha = 0.0) [real]: Exponent to spectrally weigh the energies.
(mgOffaxis = no) [boolean, (yes|no)]: Whether or not off-axis angles should be merged into a single extension.
(mgAzimuth = no) [boolean, (yes|no)]: Whether or not azimuthal angles should be merged into a single extension.
(mgEnergy = no) [boolean, (yes|no)]: Whether or not energies be merged into a single extension.
(cleanup = yes) [boolean, (yes|no)]]: Whether or not to remove temporary files that were created in the process of merging the extensions.
(clobber = no) [boolean, (yes|no)]: whether to overwrite existing output file.
(chatter = 1) [integer]: Chatter level for output
(logfile = !DEFAULT) [string]: Set the name of the log file. Special values are DEFAULT and NONE for the default file name or no log file. The default is the name of the tool with a .log extension. For example, if running ahdemo, the default log file will be called ahdemo.log. If the parameter is set to an empty string, an error will be generated. If the parameter begins with an exclamation point (!), then any existing log file with the chosen name will be overwritten.
(debug = no) [boolean, (yes|no)]: Whether to display debugging information. If turned on, this parameter will also cause error messages to print a stacktrace in addition to the usual error message.
(history = yes) [boolean, (yes|no)]: Whether to record tool parameters in history keywords in all output files.
(mode = ql) [string, (h|hl|q|ql)]: Sets how automatic parameters are specified. Legal values are h, hl, q, and ql. Hidden parameters (h) are not presented to the user and take the default value from the parameter file, but can be specified as command-line arguments. Queried parameters (q) are prompted for input from the user, but give the default value from the parameter file as a choice. Either type with learning enabled (e.g. ql) cause the default value to change to that given in the previous run.

EXAMPLES

Create an EEF file from a photon history file, without merging.
```
        eeftable.pl in.fits out.fits 100 2.0
      
```
Where in.fits is a history file with off-axis angles 0, 15, and 30 arcmin, azimuthal angles of 0 and 45 deg, and energy values of 0.5, 2.0, 3.0, 4.0 keV. The output files contains 24 extensions: an extension containing the radial EEF values for each off-axis/azimuth/energy.
Create an EEF file from a photon history file, merging energy.
```
        eeftable.pl in.fits out.fits 100 2.0 mgEnergy=yes
      
```
Where in.fits is a history file with off-axis angles 0, 15, and 30 arcmin, azimuthal angles of 0 and 45 deg, and energy values of 0.5, 2.0, 3.0, 4.0 keV. The output file contains 6 extensions: an extension containing the radial EEF values for each off-axis/azimuth.

LAST MODIFIED

February 4, 2016