[gnuastro-commits] master 1c315f8 2/3: Radial profile: undersampling the apertures before filling the 0 pixel

[Mohammad Akhlaghi]

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

    Radial profile: undersampling the apertures before filling the 0 pixel
    
    Until this commit, the filling of the central pixel was done after the
    undersampling of the aperture image. However, in order to make the script
    more general and simpler, with this commit, this step has been changed. Now
    the filling of the central pixel (0 value in the aperture image) is done
    after the undersampling (re-binning) of the aperture image. If the
    undersampling is not requested, then just a symbolic link is created.  In
    addition to this, some extra information have been added to the script and
    the Book in order to describe in a better way some steps.
---
 bin/script/radial-profile.in | 49 +++++++++++++++++++++++++-------------------
 doc/gnuastro.texi            |  7 +++++--
 2 files changed, 33 insertions(+), 23 deletions(-)

diff --git a/bin/script/radial-profile.in b/bin/script/radial-profile.in
index 0abe0ed..c78e3eb 100755
--- a/bin/script/radial-profile.in
+++ b/bin/script/radial-profile.in
@@ -96,14 +96,14 @@ $scriptname options:
   -p, --positionangle=FLT Position angle for ellipse profiles.
   -s, --sigmaclip=FLT,FLT Sigma-clip multiple and tolerance.
       --zeropoint=FLT     Zeropoint magnitude of input dataset.
-      --undersample=INT   Number of pixels to consider for re-binning.
 
  Output:
+  -o, --output            Output table with the radial profile.
   -t, --tmpdir            Directory to keep temporary files.
   -k, --keeptmp           Keep temporal/auxiliar files.
   -m, --measure=STR       Measurement operator (mean, sigclip-mean, etc.).
-  -o, --output            Output table with the radial profile.
   -v, --oversample        Oversample for higher resolution radial profile.
+  -u, --undersample=INT   Undersample for lower resolution radial profile.
       --instd=FLT/STR     Sky standard deviation as a single number or as the
                           filename containing the dataset with different values
                           per pixel.
@@ -234,6 +234,9 @@ do
         -v|--oversample)  oversample="$2";                          check_v 
"$1" "$oversample"; shift;shift;;
         -v=*|--oversample=*) oversample="${1#*=}";                  check_v 
"$1" "$oversample"; shift;;
         -v*)              oversample=$(echo "$1" | sed -e's/-v//'); check_v 
"$1" "$oversample"; shift;;
+        -u|--undersample) undersample="$2";                          check_v 
"$1" "$undersample"; shift;shift;;
+        -u=*|--undersample=*) undersample="${1#*=}";                  check_v 
"$1" "$undersample"; shift;;
+        -u*)              undersample=$(echo "$1" | sed -e's/-u//'); check_v 
"$1" "$undersample"; shift;;
         --instd=*)        instd="${1#*=}";                          check_v 
"$1" "$instd"; shift;;
         --stdhdu=*)       stdhdu="${1#*=}";                         check_v 
"$1" "$stdhdu"; shift;;
 
@@ -288,7 +291,7 @@ if [ x"$center" != x ]; then
     fi
 fi
 
-# Make sure the value to '--mode' is either 'wcs' or 'img'. 
+# Make sure the value to '--mode' is either 'wcs' or 'img'.
 if [ $mode = "wcs" ] || [ $mode = "img" ]; then
     junk=1
 else
@@ -534,29 +537,33 @@ echo "1 $xcenter $ycenter 7 $rmax 1 $positionangle 
$axisratio 1 1" \
 
 
 
-# Fill the central pixel(s)
-# -------------------------
+# Undersampling the aperture image
+# --------------------------------
 #
-# The central pixel(s) have a distance of 0! So we need to add a single
-# value to all the profile pixels (but keep the outer parts at 0).
-apertures=$tmpdir/apertures.fits
-astarithmetic $aperturesraw set-i \
-              i 0 ne 1 fill-holes set-good \
-              i good i 1 + where -o$apertures
+# The undersampling is for making the size of the apertures larger so the
+# number of pixels on each aperture (at each radius) will be larger. Most
+# of times this option is good to average over a larger number of pixels
+# and increase the signal-to-noise ratio of the measurement.
+aperturesrebinned=$tmpdir/apertures-rebin.fits
+if [ x"$undersample" != x ]; then
+    astarithmetic $aperturesraw $undersample / -o$aperturesrebinned
+else
+    ln -fs $aperturesraw $aperturesrebinned
+fi
 
 
 
 
 
-# Re-bin the aperture image if necessary
+# Fill the central pixel(s)
 # -------------------------
 #
-# The re-binning scenario is done if the user asked.
-rebinapertures=$tmpdir/rebin-apertures.fits
-if [ x"$undersample" != x ]; then
-    astarithmetic $apertures $undersample / -o$rebinapertures
-    cp $rebinapertures $apertures
-fi
+# The central pixel(s) have a distance of 0! So we need to add a single
+# value to all the profile pixels (but keep the outer parts at 0).
+apertures=$tmpdir/apertures.fits
+astarithmetic $aperturesrebinned set-i \
+              i 0 ne 1 fill-holes set-good \
+              i good i 1 + where -o$apertures
 
 
 
@@ -614,9 +621,9 @@ astmkcatalog $apertures -h1 --valuesfile=$values 
--valueshdu=1 --ids \
 #
 # The raw MakeCatalog output isn't clear for the users of this script (for
 # example the radius column is called 'OBJ_ID'!). Also, when oversampling
-# is requested we need to divide the radii by the over-sampling factor.
-# Also, when re-binning(undersampling) is requested we need to multiple the
-# radii by the undersample factor.
+# is requested, we need to divide the radii by the over-sampling factor.
+# In the same way, when undersampling (re-binning) is requested, we need to
+# multiple the radii by the undersample factor.
 #
 # But before anything, we need to set the options to print the other
 # columns untouched (we only want to change the first column).
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index 56e05f1..44060ad 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -22051,9 +22051,12 @@ Oversample the input dataset to the fraction given to 
this option.
 Therefore if you set @option{--rmax=20} for example and 
@option{--oversample=5}, your output will have 100 rows (without 
@option{--oversample} it will only have 20 rows).
 Unless the object is heavily undersampled (the pixels are larger than the 
actual object), this method provides a much more accurate result and there are 
sufficient number of pixels to get the profile accurately.
 
+@item -u INT
 @item --undersample=INT
-Undersample the input dataset.
-If you define this option, the size which gave to this option considers as a 
re-bin size to do rebinning and do the calculation on the rebinned image, which 
allow you to decrease the noise.
+Undersample the input dataset by the number given to this option.
+This option is for considering larger apertures than the original pixel size 
(aperture size is equal to 1 pixel).
+For example, if a radial profile computed by default has 100 different radii 
(apertures of 1 pixel width), by considering @option{--undersample=2} the 
radial profile will be computed over apertures of 2 pixels, so the final radial 
profile will have 50 different radii.
+This option is good to measure over a larger number of pixels to improve the 
measurement.
 
 @item --instd=FLT/STR
 Sky standard deviation as a single number (FLT) or as the filename (STR) 
containing the image with the std value for each pixel (the HDU within the file 
should be given to the @option{--stdhdu} option mentioned below).