CLEANSIS (Sep94)               ftools.asca              CLEANSIS (Sep94)

NAME
    cleansis -- Detect anomalous ASCA SIS  pixel  values  and  output  a
    cleaned event file with an appended 'hot pixel' extension.
    
    
    
USAGE
    cleansis  datafile  outfile  cellsize  logprob bthresh phamin phamax
    [options]
    
    
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.
    
    
    
PARAMETERS
    
    datafile [file name]
        The ASCA SIS science file to be processed.
    
    outfile [file name]
        The  cleaned  ASCA  SIS  science output file name, with appended
        hot pixel extension.
    
    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.
    
    logprob [real]
        The LOG of the Poisson probability  threshold  for  rejecting  a
        pixel.  Must  be  negative  (!).  If  cellsize  =  0  zero  this 
        parameter is ignored.
    
    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.
    
    phamin [integer] 
        The  minimum  PHA  value  to use in accumulating the chip image.
        This cut is not applied to the filtered data file.
    
    phamax [integer] 
        The maximum PHA value to use in  accumulating  the  chip  image.
        This cut is not applied to the filtered data file.
    
    (iterate = yes) [boolean]
        Iterate the Poisson clean?
    
    (zeroedge = no) [boolean]
        Zero the chip edge after clean?
    
    (dirtysis = no) [boolean]
        Write  out  to  the  output  event file events from the rejected
        pixels instead of from the passed pixels?
    
    (verbose = yes) [boolean]
        Print out program steps and search summary?
    
    (rawxcol = RAWX)  [string]
        Raw X coordinate column name.
    
    (rawycol = RAWY)  [string]
        Raw Y coordinate column name.
    
    (chipcol = CCDID)  [string]
        Chip column name.
    
    (timecol = TIME)  [string]
        Time column name.
    
    (detxcol = DETX)  [string]
        Det X coordinate column name.
    
    (detycol = DETY)  [string]
        Det Y coordinate column name.
    
    (skyxcol = X)  [string]
        Sky X coordinate column name.
    
    (skyycol = Y)  [string]
        Sky Y coordinate column name.
    
    (phacol = PHA)  [string]
        PHA column name.
    
    
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
    
    
BUGS
    Warning: This is an analysis tool, not a  program  to  run  blindly:
    Clean, check, repeat.
    
    
AUTHOR
    
    Eric Gotthelf. From the original FORTRAN SISCLEAN of April 1993.
        
        
SEE ALSO