Flag and relocate out-of-time CCD events
acisreadcorr infile outfile aspect x y [dx] [dy] [bkg] [bgroup] [geompar] [random] [verbose] [clobber]
The acisreadcorr tool handles the out-of-time events from a bright source. While ACIS reads out, it is still taking data. Photons detected during the readout are clocked out in the `wrong' row and so have incorrect CHIPY values. For a bright source, you get a streak all along the column (on both sides of the source, since some events are from the previous exposure).
The user specifies the sky coordinates of the source, and tolerances dx, dy in chipx and chipy. The program calculates the chip coordinates of the source as a function of time (using the aspect solution) and flags those photons within dx/2 of the source's CHIPX at the photon arrival time, but further than dy/2 away from the source's CHIPY (so that the source itself is not flagged).
We want to both remove the streak from the image (for cosmetic reasons and so that it doesn't affect source detection) and to retain the streak photons, since in principle they have more accurate timing information and are not affected by pileup.
However, removing all photons from the given coordinates just leaves a black streak instead of a bright one - we want instead to leave the background photons where they are. For this reason, the user can input a background PI spectrum in PHA file format. The program attempts to leave in the streak as background a set of photons consistent with the given PI spectrum and distributed evenly in time. Note that if there is another bright source in the streak or if dy is set too small, so that part of the primary source is in the region being corrected, the photons from that source will probably be the ones (erroneously) grabbed by the background algorithm.
It is important that the data subspace (specifically, the good time intervals) of the event file correctly reflect the data. In certain old level 1 files (evt1), the good times include long periods where no data was being taken, and the background algorithm will make an incorrect estimate of the rate; a workaround is to time filter the file on an appropriate time range, although in general it is probably advisable to just use the level 2 file as input to this tool.
If you set verbose=1, you will get a report on the results of the background estimation as a function of PI bin, allowing you to judge how successful that part of the algorithm has been.
Events flagged as in the region but not part of the background are adjusted so that their CHIPY coordinates are set to that of the source. The algorithm then moves a rectangle of "excess" streak photons to a line (constant aspect-adjusted CHIPY, variable CHIPX) near the user-supplied position (x,y). If you run this program, you may want to filter out the affected photons before doing accurate PSF work.
The event times of the moved photons are also crudely corrected to give "improved" photon arrival times. Whether these times are actually an improvement in the current release has not been well tested.
Most importantly, the STATUS values of both the "background" and "source" photons affected are modified, so that the user can isolate them and see what has been done. Bit 22 is used for background and bit 21 for source (counting from 0 at the right of the bit string, least significant bit).
To see the photons tagged as background,
dmcopy "fix.fits[status=10xxxxxxxxxxxxxxxxxxxxx]" flag_bkg.fits
To see the photons tagged as out-of-time source events,
dmcopy "fix.fits[status=01xxxxxxxxxxxxxxxxxxxxx]" flag_src.fits
The Remove the ACIS Readout Streak thread shows an example run of the acisreadcorr tool.
acisreadcorr evt.fits fix.fits aspect="@asol.lis" x=3468.0 y=4988.0 dx=2 dy=100 bkg=bkg.pi bgroup=25 clobber=yes
Correct the event file evt.fits, making fix.fits. Use the aspect solution files listed in the ASCII stack file asol.lis. The source is at SKY pixel coordinates 3468,4988; the streak to be corrected has a width of 2 pixels and avoids a 100 pixel area centered on the source. The background is estimated using bkg.pi; the spectrum is grouped with at least 25 counts per bin before being compared with the event data.
Detailed Parameter Descriptions
Parameter=infile (file required filetype=input)
Input file name
Name of the input (level 1 or 2) event file
Parameter=outfile (file required filetype=output)
Output file name
Name of the output event file
Parameter=aspect (file required filetype=input)
Aspect solution file or stack
The asol1.fits aspect solution files (usually a stack)
Parameter=x (real required)
SKY X pixel coordinate
X pixel coordinate of source.
Parameter=y (real required)
SKY Y pixel coordinate
Y pixel coordinate of source.
Parameter=dx (real default=)
Width in pixels of the region to be cleaned. The default value of 2 is about right for on-axis point sources.
Parameter=dy (real default=)
Streak avoidance region size
Number of rows to be avoided around the source. The default value of 100 seems to be reasonable for a 50 ks exposure on a 2 count per second source, and may be good for other combinations.
Parameter=bkg (file filetype=input)
Background PI spectrum
Spectrum to be used to flag counts as background. May be omitted.
Parameter=bgroup (real default=10)
PI spectrum grouping
The background spectrum is compared with the events in the readout streak in coarse PI bins, the bins are selected to have at least bgroup counts per bin in the input spectrum.
Parameter=geompar (file default=geom)
The name of the Pixlib Geometry parameter file.
Parameter=random (integer default=0)
Random number seed. 0 == use system time.
Parameter=verbose (integer default=0 min=0 max=5)
Verbose can be from 0 to 5, generating different amounts of output.
Parameter=clobber (boolean default=no)
If outfile already exists, clobber=yes will allow you to overwrite it.
It is important to note that the way acisreadcorr works, it is assuming that the source of the streak is inherently point-like. Even when working with off-axis data when one might set the "dy" parameter to a larger value, all the streaked events get relocated back to a single X,Y location. High surface brightness extended sources do also suffer from the same readout streak phenomenon; however, to correctly relocate where the event should come from would require knowing the source morphology which is beyond what acisreadcorr knows how to do.
- There is a bug in acisreadcorr such that it does not work correctly on observations that used a subarray.
Please refer to the "Remove the ACIS readout streak" thread for full details.
- Interleaved mode data: incorrect EXPTIME value in the streak events
The following bug applies only to interleaved mode data:
The computation of the TIME of the events in the streak is correct with the exception of the value of EXPTIME.
In one example of this bug, a value of 3.3 s was used instead of the correct value of 0.3 s. The exposure time of the secondary frames of obsid 107 is 3.3 s, but this run of acisreadcorr used the data from the primary frames (0.3 s exposure time).