NAME

pileest - creates an estimated pileup fraction image from an event file

SYNOPSIS

pileest <eventfile> <outmap> <inreg> <outreg> <alpha> <maxpilefrac>

DESCRIPTION

This tool creates an estimated pileup fraction image, given an event file. It does so using a third order approximation for grade migration. If run interactively, the user can create a circular pileup exclusion region. If not run interactively, the best guess pileup exclusion region is created based on the maxpilefrac parameter. If an input region is also specified, the tool will estimate the best input parameters for the Xspec 'pileup' model for the combination of the input region and created pileup exclusion region.

The steps performed to create the estimated pileup fraction image are as follows:

  1. Run the extractor ftool on eventfile to produce an un-binned image.

  2. Convert image to counts/3x3 pixels/frame using the fboxcar and ftimgcalc tools and the frame time (TIMEDEL keyword usually).

  3. Calculate the expected counts in the absence of pileup per 3x3 pixels per frame, using a 3rd order grade migration approximation:
    N' = N + N^2*(2-<alpha>)/2 + N^3*(2*<alpha>^2-9*<alpha>+9)/6

    where N' is the expected counts, N is the counts/3x3 pixels/frame calculated in the previous step, and <alpha> is the grade migration parameter.

  4. Calculate a map (image) of the estimated pileup fraction using the fraction of events affected by either grade or energy migration, a.k.a.:
    f_t = 1 - exp( -N' )

If the interactive parameter is set to 'yes', the image will be displayed (see also contpfrac and pfrac_vals parameters). A single contour will be overlaid at the level where the estimated pileup fraction is equal to the value of the maxpilefrac parameter. If an input region is specified, it will also be overlaid on the displayed image.

The user will then be asked to create a pileup exclusion region by selecting the center of the region, and a point on the circle. The resulting region will be saved to outreg.

If the interactive parameter is set to 'no', then an exclusion region will be automatically created. It is estimated as the minimum circle required to exclude pixels with >=maxpilefrac fractional pileup.

Lastly, if an input region is specified, the best estimates for input to the Xspec 'pileup' model will be printed to the terminal.

NOTE: Not all region file formats are supported for the inreg parameter. In particular, ds9 style regions where "global" properties are declared, or the coordinate system is defined on a separate line from the region shapes, are not yet supported.

CAVEATS

This tool can give misleading results if severe pileup (e.g. a PSF "hole") is present in the input event data. Other means of accounting for pileup are required in this case.

The GTI of the event file (or AND'ed with the GTI specified in the gtifile parameter) should represent times of roughly uniform rate and spectral "color". Otherwise the grade migration approximation is not valid.

The automatic pileup exclusion region generator assumes that there is a single source represented in the input event file. If this is not the case, the automatic region may be incorrect, or the tool may fail outright.

PARAMETERS

eventfile [file]
Input event file for which to make estimated pileup fraction image. This event file should contain only a single source if an automatic exclusion region is to be generated.

outmap [file]
Output estimated pileup fraction image.

inreg [file]
Input source inclusion region. If set to 'NONE', then the estimated best parameters for the Xspec 'pileup' model will not be calculated.

outreg [file]
Output region file. This file will contain the user created circular exclusion region if interactive is set to 'yes', or the automatically created exclusion region if interactive is set to 'no'.

alpha [real]
Grade migration parameter (alpha). See DESCRIPTION.

maxpilefrac [real]
Pileup fraction to contour on displayed pileup fraction map. If interactive is set to 'no', the region created in outreg will be the minimum circle required to exclude pixels with >=maxpilefrac fractional pileup.
(gtifile) [file]
Additional GTI file to filter events. This will be AND'ed with the GTI in the event file. Can be any time selection file recognized by the extractor ftool (see fhelp extractor).

(interactive) [bool]
Interactively create pileup exclusion region?

(contpfrac) [bool]
When displaying pileup fraction image, use continuous levels? This is for display purposes only.

(pfrac_vals) [string]
Levels to use when displaying discretized pileup fraction image (comma or space delimited list). This is for display purposes only.

(plotimage) [bool]
If set to yes, a plot of the estimated pileup fraction image with any regions overlaid. The type of plot output (e.g. post-script, gif) can be controlled using the plotdevice parameter.

The filename will be the same as the outmap parameter, but with a file extension that matches the plot type specified in the plotdevice parameter.

(plotdevice) [string]
Type of plot file to create. This must be a variant of the following PGPLOT file devices: GIF (e.g. '/gif'), Postscript (e.g. '/ps'), X-window plot file (e.g. '/wd'), or PPM (e.g. '/ppm'). The sub-types of these are also supprted (e.g. '/vgif', '/cps', 'vwd', etc.)

(cleanup) [bool]
Remove temporary files?

(chatter) [0,5]
Terminal chat level. 0 => no chatter; 5 => debugging

(clobber) [bool]
Overwrite existing output files?

(history) [bool]
Add history keywords?

NOTES

This tool is based heavily on the ISIS script pile_estimate.sl by John Davis. See:

http://space.mit.edu/cxc/software/suzaku/pest.html

for information on the original tool.

LAST MODIFIED

July 2010