/ ciao4.17 / ahelp / acisreadcorr.html

Jump to: Description · Example · Parameters · Extended Sources · Bugs · See Also

AHELP for CIAO 4.17

acisreadcorr

Synopsis

Flag and relocate out-of-time CCD events

Syntax

acisreadcorr  infile outfile aspect x y [dx] [dy] [bkg] [bgroup]
[geompar] [random] [verbose] [clobber]

Description

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.

Example

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.

Parameters

name	type	ftype	def	min	max	reqd
infile	file	input				yes
outfile	file	output				yes
aspect	file	input				yes
x	real					yes
y	real					yes
dx	real
dy	real
bkg	file	input
bgroup	real		10
geompar	file		geom
random	integer		0
verbose	integer		0	0	5
clobber	boolean		no

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=)

Streak width

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.

Extended Sources

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.

Bugs

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).