7.2.2 Invoking NoiseChisel ¶

NoiseChisel will detect signal in noise producing a multi-extension dataset containing a binary detection map which is the same size as the input. Its output can be readily used for input into Segment, for higher-level segmentation, or MakeCatalog to do measurements and generate a catalog. The executable name is astnoisechisel with the following general template

$ astnoisechisel [OPTION ...] InputImage.fits

One line examples:

## Detect signal in input.fits.
$ astnoisechisel input.fits

## Inspect all the detection steps after changing a parameter.
$ astnoisechisel input.fits --qthresh=0.4 --checkdetection

## Detect signal assuming input has 4 amplifier channels along first
## dimension and 1 along the second. Also set the regular tile size
## to 100 along both dimensions:
$ astnoisechisel --numchannels=4,1 --tilesize=100,100 input.fits

If NoiseChisel is to do processing (for example, you do not want to get help, or see the values to each input parameter), an input image should be provided with the recognized extensions (see Arguments). NoiseChisel shares a large set of common operations with other Gnuastro programs, mainly regarding input/output, general processing steps, and general operating modes. To help in a unified experience between all of Gnuastro’s programs, these operations have the same command-line options, see Common options for a full list/description (they are not repeated here).

As in all Gnuastro programs, options can also be given to NoiseChisel in configuration files. For a thorough description on Gnuastro’s configuration file parsing, please see Configuration files. All of NoiseChisel’s options with a short description are also always available on the command-line with the --help option, see Getting help. To inspect the option values without actually running NoiseChisel, append your command with --printparams (or -P).

NoiseChisel’s input image may contain blank elements (see Blank pixels). Blank elements will be ignored in all steps of NoiseChisel. Hence if your dataset has bad pixels which should be masked with a mask image, please use Gnuastro’s Arithmetic program (in particular its where operator) to convert those pixels to blank pixels before running NoiseChisel. Gnuastro’s Arithmetic program has bitwise operators helping you select specific kinds of bad-pixels when necessary.

A convolution kernel can also be optionally given. If a value (file name) is given to --kernel on the command-line or in a configuration file (see Configuration files), then that file will be used to convolve the image prior to thresholding. Otherwise a default kernel will be used. For a 2D image, the default kernel is a 2D Gaussian with a FWHM of 2 pixels truncated at 5 times the FWHM. This choice of the default kernel is discussed in Section 3.1.1 of Akhlaghi and Ichikawa 2015. For a 3D cube, it is a Gaussian with FWHM of 1.5 pixels in the first two dimensions and 0.75 pixels in the third dimension. See Convolution kernel for kernel related options. Passing none to --kernel will disable convolution. On the other hand, through the --convolved option, you may provide an already convolved image, see descriptions below for more.

NoiseChisel defines two tessellations over the input (see Tessellation). This enables it to deal with possible gradients in the input dataset and also significantly improve speed by processing each tile on different threads simultaneously. Tessellation related options are discussed in Processing options. In particular, NoiseChisel uses two tessellations (with everything between them identical except the tile sizes): a fine-grained one with smaller tiles (used in thresholding and Sky value estimations) and another with larger tiles which is used for pseudo-detections over non-detected regions of the image. The common Tessellation options described in Processing options define all parameters of both tessellations. The large tile size for the latter tessellation is set through the --largetilesize option. To inspect the tessellations on your input dataset, run NoiseChisel with --checktiles.

$ astnoisechisel --help | grep check

When working on 3D data cubes, the tessellation options need three values and updating them every time can be annoying/buggy. To simplify the job, NoiseChisel also installs a astnoisechisel-3d.conf configuration file (see Configuration files). You can use this for default values on data cubes. For example, if you installed Gnuastro with the prefix /usr/local (the default location, see Installation directory), you can benefit from this configuration file by running NoiseChisel like the example below.

$ astnoisechisel cube.fits \
             --config=/usr/local/etc/gnuastro/astnoisechisel-3d.conf

To further simplify the process, you can define a shell alias in any startup file (for example, ~/.bashrc, see Installation directory). Assuming that you installed Gnuastro in /usr/local, you can add this line to the startup file (you may put it all in one line, it is broken into two lines here for fitting within page limits).

alias astnoisechisel-3d="astnoisechisel \
               --config=/usr/local/etc/gnuastro/astnoisechisel-3d.conf"

Using this alias, you can call NoiseChisel with the name astnoisechisel-3d (instead of astnoisechisel). It will automatically load the 3D specific configuration file first, and then parse any other arguments, options or configuration files. You can change the default values in this 3D configuration file by calling them on the command-line as you do with astnoisechisel²⁰⁵. For example:

$ astnoisechisel-3d --numchannels=3,3,1 cube.fits

Below, we will discuss NoiseChisel’s options, classified into separate sub-sections to help in easy navigation. NoiseChisel input discusses the basic options relating to input file(s) and data; these have no effect on the the detection process. Afterwards, Detection options fully describes every configuration parameter (option) related to detection and how they affect the final result. The order of options in this section follow the logical order within NoiseChisel. On first reading (while you are still new to NoiseChisel), it is therefore strongly recommended to read the options in the given order below. The output of --printparams (or -P) also has this order. However, the output of --help is sorted alphabetically. Finally, in NoiseChisel output the format of NoiseChisel’s output is discussed.

• NoiseChisel input
• Detection options
• NoiseChisel output