celldetect: Input parameter description

bkgerrvalue

Data Type: real Units: events/pixel Default: 0

Allowed range: ≥ 0

Global value of background error; it is meaningful only if bkgvalue is also set. If set to 0, background error is assumed to be negligible and is not taken into consideration.

bkgfile

Data Type: string Default: ””

The name of the background file, containing in each pixel the total number of background events. This file has to be an image of the same size as the input data. If it is set to an empty string (and bkgvalue=0), then the background is estimated from infile, via calculating events in the frame surrounding the detect cell.

bkgvalue

Data Type: real Units: counts/pixel

Default: 0 Allowed range: ≥ 0

Global value for the number of background events per pixel. If set to a non-zero value, it overrides the background values in the file bkgfile. It is equivalent to having a flat background (i.e. having a background map with identical value in all pixels). If not used, it should be set to zero.

Exercise caution when using this parameter: experience shows that setting this parameter to too low a value results in numerous false detections, the number of which grows with increasing off-axis angle. cellfile

Data Type: string Default: ””

The name of an optional output file which will contain the filenames of images which have a value at each pixel of the size of the detect cell used at that location. Saving this image makes sense only if fixedcell is set to 0 (otherwise it will have the same value in each pixel). If the data are contained within 2048, the cellsize image will be conformal to the data. If the data exceed 2048, then successive files are blocked by increasing factors of two (each output file is a primary image of dimension 2048). centroid

Data Type: boolean Default: yes

Allowed Values: yes, no

Boolean flag that tells celldetect whether the quoted position of the source on output is to be the location of the detect cell (if set to ‘no’), or the centroid of events in the detect cell (if set to ‘yes’). Centroid has been found to be a very accurate estimate of position of single point sources. In the latter case, the tool also calculates the 1-σ sizes of the principal axes of the distribution of events in the detect cell and the position angle of the major principal axis.

clobber

Data Type: boolean Default: yes

Boolean flag, indicating whether the tool is allowed to overwrite exiting files. convolve

Data Type: boolean Default: no

Allowed Values: yes, no

If set to ‘yes’, the tool uses the convolution package, instead of a direct calculation of counts in the detect cell; i.e. the Fourier transform method is used, with the kernel being the detect cell (square tophat function). The use of default ‘no’ is recommended, since the tool runs considerably faster in the direct calculation mode. However, if a SNR map is desired, convolve must be set to ‘yes’ and a string other than ’none’ must be enetered for snrfile. The “convolution” option does not work with recursive blocking.

eband

Data Type: real Units: keV Default: 1.4967

Allowed range: 0.3 - 8.0

The energy band used to determine the PSF size. Changing the default is not recommended. For Chandra, we use 1.4967 keV as the default, since there is plenty of XRCF measurements at this energy and both detectors have their peak effective areas near this value. The allowed range is set by the PSF library.

eenergy

Data Type: real Default: 0.80

Allowed range: 0.01 - 0.99

The value of PSF encircled energy that is to be used as a basis for determining the cell size. The detect cell is a square box containing at least this encircled energy fraction with a side that is a multiple of three. A good default value is 0.80. For more detailed discussion on how the cell size is set, see the algorithm description.

expfile

Data Type: string Default: ””

Exposure map file name. Not implemented at present. findpeaks

Data Type: boolean Default: yes

Allowed Values: yes, no

Boolean flag which tells celldetect whether to perform a search for local peaks (virtually identical to lpeaks in PROS). If set to ‘no’ then celldetect outputs all detect cells with SNR higher than thresh (which usually results in each source being detected several times).

fixedcell

Data Type: integer Default: 0

Allowed values: 0, 1, or any positive integer which is a multiple of 3

The size of the detect cell. It should be set to a multiple of 3, or 1. If set to anything else than 0, it simply tells celldetect to run with constant cell size. Setting it overrides all information provided by xoffset, yoffset, eband, and eenergy.

infile

Required

Data Type: string Default: ””

