[gnuastro-commits] master c4877bc: MakeCatalog: new --halfmaxradius column, obs suffix removed

[Mohammad Akhlaghi]

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

    MakeCatalog: new --halfmaxradius column, obs suffix removed
    
    The '--fwhmobs' and '--halfradiusobs' options were one of the first ones we
    added in the '--halfXXX' options. But as we added more, the names became
    more standard like '--halfsumarea' or '--halfsumsb', or '--halfmaxarea' and
    etc. However, until now, '--halfradiusobs' still had a differently
    formatted name which could be confusing. Also, both had an 'obs' suffix
    which was redundant (because MakeCatalog doesn't do any parametric fitting
    yet).
    
    With this commit, '--halfradiusobs' is renamed to '--halfsumradius' to have
    a similar format to the rest and avoid confusion and '--fwhmobs' is renamed
    to '--fwhm'.
    
    Also, for the sake of symmetry between the '--halfsum*' and '--halfmax*'
    options, the new '--halfmaxradius' column has been added with this commit.
---
 NEWS                    |  5 +++--
 bin/mkcatalog/args.h    | 22 ++++++++++++++++++----
 bin/mkcatalog/columns.c | 46 ++++++++++++++++++++++++++++------------------
 bin/mkcatalog/ui.h      |  5 +++--
 doc/gnuastro.texi       | 20 ++++++++++++--------
 5 files changed, 64 insertions(+), 34 deletions(-)

diff --git a/NEWS b/NEWS
index 445aaf0..04a2954 100644
--- a/NEWS
+++ b/NEWS
@@ -65,8 +65,9 @@ See the end of the file for license conditions.
    --maximum: maximum value of labeled regions pixels (clump/object).
    --areaarcsec2: area of labeled region (clump/object) in arcsec^2.
    --surfacebrightness: the surface brightness of the labeled region.
-   --fwhmobs: observed FWHM in pixels, along the major axis.
+   --fwhm: observed FWHM in pixels (non-parametric), along the major axis.
    --halfmaxarea: number of pixels with a value larger than half the maximum.
+   --halfmaxradius: radius of region that is larger than half the maximum.
    --halfmaxsum: sum of pixels with a value larger than half the maximum.
    --halfmaxsb: surf. brightness within half of the maximum.
    --fracmax: fractions to use in '--fracmaxarea1' or '--fracmaxarea2'.
@@ -78,7 +79,7 @@ See the end of the file for license conditions.
    --fracmaxradius2: radius derived from '--fracmaxarea2'.
    --halfsumsb: Surface brightness within area reported by '--halfsumarea'.
    --halfsumarea: area containing half of the summed object or clump values.
-   --halfradiusobs: radius derived from '--halfsumarea', underestimates r_e.
+   --halfsumradius: radius derived from '--halfsumarea', underestimates r_e.
    --areaminv: the number of pixels that are equal to the minimum value.
    --areamaxv: the number of pixels that are equal to the maximum value.
    - New columns to return the position of pixel with minimum or maximum
