[gnuastro-commits] master a1718973: Book: differentiating MEDSTD from Standard Deviation in Masked Images

[Mohammad Akhlaghi]

branch: master
commit a1718973ee3af8b7fc431a22b82bde96f19a2b1c
Author: Elham Saremi <saremi_elham@yahoo.com>
Commit: Mohammad Akhlaghi <mohammad@akhlaghi.org>

    Book: differentiating MEDSTD from Standard Deviation in Masked Images
    
    Until now, the tutorial has provided a clear explanation and examples for
    estimating the image surface brightness limit using two methods. The first
    method involves calculating the standard deviation of a masked image, while
    the second method utilizes the MEDSTD keyword stored within the SKY_STD
    HDU. While the tutorial mentions that the differences between MEDSTD and
    the standard deviation of the masked image are generally small, it does not
    clarify to the reader which is more precise when there is a difference.
    
    With this commit, a box has been added in the text to highlight how MEDSTD
    is not only easier to use, but is more robust to outliers; and therefore,
    it is the one that should be prefered. Some minor corrections have been
    made in the text.
---
 doc/gnuastro.texi | 21 +++++++++++++++------
 1 file changed, 15 insertions(+), 6 deletions(-)

diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index 5ed02cc3..55765d99 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -5254,7 +5254,7 @@ $ bunzip2 r.fits.bz2
 
 @node NoiseChisel optimization, Skewness caused by signal and its measurement, 
Downloading and validating input data, Detecting large extended targets
 @subsection NoiseChisel optimization
-In @ref{Detecting large extended targets} we downloaded the single exposure 
SDSS image.
+In @ref{Downloading and validating input data} we downloaded the single 
exposure SDSS image.
 Let's see how NoiseChisel operates on it with its default parameters:
 
 @example
@@ -5472,7 +5472,7 @@ In these deeper images you clearly see how the outer 
edges of the M51 group foll
 
 As the gradient in the @code{SKY} extension shows, and the deep images cited 
above confirm, the galaxy's signal extends even beyond this.
 But this is already far deeper than what most (if not all) other tools can 
detect.
-Therefore, we will stop configuring NoiseChisel at this point in the tutorial 
and let you play with the other options a little more, while reading more about 
it in the papers: Akhlaghi and Ichikawa 
@url{https://arxiv.org/abs/1505.01664,2015} and 
@url{https://arxiv.org/abs/1909.11230,2019}) and @ref{NoiseChisel}.
+Therefore, we will stop configuring NoiseChisel at this point in the tutorial 
and let you play with the other options a little more, while reading more about 
it in the papers: Akhlaghi and Ichikawa 
@url{https://arxiv.org/abs/1505.01664,2015} and 
@url{https://arxiv.org/abs/1909.11230,2019} and @ref{NoiseChisel}.
 When you do find a better configuration feel free to contact us for feedback.
 Do not forget that good data analysis is an art, so like a sculptor, master 
your chisel for a good result.
 
@@ -5701,12 +5701,12 @@ In case you would like to know more about the usage of 
the quantile of the mean
 @cindex Surface brightness limit
 @cindex Limit, surface brightness
 When your science is related to extended emission (like the example here) and 
you are presenting your results in a scientific conference, usually the first 
thing that someone will ask (if you do not explicitly say it!), is the 
dataset's @emph{surface brightness limit} (a standard measure of the noise 
level), and your target's surface brightness (a measure of the signal, either 
in the center or outskirts, depending on context).
-For more on the basics of these important concepts please see @ref{Quantifying 
measurement limits}).
-So in this section of the tutorial, we will measure these values for this 
image and this target.
+For more on the basics of these important concepts please see @ref{Quantifying 
measurement limits}.
+So in this section of the tutorial, we will measure these values for the 
single-exposure SDSS image of the M51 group that we downloaded in 
@ref{Downloading and validating input data}.
 
 @noindent
 Before measuring the surface brightness limit, let's see how reliable our 
detection was.
-In other words, let's see how ``clean'' our noise is (after masking all 
detections, as described previously in @ref{Skewness caused by signal and its 
measurement})
+In other words, let's see how ``clean'' our noise is (after masking all 
detections, as described previously in @ref{Skewness caused by signal and its 
measurement}):
 
 @example
 $ aststatistics det-masked.fits --quantofmean
@@ -5746,7 +5746,16 @@ $ astfits r_detected.fits --hdu=SKY_STD | grep 'M..STD'
 @end example
 
 The @code{MEDSTD} value is very similar to the standard deviation derived 
above, so we can safely use it instead of having to mask and run Statistics.
-In fact, MakeCatalog also uses this keyword and will report the dataset's 
@mymath{n\sigma} surface brightness limit as keywords in the output (not as 
measurement columns, since it is related to the noise, not labeled signal):
+
+@cartouche
+@noindent
+@strong{@code{MEDSTD} is more reliable than the standard deviation of masked 
pixels:} it may happen that differences between these two become more 
significant than the experiment above.
+In such cases, the @code{MEDSTD} is more reliable because NoiseChisel 
estimates it within the tiles and after several steps of outlier rejection (for 
example due to un-detected signal) and before interpolation.
+Whereas the standard deviation of the masked image is calculated based on the 
final detection, does no higher-level outlier rejection and is based on the 
interpolated image.
+Therefore, it can be easily biased by signal or artifacts in the image and 
besides being easier to measure, @code{MEDSTD} is also more statistically 
robust.
+@end cartouche
+
+Fortunately, MakeCatalog will use this keyword and will report the dataset's 
@mymath{n\sigma} surface brightness limit as keywords in the output (not as 
measurement columns, since it is related to the noise, not labeled signal) as 
described below.
 
 @example
 $ astmkcatalog r_detected.fits -hDETECTIONS --output=sbl.fits \