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]
JSACAT = NDF (Read)
An optional JSA-style output catalogue in which to store the clump parameters (for KAPPA-style catalogues see parameter " OUTCAT" ). No catalogue will be produced if a null (!) value is supplied. The created file will be a FITS file containing a binary table. The columns in this catalogue will be the same as those created by the " OUTCAT" parameter, but the table will in also hold the contents of the FITS extension of the input NDF, and CADC-style provenance headers. [!]
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 KAPPA-style output catalogue in which to store the clump parameters (for JSA-style catalogues see parameter " JSACAT" ). See the description of the OUTCAT parameter for the FINDCLUMPS command for further information.
SHAPE = LITERAL (Read)
Specifies the shape that should be used to describe the spatial coverage of each clump in the output catalogue. It can be set to any of the strings described below. If it is set to " None" , the spatial shape of each clump is not recorded in the output catalogue. Otherwise, the catalogue will have an extra column named " Shape" holding an STC-S description of the spatial coverage of each clump. " STC-S" is a textual format developed by the IVOA for describing regions within a WCS - see http://www.ivoa.net/Documents/latest/STC-S.html for details. These STC-S desriptions can be displayed by the KAPPA:LISTSHOW command, or using GAIA. Since STC-S cannot describe regions within a pixel array, it is necessary to set parameter WCSPAR to TRUE if using this option. An error will be reported if WCSPAR is FALSE. An error will also be reported if the WCS in the input data does not contain a pair of scelestial sky axes.

  • Polygon: Each polygon will have, at most, 15 vertices. If the data is 2-dimensional, the polygon is a fit to the clump’ s outer boundary (the region containing all godo data values). If the data is 3-dimensional, the spatial footprint of each clump is determined by rejecting the least significant 10% of spatial pixels, where " significance" is measured by the number of spectral channels that contribute to the spatial pixel. The polygon is then a fit to the outer boundary of the remaining spatial pixels.

  • Ellipse: All data values in the clump are projected onto the spatial plane and " size" of the collapsed clump at four different position angles - all separated by 45 degrees - is found (see the OUTCAT parameter for a description of clump " size" ). The ellipse that generates the closest sizes at the four position angles is then found and used as the clump shape.

  • Ellipse2: The above method for determining ellipses works well for clumps that are in fact elliptical, but can generate extremely long thin ellipses for clumps are far from being ellitical. The " Ellipse2" option uses a different method for determining the best ellipse based on finding many marginal profiles at one degree intervals of azimuth, and using the longest marginal profile as the major axis. The ellipse is centred at the clump centroid.

  • Ellipse3: The same as " Ellipse2" except that the ellipse is centred at the clump peak, rather than the clump centroid, and the pixel data values are used as weights when forming the mean radial distance at each azimuth angle.

In general, ellipses will outline the brighter, inner regions of each clump, and polygons will include the fainter outer regions. The dynamic default is " Polygon" if a JSA-style catalogue (see parameters JSACAT) is being created, and " None" otherwise. Note, if a JSA-style catalogue is being created an error will be reported if " Ellipse" , " Ellipse2" , " Ellipse 3" or " None" is selected. []

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. []