diff --git a/bin/mkcatalog/args.h b/bin/mkcatalog/args.h
index ee345c4..659cea7 100644
--- a/bin/mkcatalog/args.h
+++ b/bin/mkcatalog/args.h
@@ -1687,8 +1687,8 @@ struct argp_option program_options[] =
       ui_column_codes_ll
     },
     {
-      "fwhmobs",
-      UI_KEY_FWHMOBS,
+      "fwhm",
+      UI_KEY_FWHM,
       0,
       0,
       "Full width at half max (non-parametric).",
@@ -1715,6 +1715,20 @@ struct argp_option program_options[] =
       ui_column_codes_ll
     },
     {
+      "halfmaxradius",
+      UI_KEY_HALFMAXRADIUS,
+      0,
+      0,
+      "Radius at half the maximum (non-parametric).",
+      UI_GROUP_COLUMNS_MORPHOLOGY,
+      0,
+      GAL_TYPE_INVALID,
+      GAL_OPTIONS_RANGE_ANY,
+      GAL_OPTIONS_NOT_MANDATORY,
+      GAL_OPTIONS_NOT_SET,
+      ui_column_codes_ll
+    },
+    {
       "halfmaxsum",
       UI_KEY_HALFMAXSUM,
       0,
@@ -1771,8 +1785,8 @@ struct argp_option program_options[] =
       ui_column_codes_ll
     },
     {
-      "halfradiusobs",
-      UI_KEY_HALFRADIUSOBS,
+      "halfsumradius",
+      UI_KEY_HALFSUMRADIUS,
       0,
       0,
       "Radius calculated from --halfsumarea.",
diff --git a/bin/mkcatalog/columns.c b/bin/mkcatalog/columns.c
index 3024f35..ee0aedb 100644
--- a/bin/mkcatalog/columns.c
+++ b/bin/mkcatalog/columns.c
@@ -334,7 +334,7 @@ columns_sanity_check(struct mkcatalogparams *p)
           case UI_KEY_GEOSEMIMAJOR:
           case UI_KEY_GEOSEMIMINOR:
           case UI_KEY_GEOAXISRATIO:
-          case UI_KEY_HALFRADIUSOBS:
+          case UI_KEY_HALFSUMRADIUS:
           case UI_KEY_FRACMAXRADIUS1:
           case UI_KEY_FRACMAXRADIUS2:
           case UI_KEY_GEOPOSITIONANGLE:
@@ -1835,8 +1835,9 @@ columns_define_alloc(struct mkcatalogparams *p)
             oiflag[ OCOL_FRACMAX2NUM ] = ciflag[ CCOL_FRACMAX2NUM ] = 1;
           break;
 
-        case UI_KEY_FWHMOBS:
-        case UI_KEY_HALFRADIUSOBS:
+        case UI_KEY_FWHM:
+        case UI_KEY_HALFMAXRADIUS:
+        case UI_KEY_HALFSUMRADIUS:
         case UI_KEY_FRACMAXRADIUS1:
         case UI_KEY_FRACMAXRADIUS2:
           unit           = "pixels";
@@ -1861,15 +1862,20 @@ columns_define_alloc(struct mkcatalogparams *p)
           oiflag[ OCOL_GXY        ] = ciflag[ CCOL_GXY        ] = 1;
           switch(colcode->v)
             {
-            case UI_KEY_FWHMOBS:
-              name="FWHM_OBS";
+            case UI_KEY_FWHM:
+              name="FWHM";
               oiflag[ OCOL_HALFMAXNUM  ] = ciflag[ CCOL_HALFMAXNUM  ] = 1;
               ocomment = "Full width at half maximum (accounting for 
ellipticity).";
               break;
-            case UI_KEY_HALFRADIUSOBS:
-              name="HALF_RADIUS_OBS";
+            case UI_KEY_HALFMAXRADIUS:
+              name="HALF_MAX_RADIUS";
+              oiflag[ OCOL_HALFMAXNUM  ] = ciflag[ CCOL_HALFMAXNUM  ] = 1;
+              ocomment = "Radius at half of maximum (accounting for 
ellipticity).";
+              break;
+            case UI_KEY_HALFSUMRADIUS:
+              name="HALF_SUM_RADIUS";
               oiflag[ OCOL_HALFSUMNUM  ] = ciflag[ CCOL_HALFSUMNUM  ] = 1;
-              ocomment = "Radius derived from area of half of total sum.";
+              ocomment = "Radius at half of total sum (accounting for 
ellipticity).";
               break;
             case UI_KEY_FRACMAXRADIUS1:
               name="FRAC_MAX_RADIUS_1";
@@ -2643,8 +2649,9 @@ columns_fill(struct mkcatalog_passparams *pp)
                                             oi[OCOL_HALFSUMNUM] );
           break;
 
