[gnuastro-commits] master dc8f7208: color-faint-gray: warning the user to convert zero pixel values to nan

[Mohammad Akhlaghi]

branch: master
commit dc8f72081cf7e82969f146957aa8e1d1c67284e1
Author: Raul Infante-Sainz <infantesainz@gmail.com>
Commit: Mohammad Akhlaghi <mohammad@akhlaghi.org>

    color-faint-gray: warning the user to convert zero pixel values to nan
    
    Until now, we did not inform the user to convert all pixels that are equal
    to zero to nan values. We are used to having such pixels already as NaNs
    (from Gnuastro programs). However, there are many images coming from other
    software that put zero values to those pixels, normally in the
    corner/borders, or in general in the outer part of the images. These zero
    pixel values that are meaningless affect the estimation of the necessary
    parameters for constructing a nice color/gray image.
    
    With this commit, a couple of sentences explaining this situation have been
    included to warn the user. The reporting of the default/used values for
    grayval and colorval was wrong and it has been corrected. In addition to
    that, I also fixed a couple of typos in other part of the Book.
---
 bin/script/color-faint-gray.sh | 17 ++++++++++++-----
 doc/gnuastro.texi              | 23 +++++++++++++++++++++--
 2 files changed, 33 insertions(+), 7 deletions(-)

diff --git a/bin/script/color-faint-gray.sh b/bin/script/color-faint-gray.sh
index ad1d1f80..04ea0c40 100644
--- a/bin/script/color-faint-gray.sh
+++ b/bin/script/color-faint-gray.sh
@@ -922,16 +922,16 @@ else
     # asinh-transformed image. If the user does not provide a value then use
     # ghe computed one (guessed). If the user provide a value, then use it
     # directly. Note that the guessed value is computed in any case.
-    colorval_estimated=$(aststatistics $i_colorgray_threshold \
+    colorval_default=$(aststatistics $i_colorgray_threshold \
                                        --median --quiet)
     if [ x$colorval = x"" ]; then
-      colorval=$colorval_estimated
+      colorval=$colorval_default
     fi
 
-    grayval_estimated=$(aststatistics $i_colorgray_threshold \
+    grayval_default=$(aststatistics $i_colorgray_threshold \
                                       --median --quiet)
     if [ x$grayval = x"" ]; then
-      grayval=$grayval_estimated
+      grayval=$grayval_default
     fi
 
 
@@ -1091,7 +1091,11 @@ if [ ! x$quiet = x"--quiet" ]; then
   cat <<EOF
 
 TIPS:
-  # First, use the default options to estimate the parameters.
+
+  # If there are exact zero-valued pixels (e.g., in the border/outer parts
+    of the images), convert them to NaN: zero is statistically meaningful
+    and can interfere with the statistics of this script; see the tutorial.
+  # Use the default options to estimate the parameters.
   # Select a good background value of the images:
       A minimum value of zero could be a good option: '--minimum=0.0'
   # Focus on the bright regions and tweak '--qbright' and '--stretch':
@@ -1102,6 +1106,9 @@ TIPS:
       This is the lowest value of the threshold image that is shown in color.
   # Change '--grayval' to separate the black and gray regions:
       This is highest value of the threshold image that is shown in gray.
+  # Schema for these parameters:
+      Output regions:   |  GRAY  |   BLACK   |   COLOR   |
+      Threshold values: 0 --- grayval --- colorval --- 100
   # Use '--checkparams' to check the pixel value distributions.
   # Use '--keeptmp' to not remove the threshold image and check it:
       '$i_colorgray_threshold'
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index 9911fcbf..0a505406 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -9046,6 +9046,25 @@ However, the images does not look nice and there is 
significant room for improve
 You will notice that at the end of its operation, the script printed some 
numerical values for four options in a table, to show automatically estimated 
parameter values.
 To enhance the output, let's go through and explain these step by step.
 
+@cartouche
+@noindent
+@strong{Zero as blank value:}
+@cindex Blank values
+@cindex Zero as blank/NaN
+@cindex NaN (Not a Number)
+@cindex Not a Number (NaN)
+Some astronomical data analysis software do not put ``Not a Number'' (NaN) in 
pixels that do not have data (for example there was no exposure there); instead 
they put a value of zero (or any other arbitrary number)!
+When present, such pixels usually occur on the outer edges of images (for 
example the image was taken at a rotated angle to the equatorial coordinates of 
the pixel grid).
+However, zero (or any arbitrary number) is statistically meaningful and will 
bias the measurements done in this (or any other) analysis.
+The examples here don't have such regions, but it is important to be prepared.
+
+If your inputs suffer from this problem, run the command below to convert the 
zero (or any other arbitrary value) to a NaN before starting to use this script:
+
+@example
+$ astarithmetic img.fits set-i i i 0 eq nan where --output=good.fits
+@end example
+@end cartouche
+
 The first important point to take into account is the photometric calibration.
 If the images are photometrically calibrated, then it is necessary to use the 
calibration to put the images in the same physical units and create ``real'' 
colors.
 The script is able to do it through the zero point magnitudes with the option 
@option{--zeropoint} (or @option{-z}).
@@ -22144,9 +22163,9 @@ This operator is very similar to @command{min}, with 
the exception that it expec
 The first popped operand is the termination criteria and the second is the 
multiple of the median absolute deviation.
 
 For example, in the command below, the first popped operand of 
@code{sigclip-mean} (@command{0.1}) is the @mymath{\sigma}-clipping termination 
criteria.
-If the termination criteria is larger than, or equal to, 1 it is interpreted 
as the total number of clips.
+If the termination criteria is larger than, or equal to 1, it is interpreted 
as the total number of clips.
 But if it is between 0 and 1, then it is the tolerance level on the change in 
the median absolute deviation (see @ref{Sigma clipping}).
-The second popped operand (@command{3}) is the multiple of the median absolute 
deviation to use.
+The second popped operand (@command{4}) is the multiple of sigma (STD) to use.
 The third popped operand (@command{3}) is number of datasets that should be 
stacked (similar to the first popped operand to @command{min}).
 Two other side-notes should be mentioned here:
 @itemize