.help detect    April97     ftools.rosat
.ih
NAME
detect --> detects all sources in a given PSPC FITS image having a
significance equal to or greater than a user specified significance,
and having a count rate equal to or greater than a user specified count
rate.

This tool is to be used only for PSPC observations.
    
.ih 
USAGE
detect evtmapfil expmapfil chanmin chanmax sig count_rate
    
.ih   
DESCRIPTION
DETECT will identify point sources in the field covered by a single PSPC
observation and create a point source mask for that field.  It uses SLIDING
BOX algorithm with the slight improvement that the box is a circle where
the radius is a function of off-axis angle.  The source identification
threshold can be set for both count rate and significance.  The program
sets a source radius at 90% encircled energy radius and the background
annulus at 2.5 times the 90% encircled energy radius.  If fewer than 4
counts are found in the background annulus, the average background for the
observation is used.  The significance is determined using POISSON
statistics, but does not consider the number of trials.
    
DETECT requires a PSPC image in some energy band along with an exposure
map in that energy band; the PSPC image can be constructed for eg. by 
using XSELECT on the PSPC events file (the *_bas.fits file) for a given 
observation.  The PSPC exposure map can be created by running the
FTOOL PCEXPMAP.

DETECT will generate 2 output files:
 
1. an image file containing the sources circled with 90% PSF
    
2. an ascii  file  containg the details of the sources, e.g., RA, DEC,
count rate, radial distances from the center of the image file etc.
            
    
    
WARNINGS ON USAGE
    
.ls Only PSPC observations are currently supported in this task.
.le

.ls DETECT can be used with the BROAD-BAND images (*_im1.fits) and exposure maps (*_mex.fits) available from the ROSAT data archive, but the headers in the primary arrays of these FITS files need to have included the values of the CHANMIN and CHANMAX keywords.  To do this first find the values of the PIMIN and PIMAX keywords (typically, PIMIN=11 and PIMAX=235). Create a file called chan_bnds.txt with 2 entries:
.nf
CHANMIN   11
CHANMAX  235
.fi
in which the entry after CHANMIN is the value of PIMIN, and similarly for CHANMAX.  Then use the ftool fmodhead to update the header of the broad-band image file and the broad-band exposure map:
.nf
% fmodhead rp900176n00_im1.fits+0 chan_bnds.txt
% fmodhead rp900176n00_mex.fits+0 chan_bnds.txt    
.fi
.le

.ih
PARAMETERS:
.ls(evtmapfil="EVTMAPFIL") [character string]
The  name  of the input FITS image file 
.le
.ls  (expmapfil="EXPMAPFIL") [character string]
The name of the input exposure map  file (obtained  running  the
tool PCEXPMAP, using the detmap file and not devignetted map).
.le
.ls  (instr="INSTR") [string]
Name  of  instrument  PSPC/HRI.   This  parameter is not used at
present as it was designed to be used when  both  HRI  and  PSPC
are  supported.   So,  it  is  basically  inactive  till  HRI is
supported.        
.le
.ls   (chanmin="CHANMIN") [integer]
Lower bound channel number.  This should  be  same  as  the  minimum
channel number, as given by the CHANMIN keyword in the FITS image 
or exposure map.
.le
.ls    (chanmax="CHANMAX") [integer]
Upper bound channel number.  This should be same as the maximum
channel number, as given by the CHANMAX keyword in the FITS image or
exposure map.
.le
.ls  (sig="SIG") [real]
Significance level wanted.
.le
.ls   (count_rate="COUNT_RATE") [real]
Threshold count rate.  Source  with  count
rate equal to or higher than this value will be returned by DETECT
.le    
.ls    (outfil = "detect.img") [string]
The output image filename with sources encircled.
.le
.ls   (qmask = "no") [boolean]
Whether  masking  file  is  needed.   Masking  file  is the file
containing the sources masked.
.le
.ls     (chatter = "9") [integer]
Flag to set the chattyness at execution.  Default value  is  set
to  9,  which  gives the user the task version and few warnings.
Lower/higher  values  produces  quieter/verbose  output  on  the 
screen.
.le
.ls (clobber = "false") [boolean]
Flag  specifying  whether  or  not  a pre-existing file with the
same name as that  requested as the output file from  this  task
will be overwritten.

.fi
.ih 
EXAMPLE:
In this example we run detect on rp900176n00_im1.fits, a broad-band image of the Carina nebula.  First we updated the headers with the values of the CHANMIN and CHANMAX keywords:
.nf
% fmodhead rp900176n00_im1.fits+0 chan_bnds.txt
% fmodhead rp900176n00_mex.fits+0 chan_bnds.txt    
.fi
where the file chan_bnds.txt contains 2 entries
.nf
CHANMIN   11
CHANMAX  235
.fi
then
.nf
% detect 
  --- Only PSPC is supported for FTOOLS4.0 (June, 1997)
  ------ Working on HRI support for later release
Enter filename for events map:[rp900176n00_im1.fits] rp900176n00_im1.fits 
Enter filename for exposure map:[rp900176n00_mex.fits]rp900176n00_mex.fits 
Enter lower PI channel no.:[11] 11
Enter upper PI channel no.:[235] 235
Enter statistical significance:[10] 6
Enter count rate threshold:[0] 
 ** detect 1.0.1
 source detection filename = diag_8_7.dat
 ...
 ... mask file mask_8_7.fits        exists!
 ... no. of source detected =  101
 ** detect 1.0.1 completed successfully
.fi

.fi
.ih    
BUGS:
Only PSPC observations are supported for the release in June 1997.  There are currently no plans to include HRI observations.
    
.fi
.ih    
SEE ALSO
help on SRCDETECT, PCEXPMAP

.fi
.ih 
LOG OF SIGNIFICANT CHANGES:
v1.0.0 (June, 1997) created
    
.fi
.ih   
PRIMARY AUTHOR:
.nj
Banashree M Seifert
.br
.nj
HEASARC, NASA/GSFC
.br
.nj
http://heasarc.gsfc.nasa.gov/cgi-bin/ftoolshelp
.ju
.endhelp
