7.3.1.3 Segment output ¶

The main output of Segment are two label datasets (with integer types, separating the dataset’s elements into different classes). They have HDU/extension names of CLUMPS and OBJECTS.

Similar to all Gnuastro’s FITS outputs, the zero-th extension/HDU of the main output file only contains header keywords and image or table. It contains the Segment input files and parameters (option names and values) as FITS keywords. Note that if an option name is longer than 8 characters, the keyword name is the second word. The first word is HIERARCH. Also note that according to the FITS standard, the keyword names must be in capital letters, therefore, if you want to use Grep to inspect these keywords, use the -i option, like the example below.

$ astfits image_segmented.fits -h0 | grep -i snquant

By default, besides the CLUMPS and OBJECTS extensions, Segment’s output will also contain the (technically redundant) sky-subtracted input dataset (INPUT-NO-SKY) and the sky standard deviation dataset (SKY_STD, if it was not a constant number). This can help in visually inspecting the result when viewing the images as a “Multi-extension data cube” in SAO DS9 for example, (see Viewing FITS file contents with DS9 or TOPCAT). You can simply flip through the extensions and see the same region of the image and its corresponding clumps/object labels. It also makes it easy to feed the output (as one file) into MakeCatalog when you intend to make a catalog afterwards (see MakeCatalog. To remove these redundant extensions from the output (for example, when designing a pipeline), you can use --rawoutput.

The OBJECTS and CLUMPS extensions can be used as input into MakeCatalog to generate a catalog for higher-level analysis. If you want to treat each clump separately, you can give a very large value (or even a NaN, which will always fail) to the --gthresh option (for example, --gthresh=1e10 or --gthresh=nan), see Segmentation options.

For a complete definition of clumps and objects, please see Section 3.2 of Akhlaghi and Ichikawa 2015 and Segmentation options. The clumps are “true” local maxima (minima if --minima is called) and their surrounding pixels until a local minimum/maximum (caused by noise fluctuations, or another “true” clump). Therefore it may happen that some of the input detections are not covered by clumps at all (very diffuse objects without any strong peak), while some objects may contain many clumps. Even in those that have clumps, there will be regions that are too diffuse. The diffuse regions (within the input detected regions) are given a negative label (-1) to help you separate them from the undetected regions (with a value of zero).

Each clump is labeled with respect to its host object. Therefore, if an object has three clumps for example, the clumps within it have labels 1, 2 and 3. As a result, if an initial detected region has multiple objects, each with a single clump, all the clumps will have a label of 1. The total number of clumps in the dataset is stored in the NCLUMPS keyword of the CLUMPS extension and printed in the verbose output of Segment (when --quiet is not called).

The OBJECTS extension of the output will give a positive counter/label to every detected pixel in the input. As described in Akhlaghi and Ichikawa [2015], the true clumps are grown until a certain threshold. If the grown clumps touch other clumps and the connection is strong enough, they are considered part of the same object. Once objects (grown clumps) are identified, they are grown to cover the whole detected area.

The options to configure the output of Segment are listed below:

--continueaftercheck

Do not abort Segment after producing the check image(s). The usage of this option is identical to NoiseChisel’s --continueaftercheck option (NoiseChisel input). Please see the descriptions there for more.

--noobjects

Abort Segment after finding true clumps and do not continue with finding options. Therefore, no OBJECTS extension will be present in the output. Each true clump in CLUMPS will get a unique label, but diffuse regions will still have a negative value.

To make a catalog of the clumps, the input detection map (where all the labels are one) can be fed into MakeCatalog along with the input detection map to Segment (that only had a value of 1 for all detected pixels) with --clumpscat. In this way, MakeCatalog will assume all the clumps belong to a single “object”.

--grownclumps

In the output CLUMPS extension, store the grown clumps. If a detected region contains no clumps or only one clump, then it will be fully given a label of 1 (no negative valued pixels).

--rawoutput

Only write the CLUMPS and OBJECTS datasets in the output file. Without this option (by default), the first and last extensions of the output will the Sky-subtracted input dataset and the Sky standard deviation dataset (if it was not a number). When the datasets are small, these redundant extensions can make it convenient to inspect the results visually or feed the output to MakeCatalog for measurements. Ultimately both the input and Sky standard deviation datasets are redundant (you had them before running Segment). When the inputs are large/numerous, these extra dataset can be a burden.

$ gzip --best segment_output.fits

When the input is a 2D image, to inspect NoiseChisel’s output you can configure SAO DS9 in your Graphic User Interface (GUI) to open NoiseChisel’s output as a multi-extension data cube. This will allow you to flip through the different extensions and visually inspect the results. This process has been described for the GNOME GUI (most common GUI in GNU/Linux operating systems) in Viewing FITS file contents with DS9 or TOPCAT.