Last modified: December 2022

URL: https://cxc.cfa.harvard.edu/ciao/ahelp/pileup_map.html
AHELP for CIAO 4.16

pileup_map

Context: Tools::Response

Synopsis

Compute image that gives indication of pileup.

Syntax

pileup_map  infile outfile [clobber] [verbose]

Description

The pileup_map tool computes a rough estimate of the amount of pileup. The output image is the number of counts per ACIS frame. The following table is used to convert from these image values to an estimated pileup fraction.

Relationship between Pileup Fraction and Count Rate

Pileup Fraction Count rate per frame Count rate per sec
1% 0.02 0.007
5% 0.1 0.03
10% 0.2 0.07

Note that the "Count rate per sec" column assumes a standard frame time of 3.2 s; these numbers are meant only to serve as a guide. The important number is the Count rate per frame time. Many ACIS observations are done with fewer than 6 CCDs and/or use a sub-array configuration that allows for shorter frame times.

In a severely piled-up case, the counts image can form a 'crater' where the apparent pileup is low. There should be a halo around this crater with a larger pileup indicator.

Details on how the tool works are available in the Pile-up Fractions and Count Rates document [PDF].


Example

pileup_map img.fits pileup.fits

Creates the pileup image based on the input img.fits file.


Parameters

name type ftype def min max reqd
infile file input       yes
outfile file output       yes
clobber boolean   no      
verbose integer   0 0 5  

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

Input counts image

The input image must be binned by 1 for the algorithm to work. The recommended image size is ~2048x2048. The file should not have any energy cuts applied, just the standard grade and status filtering.

It is recommended also that the tool be run on a chip-by-chip basis, to avoid incorrect results for cases where the observation experienced a number of dropped frames, as is often the case where pileup is a concern. Users may use the sky FOV file to create an image of the desired chip, e.g.

dmcopy "evt2.fits[ccd_id=3,sky=region(fov.fits)][bin sky=1]" img.fits

See "ahelp skyfov" for more information.

Parameter=outfile (file required filetype=output)

The output image

The output image has units of counts/frame.

Parameter=clobber (boolean default=no)

Clobber outfile

Remove outfile if it already exists?

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

The tool chatter level

Verbose can be from 0 to 5, generating different amounts of debugging output.


Caveats

The input image must be binned at single pixel resolution.

The input image should not have any energy filters applied. Since pileup skews event energies to higher values, all eneriges should be included when computing the pileup map.

The algorithm computes the count-rate using the LIVETIME in the image header. If the individual per-CCD LIVTIMn keywords are very different, then the LIVETIME value may not be applicable for some locations within the output pileup map.


Bugs

See Also

dm
dmfiltering
tools::core
dmappend
tools::image
centroid_map, dmfilth, dmimg2jpg, dmimgadapt, dmimgblob, dmimgcalc, dmimgdist, dmimgfilt, dmimghist, dmimgpick, dmimgpm, dmimgproject, dmimgreproject, dmimgthresh, dmmaskbin, dmmaskfill, dmnautilus, dmradar, dmregrid, dmregrid2, energy_hue_map, evalpos, hexgrid, map2reg, merge_too_small, mkregmap, pathfinder, vtbin
tools::region
dmcontour, dmellipse, dmimghull, dmimglasso
tools::response
mean_energy_map
tools::statistics
dmstat, imgmoment, statmap