.help cleansis Sep94 ftools.asca
.ih
NAME
cleansis -- Detect anomalous ASCA SIS pixel values and output a cleaned event file with an appended 'hot pixel' extension.

.ih
USAGE
cleansis datafile outfile cellsize logprob bthresh phamin phamax [options]
.ih
DESCRIPTION
This task reads an SIS event file and writes out a new file containing events only from pixels which pass a set of statistical tests. These tests are applied to an internal image generated by cleansis of each CCD chip. The anomalous pixel locations and counts are written to a "hot pixel" extension appended to the cleaned file.

Anomalous pixels in the chip images are searched for in two step. First, the counts in each pixel are first compared to the mean counts in the chip. "Hot" pixels with improbable counts (based on the PSF) are rejected. Next, the counts in each "test" pixel are compared to the surrounding (cellsize X cellsize) pixels. Test pixels for which the Poisson probability exceeds the threshold given by "logprob" are also rejected ("flickering pixels"). In the cases for which the surrounding pixels yield zero counts, the zero background threshold given by "bthresh" is applied. A PHA cut ( >= phamin, <= phamax) is applied to the events used in making the chip image (but not the filtered events!).

A good starting value for "logprob" is log(1/chipsize) ~= -5.25; for "cellsize" a reasonable number a timely search is 1/4 PSF core ~= 5 pixels. For these values a "bthresh" of 3 is safe, a lower threshold can be set using the expected background rate. 

Options:

The Poisson search may be iterated with "iterate". (For very bright sources(~> 10) or those observation acquired using SIS Area Discrimination, this option may need to be turned off to prevent cutting out the source core).

The pixels along the edge of the chip (cellsize/2 in) may be removed after the local search with "zeroedge".

Normally, the idea is to reject the events which fall in pixels flagged as 'anomalous'. The "dirtysis" option allows the events contained in the 'anomalous' pixels to be save in the event file instead. This is useful for examining the properties of the rejected pixel events.

If "cellsize" equals zero then a simple counts per pixel cutoff is applied. Any pixels in the chip image containing more then "bthresh" counts are rejected. 

.ih
PARAMETERS
.ls datafile [file name]
The ASCA SIS science file to be processed.
.le                                                                 
.ls outfile [file name]
The cleaned ASCA SIS science output file name, with appended hot pixel extension.
.le                                                                 
.ls cellsize [integer]
Search cell size in units of pixels. Must be an odd integer greater then one for the local search. A value of zero invokes the simple counts per pixel cutoff.
.le
.ls logprob [real]
The LOG of the Poisson probability threshold for rejecting a pixel. Must be negative (!). If cellsize = 0 zero this parameter is ignored.
.le
.ls bthresh [integer]
Zero background cutoff threshold. This threshold is applied when the local mean is zero. Check this number against the background count rate. If cellsize = 0 zero this parameter gives the fixed count cutoff threshold.
.le
.ls phamin [integer] 
The minimum PHA value to use in accumulating the chip image. This cut is not applied to the filtered data file.
.le
.ls phamax [integer] 
The maximum PHA value to use in accumulating the chip image. This cut is not applied to the filtered data file.
.le
.ls (iterate = yes) [boolean]
Iterate the Poisson clean?
.le
.ls (zeroedge = no) [boolean]
Zero the chip edge after clean?
.le
.ls (dirtysis = no) [boolean]
Write out to the output event file events from the rejected pixels instead of from the passed pixels?
.le
.ls (verbose = yes) [boolean]
Print out program steps and search summary?
.le
.ls (rawxcol = RAWX)  [string]
Raw X coordinate column name.
.le
.ls (rawycol = RAWY)  [string]
Raw Y coordinate column name.
.le
.ls (chipcol = CCDID)  [string]
Chip column name.
.le
.ls (timecol = TIME)  [string]
Time column name.
.le
.ls (detxcol = DETX)  [string]
Det X coordinate column name.
.le
.ls (detycol = DETY)  [string]
Det Y coordinate column name.
.le
.ls (skyxcol = X)  [string]
Sky X coordinate column name.
.le
.ls (skyycol = Y)  [string]
Sky Y coordinate column name.
.le
.ls (phacol = PHA)  [string]
PHA column name.
.le
.ih
EXAMPLES
 1. Clean an SIS file to a threshold probability of 5.7E-6, using a 5X5 background cell, and a 3 count zero background threshold. No PHA cut.  

cleansis datafile cleanfile 5 -5.25 3 0 4095

 2. Same clean as above but write out the events from the rejected pixels to the output file instead.

cleansis datafile cleanfile 5 -5.25 3 0 4095 dirtysis=yes

 3. Clean an SIS file to a global fixed threshold of 20 counts per pixel. Exclude PHA values greater then 500

cleansis datafile cleanfile 0 [] 20 0 500
.ih
BUGS
Warning: This is an analysis tool, not a program to run blindly: Clean, check, repeat.
.ih
AUTHOR
.ls Eric Gotthelf. From the original FORTRAN SISCLEAN of April 1993.
.ih
SEE ALSO
.endhelp