The input file can be an event list or an image. For events-list data populating an area larger than 2048x2048, celldetect utilizes the ”recursive blocking scheme”: first the inner 2048x2048 pixel region of the data set is searched for sources, then the inner 4096x4096 pixel region (excluding the part already analyzed) is blocked by 2 and searched for sources, then the inner 8192x8192 is blocked by 4, etc. For each consecutive search the part that has already been searched for sources in higher resolution is removed from analysis, so that for each region on the data set just one blocking factor is used. Sources which appear very close to a blocking boundary may be detected twice. Recursive blocking has a number of limitations at this time: it is designed to work a full-sized level 1 pipeline outputs of size 8k x 8k (ACIS-I) or 32k x 32k (HRC-I). Analyzing data sets of size not a multiple of 2048 may produce unexpected results. If the aim point is not in the center of the dataset, some pixels will not be analyzed (eg: if the aim point is -100 pixels in X from the center, the rightmost 100 pixels in each row will be missed in the final sampling]. Recursive blocking works only for event lists. The tool presently assumes that the data are arranged in the ’X’ and ’Y’ columns. The tool depends upon TLMIN and TLMAX being set for these columns. In the case of recursive blocking, the input file specification must not have a binning directive or a spatial filter.

DataModel syntax for filtering1_{can be used. In order to use the datamodel filtering, you must explicitly}

specify the dataset (the file) and the datablock (extension) as well. For example, to analyze file foo evt.fits with an extension EVENTS, one has to use:

unix:celldetect "foo evt.fits[EVENTS]" ... kernel

Data Type: string Default: ”default”

Allowed Values: ”fits”, ”iraf”, ”default”

Format of the output source candidate list. Recognized options are: ‘default’ (indicating that output will be in the same format as input), ‘fits’, and ‘iraf’.

log

Data Type: boolean Default: no

Allowed Values: yes, no

Boolean flag. If set to ‘yes’, log output goes to celldetect.out; if set to ‘no’, log output goes to stderr. mode

Data Type: string Default: ”ql”

This is a parameter interface control variable. It is a generic parameter in all parameter files that define how to handle querried, “q” or “a” parameters. It is mainly for control of the debugger. Mode can be set to ’h’ for running non-interactively.

q - query the user each time; prompt for the parameter value even if the default is not null. l - learn the value and store it as the new default.

a - automatically take the mode of the next higher level. h - hide any prompting.

outfile Required

Data Type: string Default: ””

The filename of the output source list. psftable

Data Type: string

Default: ”$ASCDS CALIB/psfsize.fits”

File name of the table of PSF size data. The use of default is strongly recommended. snrfile

Data Type: string Default: ””

SNRmap output file. This option is meaningful only if convolve is set to ‘yes’. The pixels in SNRmap correspond to pixels in the data, and the values in them give the signal to noise ratio as calculated by the tool.

stall

Data Type: boolean Default: no

Allowed Values: yes, no

Boolean flag used for debugging. Users should leave it set to ‘no’. This parameter will be removed from future releases of the tool.

thresh

Data Type: real Default: 3

Allowed range: ≥ 0

Signal-to-noise threshold for sources. Only detect cells with signal to noise ratio higher than this value are considered source candidates.

verbose

Data Type: integer Default: 2

Allowed Values: 0-5

A number between 0 and 5. While the program is running, different levels of debugging information can be output. The verbose ”level” describes the verbosity of the output. The higher the value of verbose, the more elaborate the debug output. Value of 2 is a good default for normal running of the tool.

xoffset, yoffset

Data Type: integer Default: INDEF

Offsets of x- and y-axis. If both are set to INDEF, celldetect assumes that the off-axis angle should be calculated from the nominal RA and Dec of the data file. Setting them both to 0 indicates that the off-axis angle is to be calculated from the center of the data, nonzero values give the offset from the center of data. If ’a’ is the desired placement of the optical axis and ’b’ is the center of the data set, then xoffset = b.x-a.x, and yoffset = b.y-a.y.