-        case UI_KEY_FWHMOBS:
-        case UI_KEY_HALFRADIUSOBS:
+        case UI_KEY_FWHM:
+        case UI_KEY_HALFMAXRADIUS:
+        case UI_KEY_HALFSUMRADIUS:
         case UI_KEY_FRACMAXRADIUS1:
         case UI_KEY_FRACMAXRADIUS2:
           /* First derive the axis ratio (as 'tmp'), then set the index to
@@ -2653,13 +2660,14 @@ columns_fill(struct mkcatalog_passparams *pp)
                   / columns_second_order(pp, oi, UI_KEY_SEMIMAJOR, 0) );
           switch(key)
             {
-            case UI_KEY_FWHMOBS:        tmpind=OCOL_HALFMAXNUM;  break;
-            case UI_KEY_HALFRADIUSOBS:  tmpind=OCOL_HALFSUMNUM;  break;
+            case UI_KEY_FWHM:           tmpind=OCOL_HALFMAXNUM;  break;
+            case UI_KEY_HALFMAXRADIUS:  tmpind=OCOL_HALFMAXNUM;  break;
+            case UI_KEY_HALFSUMRADIUS:  tmpind=OCOL_HALFSUMNUM;  break;
             case UI_KEY_FRACMAXRADIUS1: tmpind=OCOL_FRACMAX1NUM; break;
             case UI_KEY_FRACMAXRADIUS2: tmpind=OCOL_FRACMAX2NUM; break;
             }
           tmp = sqrt( oi[tmpind]/(tmp*M_PI) );
-          if(key==UI_KEY_FWHMOBS)
+          if(key==UI_KEY_FWHM)
             ((float *)colarr)[oind] = tmp<1e-6 ? NAN : (tmp*2);
           else
             ((float *)colarr)[oind] = tmp<1e-6 ? NAN : tmp;
@@ -2995,21 +3003,23 @@ columns_fill(struct mkcatalog_passparams *pp)
                                               ci[CCOL_HALFSUMNUM] );
             break;
 
-          case UI_KEY_FWHMOBS:
-          case UI_KEY_HALFRADIUSOBS:
+          case UI_KEY_FWHM:
+          case UI_KEY_HALFMAXRADIUS:
+          case UI_KEY_HALFSUMRADIUS:
           case UI_KEY_FRACMAXRADIUS1:
           case UI_KEY_FRACMAXRADIUS2:
             tmp = ( columns_second_order(  pp, ci, UI_KEY_SEMIMINOR, 1)
                     / columns_second_order(pp, ci, UI_KEY_SEMIMAJOR, 1) );
             switch(key)
               {
-              case UI_KEY_FWHMOBS:        tmpind=CCOL_HALFMAXNUM;  break;
-              case UI_KEY_HALFRADIUSOBS:  tmpind=CCOL_HALFSUMNUM;  break;
+              case UI_KEY_FWHM:           tmpind=CCOL_HALFMAXNUM;  break;
+              case UI_KEY_HALFMAXRADIUS:  tmpind=CCOL_HALFMAXNUM;  break;
+              case UI_KEY_HALFSUMRADIUS:  tmpind=CCOL_HALFSUMNUM;  break;
               case UI_KEY_FRACMAXRADIUS1: tmpind=CCOL_FRACMAX1NUM; break;
               case UI_KEY_FRACMAXRADIUS2: tmpind=CCOL_FRACMAX2NUM; break;
               }
             tmp = sqrt( ci[tmpind]/(tmp*M_PI) );
-            if(key==UI_KEY_FWHMOBS)
+            if(key==UI_KEY_FWHM)
               ((float *)colarr)[cind] = tmp<1e-6 ? NAN : (tmp*2);
             else
               ((float *)colarr)[cind] = tmp<1e-6 ? NAN : tmp;
diff --git a/bin/mkcatalog/ui.h b/bin/mkcatalog/ui.h
index 265a315..ca31c7e 100644
--- a/bin/mkcatalog/ui.h
+++ b/bin/mkcatalog/ui.h
@@ -174,13 +174,14 @@ enum option_keys_enum
   UI_KEY_GEOSEMIMINOR,
   UI_KEY_GEOAXISRATIO,
   UI_KEY_GEOPOSITIONANGLE,
-  UI_KEY_FWHMOBS,
+  UI_KEY_FWHM,
   UI_KEY_HALFMAXAREA,
+  UI_KEY_HALFMAXRADIUS,
   UI_KEY_HALFMAXSUM,
   UI_KEY_HALFMAXSB,
   UI_KEY_HALFSUMAREA,
   UI_KEY_HALFSUMSB,
-  UI_KEY_HALFRADIUSOBS,
+  UI_KEY_HALFSUMRADIUS,
   UI_KEY_FRACMAXSUM1,
   UI_KEY_FRACMAXSUM2,
   UI_KEY_FRACMAXAREA1,
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index b4964ea..f047a3d 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -16773,7 +16773,7 @@ For clumps, the average river flux is subtracted from 
the sky subtracted median.
 The maximum value of pixels within the object or clump.
 When the label (object or clump) is larger than three pixels, the maximum is 
actually derived by the mean of the brightest three pixels, not the largest 
pixel value of the same label.
 This is because noise fluctuations can be very strong in the extreme values of 
the objects/clumps due to Poisson noise (which gets stronger as the mean gets 
higher).
-Simply using the maximum pixel value will create a strong scatter in results 
that depend on the maximum (for example the @option{--fwhmobs} option also uses 
this value internally).
+Simply using the maximum pixel value will create a strong scatter in results 
that depend on the maximum (for example the @option{--fwhm} option also uses 
this value internally).
 
 @item --sigclip-number
 The number of elements/pixels in the dataset after sigma-clipping the object 
or clump.
@@ -16897,12 +16897,12 @@ first two dimensions. This is only available for 
3-dimensional
 datasets. When working with Integral Field Unit (IFU) datasets, this
 projection onto the first two dimensions would be a narrow-band image.
 
-@item --fwhmobs
+@item --fwhm
 @cindex FWHM
 The full width at half maximum (in units of pixels, along the semi-major axis) 
of the labeled region (object or clump).
 The maximum value is estimated from the mean of the top-three pixels with the 
highest values, see the description under @option{--maximum}.
 The number of pixels that have half the value of that maximum are then found 
(value in the @option{--halfmaxarea} column) and a radius is estimated from the 
area.
-See the description under @option{--halfradiusobs} for more on converting area 
to radius along major axis.
+See the description under @option{--halfsumradius} for more on converting area 
to radius along major axis.
 
 Because of its non-parametric nature, this column is most reliable on clumps 
and should only be used in objects with great causion.
 This is because objects can have more than one clump (peak with true signal) 
and multiple peaks are not treated separately in objects, so the result of this 
column will be biased.
@@ -16914,12 +16914,16 @@ For example if a labeled region's maximum is less 
than 2 times the sky standard
 For a more reliable value, this fraction should be around 4 (so half the 
maximum is 2@mymath{\sigma}).
 
 @item --halfmaxarea
-The number of pixels containing half the maximum flux within the labeled 
region.
-This option is used to estimate @option{--fwhmobs}, so please read the notes 
there for the cavaeats and necessary precautions.
+The number of pixels with values larger than half the maximum flux within the 
labeled region.
+This option is used to estimate @option{--fwhm}, so please read the notes 
there for the cavaeats and necessary precautions.
+
+@item --halfmaxradius
+The radius of region containing half the maximum flux within the labeled 
region.
+This is just half the value reported by @option{--fwhm}.
 
 @item --halfmaxsum
 The sum of the pixel values containing half the maximum flux within the 
labeled region (or those that are counted in @option{--halfmaxarea}).
-This option uses the pixels within @option{--fwhmobs}, so please read the 
notes there for the cavaeats and necessary precautions.
+This option uses the pixels within @option{--fwhm}, so please read the notes 
there for the cavaeats and necessary precautions.
 
 @item --halfmaxsb
 The surface brightness (in units of mag/arcsec@mymath{^2}) within the region 
that contains half the maximum value of the labeled region.
@@ -16939,7 +16943,7 @@ For more on the definition of the surface brightness, 
see @ref{Brightness flux m
 This column just plugs in the values of half the value of the 
@option{--brightness} column and the @option{--halfsumarea} column, into the 
surface brightness equation.
 Therefore please see the description in @option{--halfsumarea} to understand 
the systematics of this column and potential biases.
 
-@item --halfradiusobs
+@item --halfsumradius
 Radius (in units of pixels) derived from the area that contains half the total 
sum of the label's pixels (value reported by @option{--halfsumarea}).
 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,
@@ -16979,7 +16983,7 @@ Hence, added with these two columns, you can sample 
three parts of the profile's
 Radius (in units of pixels) derived from the area that contains the given 
fractions of the maximum valued pixel(s) of the label's pixels (value reported 
by @option{--fracmaxarea1} or @option{--fracmaxarea2}).
 For the maximum value, see the description of @option{--maximum} column below.
 The fractions are given through the @option{--fracmax} option (that can take 
two values) and is described in @ref{MakeCatalog inputs and basic settings}.
-Recall that in @option{--fwhmobs}, the fraction is fixed to 0.5.
+Recall that in @option{--fwhm}, the fraction is fixed to 0.5.
 Hence, added with these two columns, you can sample three parts of the 
profile's radius.
 
 @item --clumpsarea