Besides the input dataset (for example, astronomical image), Segment also needs to know the Sky standard deviation and the regions of the dataset that it should segment. The values dataset is assumed to be Sky subtracted by default. If it is not, you can ask Segment to subtract the Sky internally by calling --sky. For the rest of this discussion, we will assume it is already sky subtracted.
The Sky and its standard deviation can be a single value (to be used for the whole dataset) or a separate dataset (for a separate value per pixel). If a dataset is used for the Sky and its standard deviation, they must either be the size of the input image, or have a single value per tile (generated with --oneelempertile, see Processing options and Tessellation).
The detected regions/pixels can be specified as a detection map (for example, see NoiseChisel output). If --detection=all, Segment will not read any detection map and assume the whole input is a single detection. For example, when the dataset is fully covered by a large nearby galaxy/globular cluster.
When dataset are to be used for any of the inputs, Segment will assume they are multiple extensions of a single file by default (when --std or --detection are not called). For example, NoiseChisel’s default output NoiseChisel output. When the Sky-subtracted values are in one file, and the detection and Sky standard deviation are in another, you just need to use --detection: in the absence of --std, Segment will look for both the detection labels and Sky standard deviation in the file given to --detection. Ultimately, if all three are in separate files, you need to call both --detection and --std.
The extensions of the three mandatory inputs can be specified with --hdu, --dhdu, and --stdhdu. For a full discussion on what to give to these options, see the description of --hdu in Input/Output options. To see their default values (along with all the other options), run Segment with the --printparams (or -P) option. Just recall that in the absence of --detection and --std, all three are assumed to be in the same file. If you only want to see Segment’s default values for HDUs on your system, run this command:
$ astsegment -P | grep hdu
By default Segment will convolve the input with a kernel to improve the signal-to-noise ratio of true peaks. If you already have the convolved input dataset, you can pass it directly to Segment for faster processing (using the --convolved and --chdu options). Just do not forget that the convolved image must also be Sky-subtracted before calling Segment. If a value/file is given to --sky, the convolved values will also be Sky subtracted internally. Alternatively, if you prefer to give a kernel (with --kernel and --khdu), Segment can do the convolution internally. To disable convolution, use --kernel=none.
The Sky value(s) to subtract from the input. This option can either be given a constant number or a file name containing a dataset (multiple values, per pixel or per tile). By default, Segment will assume the input dataset is Sky subtracted, so this option is not mandatory.
If the value cannot be read as a number, it is assumed to be a file name. When the value is a file, the extension can be specified with --skyhdu. When it is not a single number, the given dataset must either have the same size as the output or the same size as the tessellation (so there is one pixel per tile, see Tessellation).
When this option is given, its value(s) will be subtracted from the input and the (optional) convolved dataset (given to --convolved) prior to starting the segmentation process.
The HDU/extension containing the Sky values. This is mandatory when the value given to --sky is not a number. Please see the description of --hdu in Input/Output options for the different ways you can identify a special extension.
The Sky standard deviation value(s) corresponding to the input. The value can either be a constant number or a file name containing a dataset (multiple values, per pixel or per tile). The Sky standard deviation is mandatory for Segment to operate.
If the value cannot be read as a number, it is assumed to be a file name. When the value is a file, the extension can be specified with --skyhdu. When it is not a single number, the given dataset must either have the same size as the output or the same size as the tessellation (so there is one pixel per tile, see Tessellation).
When this option is not called, Segment will assume the standard deviation is a dataset and in a HDU/extension (--stdhdu) of another one of the input file(s). If a file is given to --detection, it will assume that file contains the standard deviation dataset, otherwise, it will look into input filename (the main argument, without any option).
The HDU/extension containing the Sky standard deviation values, when the value given to --std is a file name. Please see the description of --hdu in Input/Output options for the different ways you can identify a special extension.
The input Sky standard deviation value/dataset is actually variance. When this option is called, the square root of input Sky standard deviation (see --std) is used internally, not its raw value(s).
Detection map to use for segmentation. If given a value of all, Segment will assume the whole dataset must be segmented, see below. If a detection map is given, the extension can be specified with --dhdu. If not given, Segment will assume the desired HDU/extension is in the main input argument (input file specified with no option).
The final segmentation (clumps or objects) will only be over the non-zero pixels of this detection map. The dataset must have the same size as the input image. Only datasets with an integer type are acceptable for the labeled image, see Numeric data types. If your detection map only has integer values, but it is stored in a floating point container, you can use Gnuastro’s Arithmetic program (see Arithmetic) to convert it to an integer container, like the example below:
$ astarithmetic float.fits int32 --output=int.fits
It may happen that the whole input dataset is covered by signal, for example, when working on parts of the Andromeda galaxy, or nearby globular clusters (that cover the whole field of view).
In such cases, segmentation is necessary over the complete dataset, not just specific regions (detections).
By default Segment will first use the undetected regions as a reference to find the proper signal-to-noise ratio of “true” clumps (give a purity level specified with --snquant).
Therefore, in such scenarios you also need to manually give a “true” clump signal-to-noise ratio with the --clumpsnthresh option to disable looking into the undetected regions, see Segmentation options.
In such cases, is possible to make a detection map that only has the value 1 for all pixels (for example, using Arithmetic), but for convenience, you can also use --detection=all.
The HDU/extension containing the detection map given to --detection. Please see the description of --hdu in Input/Output options for the different ways you can identify a special extension.
The name of file containing kernel that will be used to convolve the input image. The usage of this option is identical to NoiseChisel’s --kernel option (NoiseChisel input). Please see the descriptions there for more. To disable convolution, you can give it a value of none.
The HDU/extension containing the kernel used for convolution. For acceptable values, please see the description of --hdu in Input/Output options.
The convolved image’s file name to avoid internal convolution by Segment. The usage of this option is identical to NoiseChisel’s --convolved option. Please see NoiseChisel input for a thorough discussion of the usefulness and best practices of using this option.
If you want to use the same convolution kernel for detection (with NoiseChisel) and segmentation, with this option, you can use the same convolved image (that is also available in NoiseChisel) and avoid two convolutions. However, just be careful to use the input to NoiseChisel as the input to Segment also, then use the --sky and --std to specify the Sky and its standard deviation (from NoiseChisel’s output). Recall that when NoiseChisel is not called with --rawoutput, the first extension of NoiseChisel’s output is the Sky-subtracted input (see NoiseChisel output). So if you use the same convolved image that you fed to NoiseChisel, but use NoiseChisel’s output with Segment’s --convolved, then the convolved image will not be Sky subtracted.
The HDU/extension containing the convolved image (given to --convolved). For acceptable values, please see the description of --hdu in Input/Output options.
The size of the large tiles to use for identifying the clump S/N threshold over the undetected regions. The usage of this option is identical to NoiseChisel’s --largetilesize option (NoiseChisel input). Please see the descriptions there for more.
The undetected regions can be a significant fraction of the dataset and finding clumps requires sorting of the desired regions, which can be slow. To speed up the processing, Segment finds clumps in the undetected regions over separate large tiles. This allows it to have to sort a much smaller set of pixels and also to treat them independently and in parallel. Both these issues greatly speed it up. Just be sure to not decrease the large tile sizes too much (less than 100 pixels in each dimension). It is important for them to be much larger than the clumps.
GNU Astronomy Utilities 0.23 manual, July 2024.