detect(1)

NAME
detect - Source extraction tool for CRUSH maps and more.

SYNOPSIS
detect criterion [options] <file>

  Parameters:

criterion
    A criterion for setting a false-detection rate goal.

[options]
    Various options, including pre-processing options of imagetool(1).

<file>
    A crush(1) or BoA FITS image.

DESCRIPTION
detect extracts point sources from a FITS image produced crush(1) or BoA. In addition to the source-detection options, the tool accepts all options of imagetool(1) for processing images before the extraction begins. The extraction algorithm implements a false-detection rate approach, that is it continues until a set false detection (or detection confidence) goal is reached. Each source extracted from the map has an assigned confidence level, based on the likelihood of a false detection at the same significance level in the given extraction area, as well as a cumulative number of false detections that are expected at levels above each source. When applied to crush(1) maps, the algorithm properly accounts for the effect of any map filtering/processing steps (including a filtered beam profile!), as long as these steps were also performed by other CRUSH tools (e.g. crush(1), imagetool(1)) to yield unbiased flux estimates. The output is an ASCII source catalog to the console, with some essential supplementaty information, which you can redirect to a file using the '>' operator on the command line, e.g.:

    detect false=3.0 my-image.fits > my-sources.cat

which will write a source catalog from my-image.fits to my-source.cat containing no more that 3 false detections. The program also creates a FITS image (named <source-name>.residual.fits) written to the same directory as the input image, containing the residuals after the source-extraction. The beams around the extracted sources are flagged, since these no longer contain useful information after the extraction took place.

CRITERIA
The following criteria can be used to specify how the false-detection rate goal is to be achieved. The criterion is a mandatory argument of detect.

confidence=
    Set a minimum confidence level for each detection (e.g. 0.95).

s2n=
    Set a minimum S/N level for all detections (e.g. 3.5).

nofalse=
    The confidence level that there is not a single false detection in the catalog (e.g. 0.95).

false=
    The expected number of false detections (e.g. 3.0).

help
    Provides a help screen similar to this one.

OPTIONS
All options of imagetool(1) are also used by detect. Additionally detect defines the following option(s):

-area=
    Specify the extraction area (in sq-armin) if it is different from the unflagged area of the supplied map.

-dynamic
    Re-estimate the noise with every extraction round.

-gaussian
    Use strictly Gaussian statistics for calculating cumulative false detections and confidence levels.

-symmetric
    Always use symmetric noise estimates. (The default is to use the negative-side distribution only for estimating the prevailing noise levels -- which is great if the positive fluxes are teeming with sources.)

BUGS
If you find them, please report them to the author (see below).

AUTHOR
Attila Kovacs <attila[AT]submm.caltech.edu>

SEE ALSO
crush(1), imagetool(1), coadd(1), show(1)