EXTRACTCLUMPS - Extract previously identified clumps of emission from an NDF

Description:

This application extract previously identified clumps of emission from a 1, 2 or 3 dimensional NDF. Usually, FINDCLUMPS will first be used to identify the clumps within a given array, and then EXTRACTCLUMPS can be used to find the parameters of the same clumps in a second array.

Two input NDFs are supplied; the NDF associated with parameter DATA contains the physical data values from which the clumps are to be extracted, whilst the NDF associated with parameter MASK contains integer values that identify the clump to which each pixel belongs. The two NDFs are assumed to be aligned in PIXEL coordinates. An output NDF is created that is a copy of the MASK NDF. Parameters describing the clumps extracted from the DATA NDF are stored in the CUPID extension of the output NDF, and may also be stored in an output catalogue. These are in the same form as the clump parameters created by the FINDCLUMPS command.

Usage:

extractclumps mask data out outcat

Parameters:

BACKOFF = _LOGICAL (Read)

If TRUE, the background level in each clump is removed from the clump data values before calculating the reported clump sizes and centroid position. This means that the clump sizes and centroid position will be independent of the background level. The background level used is the minimum data value in the clump. If FALSE, the full data values, including background, are used when calculating the clump sizes and centroid position. This means that clumps on larger backgrounds will be reported as wider than similar clumps on smaller backgrounds. Using BACKOFF=FALSE allows the comparison of clump properties generated by EXTRACTCLUMPS with those generated by the IDL version of CLUMPFIND (see also the ClumpFind configuration parameter "IDLAlg"). Note, the other reported clump properties such as total data value, peak data value, etc, are always based on the full clump data values, including background. [TRUE]

FWHMBEAM = _REAL (Read)

The FWHM of the instrument beam, in pixels. If DECONV is TRUE, the clump widths written to the output catalogue are reduced (in quadrature) by this amount. The default value is the value stored in the CONFIG component of the CUPID extension in the mask NDF, or 2.0 if the CUPID extension does not contain a CONFIG component. []

DATA = NDF (Read)

The input NDF containing the physical data values.

DECONV = _LOGICAL (Read)

Determines if the clump properties stored in the output catalogue and NDF extension should be corrected to remove the effect of the instrumental beam width specified by the FWHMBEAM and VELORES parameters. If TRUE, the clump sizes will be reduced and the peak values increased to take account of the smoothing introduced by the beam width. If FALSE, the undeconvolved values are stored in the output catalogue and NDF. Note, the filter to remove clumps smaller than the beam width is still applied, even if DECONV is FALSE. [TRUE]

LOGFILE = LITERAL (Read)

The name of a text log file to create. If a null (!) value is supplied, no log file is created. [!]

MASK = NDF (Read)

The input NDF containing the pixel assignments. This will usually have been created by the FINDCLUMPS command.

OUT = NDF (Write)

The output NDF.

OUTCAT = FILENAME (Write)

An optional output catalogue in which to store the clump parameters. See the description of the OUTCAT parameter for the FINDCLUMPS command for further information.

VELORES = _REAL (Read)

The velocity resolution of the instrument, in channels. If DECONV is TRUE, the velocity width of each clump written to the output catalogue is reduced (in quadrature) by this amount. The default value is the value stored in the CONFIG component of the CUPID extension in the mask NDF, or 2.0 if the CUPID extension does not contain a CONFIG component. []

WCSPAR = _LOGICAL (Read)

If a TRUE value is supplied, then the clump parameters stored in the output catalogue and in the CUPID extension of the output NDF, are stored in WCS units, as defined by the current coordinate frame in the WCS component of the input NDF (this can be inspected using the KAPPA:WCSFRAME command). For instance, if the current coordinate system in the input NDF is (RA,Dec,freq), then the catalogue columns that hold the clump peak and centroid positions will use this same coordinate system. The spatial clump sizes will be stored in arc-seconds, and the spectral clump size will be stored in the unit of frequency used by the NDF (Hz, GHz, etc). If a FALSE value is supplied for this parameter, the clump parameters are stored in units of pixels within the pixel coordinate system of the input NDF. The dynamic default for this parameter is TRUE if the current coordinate system in the input NDF represents celestial longitude and latitude in some system, plus a recogonised spectral axis (if the input NDF is 3D). Otherwise, the dynamic default is FALSE. []