[gnuastro-commits] master 07bc47f: Book: corrected description of MakeCatalog's --halfsumradius

[Mohammad Akhlaghi]

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

    Book: corrected description of MakeCatalog's --halfsumradius
    
    Until now, the description of '--halfsumradius' mentioned the old
    '--halfradiusarea' option which is no longer available. Also it talked
    about an 'obs' suffix (which its current name doesn't have anymore!).
    
    With this commit, it now asks to look into the description of
    '--halfsumarea' for more on teh potential problems and it doesn't talk
    about an 'obs' suffix. The last paragraph is just a caution that this is
    not equivalent to the effective radius.
    
    This issue was reported by Samane Raji.
---
 doc/gnuastro.texi | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index c41e903..a136e8b 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -18439,8 +18439,7 @@ For more on the definition of the surface brightness, 
see @ref{Brightness flux m
 The number of pixels that contain half the object or clump's total sum of 
pixels (half the value in the @option{--brightness} column).
 To count this area, all the non-blank values associated with the given label 
(object or clump) will be sorted and summed in order (starting from the 
maximum), until the sum becomes larger than half the total sum of the label's 
pixels.
 
-This option is thus good for clumps (which are defined to have a single peak 
in their morphology), but for objects you should be careful because if they may 
have multiple peaks and the sorting by value doesn't include morphology.
-So if the object includes multiple peaks/clumps at roughly the same level, 
then the area reported by this option will be distributed over all the peaks.
+This option is thus good for clumps (which are defined to have a single peak 
in their morphology), but for objects you should be careful: if the object 
includes multiple peaks/clumps at roughly the same level, then the area 
reported by this option will be distributed over all the peaks.
 
 @item --halfsumsb
 Surface brightness (in units of mag/arcsec@mymath{^2}) within the area that 
contains half the total sum of the label's pixels (object or clump).
@@ -18454,7 +18453,8 @@ Radius (in units of pixels) derived from the area that 
contains half the total s
 If the area is @mymath{A_h} and the axis ratio is @mymath{q}, then the value 
returned in this column is @mymath{\sqrt{A_h/({\pi}q)}}.
 This option is a good measure of the concentration of the @emph{observed} 
(after PSF convolution and noisy) object or clump,
 But as described below it underestimates the effective radius.
-Also, it should be used in caution with objects, it reliable with clumps, see 
the note under @option{--halfradiusarea}.
+Also, it should be used in caution with objects that may have multiple clumps.
+It is most reliable with clumps or objects that have one or zero clumps, see 
the note under @option{--halfsumarea}.
 
 @cindex Ellipse area
 @cindex Area, ellipse
@@ -18463,11 +18463,13 @@ For a circle (where @mymath{q=1}), this simplifies to 
the familiar @mymath{A={\p
 
 @cindex S@'ersic profile
 @cindex Effective radius
-The suffix @code{obs} is added to the option name to avoid confusing this with 
a profile's effective radius for S@'ersic profiles, commonly written as 
@mymath{r_e}.
-For more on @mymath{r_e}, please see @ref{Galaxies}.
+This option should not be confused with the @emph{effective radius} for 
S@'ersic profiles, commonly written as @mymath{r_e}.
+For more on the S@'ersic profile and @mymath{r_e}, please see @ref{Galaxies}.
 Therefore, when @mymath{r_e} is meaningful for the target (the target is 
elliptically symmetric and can be parameterized as a S@'ersic profile), 
@mymath{r_e} should be derived from fitting the profile with a S@'ersic 
function which has been convolved with the PSF.
 But from the equation above, you see that this radius is derived from the raw 
image's labeled values (after convolution, with no parametric profile), so this 
column's value will generally be (much) smaller than @mymath{r_e}, depending on 
the PSF, depth of the dataset, the morphology, or if a fraction of the profile 
falls on the edge of the image.
 
+In other words, this option can only be interpretted as an effective radius if 
there is no noise and no PSF and the profile within the image extends to 
infinity (or a very large multiple of the effective radius) and it not near the 
edge of the image.
+
 @item --fracmaxarea1
 @itemx --fracmaxarea2
 Number of pixels brighter than the given fraction(s) of the maximum pixel 
value.