Improved Attitude Correction and Pileup Estimation for Suzaku Data

pile_estimate.sl (Download Script)

Syntax

unix% ./pile_estimate.sl [options] evtfile

 Options (must precede input file; arrays/ranges do not use () or []):

   --nofilter
         The selection of events with `vwhere' is skipped.
         If the gtk module is not installed, --nofilter is the default.
   --tbin=val
         The lightcurve is created with time bins of the total frame time
         (exposure, plus delay time, e.g., for burst mode observations),
         multiplied by an integer binning factor, tbin.  Rates, however,
         are per exposure time.  [Default=16]
   --save-lightcurve=val
          Save lightcurve into FITS file (ignored, if --nofilter is chosen).
   --pfrac=vals
         The minimum fractional pileup levels for the discretized pileup
         image.  [Default=0.01,0.02,0.05,0.1]
   --cont-pfrac
         Show a continuous image of the fractional pileup.
         (The --pfrac option is ignored if --cont-pfrac is used.)
   --only-save-pileup-img=val
         The estimated pileup fraction is only saved as a FITS image,
         but not displayed through ds9.
   --show-select
         Display the pileup image with selections applied at the end.
   --outfile=val
         The root name for the output files, i.e., val.flt (time filter),
         val.reg (region file), val.parms (suggested pileup parameters).
         [Default=input file name]
   --filter-file=val
         (Optional input.) The name of a file containing pairs of times to
         be considered good times.  Creates a new column, filter, that is
         passed to vwhere.  This column will contain 1's for times within
         these GTI values, and 0's for times outside of them.  This allows
         one to apply previously defined filters to the data. [default=NULL]
   --a-band=vals  [default: 0.5-1.5]
   --b-band=vals  [default: 1.5-3]
   --c-band=vals  [default: 3-9]
         The energy bands (keV) for the three colors in the lightcurve,
         specified as 'lo-hi', or, equivalently, 'lo,hi'
   --alpha=val
         The usual pileup alpha parameter (see the Chandra ABC Guide to
         Pileup, or Davis 2001, ApJ, 562, 575).  Affects the estimated
         pileup fractions and suggested model parameters [Default=0.5]
   -v, --version
         Print version.
   -h, --help
         This message.

Overview

pile_estimate.sl will create a pileup map out of a Suzaku event data file. First, as long as the --nofilter option has not been set, a lightcurve will be created in 3 energy bins. The energy bins (which can overlap) can be specified by the user, or they will default to 0.5-1.5 keV, 1.5-3 keV, and 3-9 keV. The lightcurves will be displayed by the VWhere tool, as shown here in this image:

Left: Counts vs. time (32 second bins) for a Suzaku observation, with a bright phase selected. Right: Color-color diagram, showing (in red) the selection made on the left.
The observation was taken with 2 second frames, with only 0.498 second integration per frame. Here we used the default binning (tbin=16, hence 16*2=32 seconds of elapsed time, but only 16*0.498=7.968 seconds of integrated time) for the lightcurve. The lightcurve can be as a rate which will be calculated for the good time integration, i.e., the 0.498 second on-time per frame in this particular case.

The user then uses the VWhere tool to select a time of roughly uniform rate and color. When the user is satisfied with the time/intensity/color selections, they click "Done", and the program writes to screen and to a file (outfile.flt) a time filter such as:

2.3274617100e+08        2.3274796300e+08
2.3275023500e+08        2.3275372300e+08
2.3275599500e+08        2.3275948300e+08
2.3276175500e+08        2.3276524300e+08
2.3276751500e+08        2.3276853900e+08
2.3276994700e+08        2.3277100300e+08
2.3277324300e+08        2.3277433100e+08
2.3277609100e+08        2.3277676300e+08
2.3277900300e+08        2.3278028300e+08

which can be used directly with tools such as xselect to filter the data file and create spectra and images based upon the VWhere selections. (If the --nofilter option is chosen, the resulting time file will only reflect the good time intervals [GTI] from the existing times in the GTI extension of the input event file.)

The pile_estimate.sl tool then takes these VWhere selections and applies a box-car smoothing over 3x3 pixel bins to create an image that is then displayed with the DS9 tool. Rather than being a rate image, this image is rescaled to be the estimated pileup fraction, as shown below:

The VWhere filtered, smoothed Suzaku image, showing pileup fraction at discrete levels.
Pileup fraction here is defined to be the ratio of events lost via grade or energy migration to the events expected in the absence of pileup. (I.e., it is 1-exp(-I), where I is the incident events. Note that the expression for I itself is dependent upon the assumed alpha paramter [default=0.5], and is only accurate to 3rd order in the detected count rate.)

As long as the --cont-pfrac option is not selected, the image displays discrete steps (user selectable via the --pfrac option) that represent the minimum pileup fraction in the displayed region, with the exception of the highest displayed value. This value corresponds to the image maximum, and is shown over regions at this maximum down to half way towards the next lowest displayed value.

The following is then displayed on the screen:

Create a circular, circular annular, or box (-box -box) region using physical coordinates.

   Enter 'y' when finished, or 'q' to finish without a region file:

One can quit without proceeding further, or create a region file. The tool supports a variety of different include/exclude regions: circle, ellipse, box, annulus, annular ellipse, and annular box. (The tool assumes that the entire chip is at first excluded, then applies all the include regions, and then applies all the exclude regions, regardless of the order in which the regions were input.) Regions must be in physical coordinates, and use the ds9/funtools format. Choosing 'y' will automatically save the region to a file (outfile.reg).

Here we show an example where we exclude most regions that have 8% pileup or greater. We center the annular region on the peak of the pileup. (Note that these data were first corrected using the aeattcor.sl tool.)

The VWhere filtered, smoothed Suzaku image, showing pileup fraction at discrete levels, with an annular region (excluding the central, most piled region) selected.
The tool then internally applies this region filter to the events to estimate the remaining levels of pileup. (One still needs to apply the region filter file when extracting spectra and/or lightcurves.) These estimates are translated into the values to which one should set pileup parameters (frame time, number of regions, PSF fraction) if using the ISIS pileup model when fitting spectra created from the filtered events. These values are printed to the screen and written to a file:

Suggested pileup model parameters for xis1.evt,
using region file xis1.evt.reg and filter file xis1.evt.flt :

   Frame Time (set_frame_time)   : 0.4980
   Effective piled PSF fraction  : 0.5942
   Equivalent number of regions  :    763
   Max equivalent pileup fraction: 0.0685 * 0.5942 = 0.0407

This functionality is experimental, and may not be 100% quantitatively accurate. (I.e., you might be better off excluding as much pileup as possible.) But assuming that one wanted to try applying this in ISIS, with the above values one would proceed as follows (assuming that the spectrum extracted with the pile_estimate.sl derived time and region filters is assigned as dataset 1 in ISIS):

isis> set_kernel(1,"pileup");
isis> set_frame_time(1,0.498);
isis> fit_fun("...");   % Create a model as usual
isis> set_par("pileup(1).nregions",763);
isis> set_par("pileup(1).psfrac",0.5942);

One would then proceed as normal for the model analysis.

Caveats

As for the aeattcor.sl tool, inaccurate results will be obtained if the event file under analysis contains data dropouts or periods of telemetry saturation that are not first removed. (As always, the event file GTI table must also be updated to reflect any such time filters.) The tool assumes that the exposure time of the image can be meaningfully estimated from the time intervals within the GTI extension of the input event file. `Unflagged' data dropouts, e.g., from telemetry dropouts, decrease the count rate (due to data losses), without decreasing the integration time, and hence potentially lead to an underestimation of the pileup fraction.

Note that severe pileup will not be accurately estimated. The tool assumes that one is in the low pileup fraction regime where increasing incident counts leads to increasing detected counts (albeit with the detected counts always being lower than the incident counts). For sufficiently high count rates, the detected vs. incident counts curve turns over, and cratering results. This is seen in this image (which also shows eveidence of partial image frames from telemetry dropouts):

A Suzaku observation that is very seriously affected by pileup. Notice the `crater' near the center of the image. Estimates of pileup fraction will be inaccurate in such regions.
Such craters must be excluded from the selected regions in order for the estimated residual pileup fraction to have any meaning whatsoever.

This page was last updated Apr 26, 2010 by Michael Nowak. Accessibility To comment on it or the material presented here, send email to mnowak@space.mit.edu.