[gnuastro-commits] master b3d2e69 2/3: Book: all output extensions of --checkqthresh now described

[Mohammad Akhlaghi]

branch: master
commit b3d2e6919837a2e74799b0561d7b68997c34660d
Author: Mohammad Akhlaghi <mohammad@akhlaghi.org>
Commit: Mohammad Akhlaghi <mohammad@akhlaghi.org>

    Book: all output extensions of --checkqthresh now described
    
    Until now, this very important option in NoiseChisel didn't have any proper
    description of what each output extension is. This would discourage people
    from using it (because of the many extensions, it could be hard to
    understand).
    
    With this commit, each extension of the output file with '--checkqthresh'
    is described and the options that affect that extension are described.
    
    This issue was reported by Zahra Hosseini.
---
 THANKS                       |  1 +
 doc/announce-acknowledge.txt |  1 +
 doc/gnuastro.texi            | 67 +++++++++++++++++++++++++++++++++++++++++++-
 3 files changed, 68 insertions(+), 1 deletion(-)

diff --git a/THANKS b/THANKS
index c183bb8..6a28632 100644
--- a/THANKS
+++ b/THANKS
@@ -50,6 +50,7 @@ support in Gnuastro. The list is ordered alphabetically (by 
family name).
     Madusha Gunawardhana                 gunawardhana@strw.leidenuniv.nl
     Bruno Haible                         bruno@clisp.org
     Stephen Hamer                        stephen.hamer@univ-lyon1.fr
+    Zahra Hosseini                       2hs.zahra@gmail.com
     Leslie Hunt                          leslie.hunt@inaf.it
     Takashi Ichikawa                     ichikawa@astr.tohoku.ac.jp
     Raúl Infante Sainz                   infantesainz@gmail.com
diff --git a/doc/announce-acknowledge.txt b/doc/announce-acknowledge.txt
index 0b3905d..edd0a87 100644
--- a/doc/announce-acknowledge.txt
+++ b/doc/announce-acknowledge.txt
@@ -1,6 +1,7 @@
 Alphabetically ordered list to acknowledge in the next release.
 
 Sepideh Eskandarlou
+Zahra Hosseini
 Sebastian Luna-Valero
 Peter Teuben
 
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index 4ba7d38..66db3e3 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -17341,10 +17341,75 @@ Width of flat kernel used to smooth the interpolated 
quantile thresholds, see @o
 @cindex NaN
 @item --checkqthresh
 Check the quantile threshold values on the mesh grid.
-A file suffixed with @file{_qthresh.fits} will be created showing each step.
+A multi-extension FITS file, suffixed with @file{_qthresh.fits} will be 
created showing each step of how the final quantile threshold is found.
 With this option, NoiseChisel will abort as soon as quantile estimation has 
been completed, allowing you to inspect the steps leading to the final quantile 
threshold, this can be disabled with @option{--continueaftercheck}.
 By default the output will have the same pixel size as the input, but with the 
@option{--oneelempertile} option, only one pixel will be used for each tile 
(see @ref{Processing options}).
 
+The key things to remember are:
+@itemize
+@item
+The measurements to find the thresholds are done on tiles that cover the whole 
image in a tesselation.
+Recall that you can set the size of tiles with @option{--tilesize} and check 
them with @option{--checktiles}.
+Therefore except for the first and last extensions, the rest only show tiles.
+@item
+NoiseChisel ultimately has three thresholds: the quantile threshold (that you 
set with @option{--qthresh}), the no-erode quantile (set with 
@option{--noerodequant}) and the growth quantile (set with 
@option{--detgrowquant}).
+Therefore for each step, we have three extensions.
+@end itemize
+
+The output file will have the following extensions.
+Below, the extensions are put in the same order as you see in the file, with 
their name.
+
+@table @code
+@item CONVOLVED
+This is the input image after convolution with the kernel (which is a FWHM=2 
Gaussian by default, but you can change with @option{--kernel}).
+Recall that the thresholds are defined on the convolved image.
+
+@item  QTHRESH_ERODE
+@itemx QTHRESH_NOERODE
+@itemx QTHRESH_EXPAND
+In these three extensions, the tiles that have a quantile-of-mean more/less 
than 0.5 (quantile of median) @mymath{\pm d} are set to NaN (@mymath{d} is the 
value given to @option{--meanmedqdiff}, see @ref{Quantifying signal in a tile}).
+Therefore the non-NaN tiles that you see here are the tiles where there is no 
significant skewness (changing signal) within that tile.
+The only differing thing between the three extensions is the values of the 
non-NaN tiles.
+These values will be used to construct the final threshold map over the whole 
image.
+
+@item  VALUE1_NO_OUTLIER
+@itemx VALUE2_NO_OUTLIER
+@itemx VALUE3_NO_OUTLIER
+All outlier tiles have been masked.
+The reason for removing outliers is that the quantile-of-mean is only 
sensitive to signal that varies on a scale that is smaller than the tile size.
+Therefore the extended wings of large galaxies or bright stars (which vary on 
scales much larger than the tile size) will pass that test.
+As described in @ref{Quantifying signal in a tile}, using the values given to 
@option{--outliersclip} and @option{--outliersigma}, the outlier tiles are 
removed in this step.
+
+@item  THRESH1_INTERP
+@itemx THRESH2_INTERP
+@itemx THRESH3_INTERP
+Using the successful values that remain after the previous step, give values 
to all (interpolate) the tiles in the image.
+The interpolation is done using the nearest-neighbor method: for each tile, 
the N nearest neighbors are found and the median of their values is used to 
fill it.
+You can set the value of N through the @option{--interpnumngb} option.
+
+@item  THRESH1_SMOOTH
+@itemx THRESH2_SMOOTH
+@itemx THRESH3_SMOOTH
+Smooth the interpolated image to remove the strong differences between 
touching tiles.
+Because we used the median value of the N nearest neighbors in the previous 
step, there can be strong discontinuities on the edges of tiles (which can 
directly show in the image after applying the threshold).
+The scale of the smoothing (number of nearby tiles to smooth with) is set with 
the @option{--smoothwidth} option.
+
+@item QTHRESH-APPLIED
+The pixels in this image can only have three values:
+
+@table @code
+@item 0
+These pixels had a value below the quantile threshold.
+@item 1
+These pixels had a value above the quantile threshod, but below the threshold 
for no erosion.
+Therefore in the next step, NoiseChisel will erode (set them to 0) these 
pixels if they are touching a 0-valued pixel.
+@item 2
+These pixels had a value above the no-erosion threshold.
+So NoiseChisel will not erode these pixels, it will only apply Opening to them 
afterwards.
+Recall that this was done to avoid loosing sharp point-sources (like stars in 
space-based imaging).
+@end table
+@end table
+
 @item --blankasforeground
 In the erosion and opening steps below, treat blank elements as foreground 
(regions above the threshold).
 By default, blank elements in the dataset are considered to be background, so 
if a foreground pixel is touching it, it will be eroded.