How to use PWDetect INTRODUCTION PWDetect is the wavelet-based source detection code for Chandra X-ray data developed at the Osservatorio Astronomico di Palermo (OAPA). It performs a multiscale analysis of the data, allowing detection of both pointlike and moderately extended sources in the entire field of view. Various Chandra detectors are supported: HRC-I, ACIS-I, and individual ACIS chips (from both ACIS-I and ACIS-S); analysis of HRC-S images is not supported. PWDetect needs as input a valid Chandra FITS event file, and its associate FITS exposure map (mandatory), binned to 2 arcsec pixels. The exposure map is strictly needed since it contains important information used throughout the analysis. It should be computed using the CIAO task mkexpmap. The input event list is not read using the DataModel interface, and therefore filtering "on the fly" is not possible. Any time or energy filtering must be applied before calling PWDetect (and coherently to both event file and exposure map). We however discourage the use of spatial filters (sub-images), that may cause PWDetect to misidentify the image border and produce a large number of spurious detections. PWDetect uses the parameter file pwdetect.par to read/save its parameters. This file must reside in the current directory, and its name must not be changed. Command-line parameters will not work, but if you don't like interactive parameters setting you may use the `pset' command, as with any other parameter file. Beside input/output file names, PWDetect requires two most important input parameters to be set, namely the detection threshold and the maximum scale to be used in the analysis. The number of expected spurious detections depends sensitively on the choice of these parameters, and on the image integrated background. Useful plots are available at http://www.astropa.unipa.it/progetti_ricerca/PWDetect/ INPUT PARAMETERS: Input file name: a standard Chandra FITS event list Exposure map file name: an exposure map for the given observation, created with mkexpmap, of size 2048x2048 and with 2-arcsec pixels. To make it, use `pset mkexpmap xygrid="0.5:32768.5:#2048,0.5:32768.5:#2048"' for HRC-I, and `pset mkexpmap xygrid="0.5:8192.5:#2048,0.5:8192.5:#2048"' for ACIS-I. The same exposure map can be used when analyzing different ACIS chips in single-chip mode (see below). First threshold significance for detection: the initial detection threshold, used in the first search for candidate sources. Units are equivalent gaussian sigmas. Its recommended value should be at least 1.0 lower than the final threshold. The simulation (see enclosed plots) have been run for an initial threshold of 3.5 (the default value). Final threshold significance for detection: the final detection threshold, in equivalent gaussian sigmas. Its recommended value depends sensitively on the desired number of spurious detections per field, the background level, and detector. See the plots mentioned above. Maximum wavelet scale: the event list dataset is searched for sources at various spatial scales. The smallest scale is set to 0.25 arcsec for HRC, and to 0.5 arcsec for ACIS, to adequately sample the Chandra PSF. The largest scale can be chosen by the user, up to a value of 181 arcsec. Note that the scales actually used by PWDetect are all powers of sqrt(2), and other values will be rounded to the nearest power of sqrt(2). The recommended (best tested) value of the maximum wavelet scale is 16 arcsec. This value was also used to produce the plots of detection threshold vs. background mentioned above. ACIS single chip mode flag: while ACIS-I, with its four adjacent front-illuminated chips can be analyzed with PWDetect as a single detector (flag set = 0), this is not the case for the alternating front- and back-illuminated chips of ACIS-S. In this case, the individual chips need to be analyzed separately (flag set = 1). If the user needs, also individual ACIS-I chips may be analyzed using this option. ACIS single chip Identifier: if the single-chip mode is set, this is the number of the ACIS chip to analyze. Output source list filename root: the root file name for detected source lists (and overlay). Output background filename root: the root file name for output background maps. Output Log file name: file name for a short log of PWDetect run. PRODUCTS: 1) a list of detected sources (root_src, root_src.fits), in both ASCII and FITS format, including various computed source properties (position, counts, count rate, size, exposure time, background value, etc.). 2) an ASCII list describing at which individual scales was a source detected (root_signif), and to which significance level. 3) a DS9-style region file (root_overlay.ds9), for ready visualization of detected sources using the DS9 display. Also, an overlay file (bounds.ds9) is created to show the region being analyzed by PWDetect. 4) a short log file. 5) two FITS background maps: a zero-order map (bkgroot0.fits), and a second map (bkgroot.fits) with bright sources removed. Units are counts/square arcsec. The content of the detected source file (root_src[.fits]) is as follows: Column # 1: RA (deg) Right Ascension (decimal degrees) Column # 2: RA_err (deg) Error on RA (decimal degrees) Column # 3: Dec (deg) Declination (decimal degrees) Column # 4: Dec_err (deg) Error on Dec (decimal degrees) Column # 5: X (pix) Position X (physical pixels) Column # 6: X_err (pix) Error on X (physical pixels) Column # 7: Y (pix) Position Y (physical pixels) Column # 8: Y_err (pix) Error on Y (physical pixels) Column # 9: Offax (arcmin) Off-axis angle Column #10: Det_scale (arcsec) Highest-significance detection scale Column #11: Src_area (arcsec^2) Approximate source (core) area Column #12: Signif Detection significance (sigmas) Column #13: Src_cnt Total source counts Column #14: Cnt_err Error on source counts Column #15: Bkg_cnt Background counts in source core area Column #16: Src_ct_rate (cts/sec) Source count rate Column #17: Src_rate_err (cts/sec) Error on source count rate Column #18: Src_flux (cts/sec/cm^2) Source flux Column #19: Src_flux_err (cts/sec/cm^2) Error on source flux Column #20: Bkg_rate (cts/sec/arcsec^2) Background count rate Column #21: Exp_time (sec) Source weighted exposure time Column #22: Size (arcsec) Source size Column #23: Siz_err (arcsec) Error on source size Column #24: Extent Source extent (relative to PSF) Column #25: Ext_err Error on source extent Column #26: Src_num PWDetect source number SAMPLE SESSION: PWDetect needs about 180Mb RAM to run, so a machine with about 256Mb of memory is really required. Depending on your machine, it may be therefore necessary to set a memory limit higher than its default value, using the command: prompt> limit datasize 200M Then you are ready to run: prompt> chmod u+x pwdetect_osf prompt> pwdetect_osf Thu Jul 26 19:03:22 2001 Welcome to PWDETECT V1.0 Palermo Wavelet Detect for CHANDRA data Input file name (eventlist.fits): Final threshold significance for detection (5.31): Maximum wavelet scale (arcsec) [powers of sqrt(2)] (16.0): ACIS single chip mode flag (0=Full ACIS-I, 1=Single Chip) (0): ACIS single chip Identifier (0 to 9) (0): Output source list filename root (det): Output background filename root (bkgmap): Output Log file name (det_log): Exposure map file name (expmap.fits): Reading exposure map: expmap.fits ...done initial threshold = 4.00 sigmas final threshold = 5.31 sigmas Detector is ACIS-I ... reading data ... successfully read 20295 events performing detection at 11 scales, from 0.50 to 16.00 arcsec, in logarithmic steps by a factor sqrt(2) computing background image... done 51 sources at scale = 0.50 arcsec 69 sources at scale = 0.71 arcsec 69 sources at scale = 1.00 arcsec 98 sources at scale = 1.41 arcsec 113 sources at scale = 2.00 arcsec 143 sources at scale = 2.83 arcsec 143 sources at scale = 4.00 arcsec 118 sources at scale = 5.66 arcsec 105 sources at scale = 8.00 arcsec 86 sources at scale = 11.31 arcsec 63 sources at scale = 16.00 arcsec computing best source properties... done computing background image update... done 51 sources at scale = 0.50 arcsec 69 sources at scale = 0.71 arcsec 69 sources at scale = 1.00 arcsec 100 sources at scale = 1.41 arcsec 113 sources at scale = 2.00 arcsec 146 sources at scale = 2.83 arcsec 148 sources at scale = 4.00 arcsec 121 sources at scale = 5.66 arcsec 106 sources at scale = 8.00 arcsec 91 sources at scale = 11.31 arcsec 66 sources at scale = 16.00 arcsec computing best source properties... done Total number of detected sources = 105 Nominal effective area (cm^2) = 286.6157 Thu Jul 26 19:10:46 2001 total elapsed time: 444 sec prompt> The same output is saved in the log file. LIMITATIONS: There is a limit of 3 million photons maximum that can be handled by the standard PWDetect. The PSF parametrization is still preliminary, and will be refined in the near future (including also an energy dependence). FURTHER INFO: PWDetect for Chandra is largely based on its predecessor for ROSAT/PSPC data. You may find information about the theory behind it in Damiani et al. 1997 (ApJ, 483, 350), and tests on PSPC data in Damiani et al. 1997 (ApJ, 483, 370). An article specific to the Chandra PWDetect is in preparation.