[gnuastro-commits] master f0fcad5 7/7: astscript-radial-profile: Removed special sn option

[Mohammad Akhlaghi]

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

    astscript-radial-profile: Removed special sn option
    
    Until now the radial profile script had a special option for the
    signal-to-noise ratio (S/N)! However the S/N is already a "--measure" that
    is provided by MakeCatalog. Having a separate option only for this column
    made the script hard for the users to use (an extra option), and for the
    maintainers to maintain (complexities in variable checking).
    
    With this commit, this option has been removed, and within the manual the
    user is instructed to use '--measure=sn' if they want the S/N. During the
    process and while inspecting the code, I also made these corrections:
    
     - A new '--zeropoint' option has been added to the radial profile script
       so users can ask for things like the magnitude or surface brightness.
    
     - In the part where we converted WCS coordinates into pixel coordinates,
       the "sed 's/,/ /'" was extra (because Gnuastro programs, including
       'asttable' in this case, automatically separate columns by a comma).
    
     - With this commit, the '--stdhdu' option is optional (it is no longer
       used to distinguish a file from a number). To see if the value of
       '--stdhdu' is a file, we simply use 'if [ -f $stdhdu ]' (since it should
       exist anyway).
    
     - The 'tests/during-dev.sh' script (that is used for testing Gnuastro's
       programs and scripts) has been modified by including all the programs'
       configuration files during the build, and also including the place of
       all the built programs into the PATH. In this way, when testing an
       'astscript' with 'tests/during-dev.sh', we can be sure that the
       currently under-development programs will be used by the 'astscript-*'.
---
 bin/script/radial-profile.in | 113 +++++++++++++++++--------------------------
 doc/gnuastro.texi            |  59 +++++++++++-----------
 tests/during-dev.sh          |  15 ++++++
 3 files changed, 86 insertions(+), 101 deletions(-)

diff --git a/bin/script/radial-profile.in b/bin/script/radial-profile.in
index 2eaad77..38f9814 100755
--- a/bin/script/radial-profile.in
+++ b/bin/script/radial-profile.in
@@ -33,7 +33,6 @@ set -e
 
 
 # Default option values (can be changed with options on the command-line).
-sn=""
 hdu=1
 rmax=""
 quiet=""
@@ -46,6 +45,7 @@ keeptmp=0
 mode="img"
 measure=""
 axisratio=1
+zeropoint=""
 sigmaclip=""
 measuretmp=""
 oversample=""
@@ -95,6 +95,7 @@ $scriptname options:
   -Q, --axisratio=FLT     Axis ratio for ellipse profiles (A/B).
   -p, --positionangle=FLT Position angle for ellipse profiles.
   -s, --sigmaclip=FLT,FLT Sigma-clip multiple and tolerance.
+      --zeropoint=FLT     Zeropoint magnitude of input dataset.
 
  Output:
   -t, --tmpdir            Directory to keep temporary files.
@@ -112,8 +113,6 @@ $scriptname options:
       --cite              BibTeX citation for this program.
   -q, --quiet             Don't print the list.
   -V, --version           Print program version.
-  -n, --sn                The signal to noise ratio of the profile is 
calculated
-                          according to instd and stdhdu.
 
 Mandatory or optional arguments to long options are also mandatory or optional
 for any corresponding short options.
@@ -216,6 +215,7 @@ do
         -s|--sigmaclip)     sigmaclip="$2";                            check_v 
"$1" "$sigmaclip";  shift;shift;;
         -s=*|--sigmaclip=*) sigmaclip="${1#*=}";                       check_v 
"$1" "$sigmaclip";  shift;;
         -s*)                sigmaclip=$(echo "$1"  | sed -e's/-s//');  check_v 
"$1" "$sigmaclip";  shift;;
+        --zeropoint=*)      zeropoint="${1#*=}";                       check_v 
"$1" "$zeropoint";  shift;;
 
         # Output parameters
         -k|--keeptmp)     keeptmp=1; shift;;
@@ -244,7 +244,6 @@ do
         -V*|--version=*)  on_off_option_error --version -V;;
         --cite)           astfits --cite; exit 0;;
         --cite=*)         on_off_option_error --cite;;
-        --sn)             sn=1; shift;;
 
         # Unrecognized option:
         -*) echo "$scriptname: unknown option '$1'"; exit 1;;
@@ -302,39 +301,6 @@ if [ x"$measure" = x ]; then measure=mean; fi
 
 
 
-# Check and set SNR parameters and variables
-# ------------------------------------------
-#
-# --sn  --instd  --stdhdu  instdtype
-#   yes   no       yes       file (same as input image)
-#   yes   yes      yes       file (independent file)
-#   yes   no       no        error
-#   yes   yes      no        number (std value)
-
-if [ x"$sn" != x ]; then
-    finalsn="--sn "
-    if [ x"$stdhdu" != x ]; then
-        instdtype="file"
-        if [ x"$instd" = x ]; then instd=$inputs; fi
-    else
-        if [ x"$instd" != x ]; then
-            instdtype="number"
-        else
-            echo "No stdhdu has been entered \
-                  neither a numerical value for instd."
-            exit 1
-        fi
-    fi
-    finalinstd="--instd=$instd "
-else
-   finalsn=""
-   finalinstd=""
-fi
-
-
-
-
-
 # Finalize the center value
 # -------------------------
 #
@@ -351,26 +317,24 @@ if [ x"$center" = x ]; then
     xcenter=$(astfits $inputs --hdu=$hdu | awk '/^NAXIS1/{print $3/2+0.5}')
     ycenter=$(astfits $inputs --hdu=$hdu | awk '/^NAXIS2/{print $3/2+0.5}')
 
+# A center is given.
 else
 
+    # The central position is in image mode; we should just separate each
+    # coordinate.
     if [ $mode = img ]; then
-
-        # A center has been given, we should just separate them.
         xcenter=$(echo "$center" | awk 'BEGIN{FS=","} {print $1}')
         ycenter=$(echo "$center" | awk 'BEGIN{FS=","} {print $2}')
 
+    # The center is in WCS coordinates. We should thus convert them to
+    # image coordinates at this point. To do that, WCS information from the
+    # input header image is used.
     else
-
-        # WCS coordinates have been given. We should thus convert them to
-        # image coordinates at this point. To do that, WCS information from
-        # the input header image is used.
         xy=$(echo "$center" \
-                  | sed 's/,/ /' \
                   | asttable -c'arith $1 $2 wcstoimg' \
                              --wcsfile=$inputs --wcshdu=$hdu)
         xcenter=$(echo $xy | awk '{print $1}');
         ycenter=$(echo $xy | awk '{print $2}');
-
     fi
 fi
 
@@ -448,21 +412,29 @@ if [ -d $tmpdir ]; then junk=1; else mkdir $tmpdir; fi
 # and third value of that string, and convert to the cropped coordinate
 # system. Note that because FITS pixel couting starts from 1, we need to
 # subtract `1'.
+#
+# For the standard deviation, besides being empty or not, we first need to
+# make sure it is actually a file (note that it can also be a number). If
+# its a file, we'll crop it and set 'instd' to be the new cropped file.
 crop=$tmpdir/crop.fits
+cropstd=$tmpdir/crop-std.fits
 cropwidth=$(echo $rmax | awk '{print $1*2+1}')
 astcrop $inputs --hdu=$hdu --center=$xcenter,$ycenter --mode=img \
         --width=$cropwidth --output=$crop $quiet
-
-if [ x"$sn" != x ]; then
-    if [ "$instdtype" = "file" ]; then
-        cropstd=$tmpdir/cropstd.fits
-        astcrop $instd -h$stdhdu --center=$xcenter,$ycenter \
-                --mode=img --width=$cropwidth --output=$cropstd $quiet
-        finalinstd="--instd=$cropstd "
+if [ x"$instd" != x ] && [ -f "$instd" ]; then
+    if [ x"$stdhdu" = x ]; then instdhduopt="";
+    else                        instdhduopt="--hdu=$stdhdu";
     fi
+    astcrop "$instd" "$instdhduopt" --center=$xcenter,$ycenter \
+            --mode=img --width=$cropwidth --output=$cropstd $quiet
 fi
 
 
+
+
+
+# Correct the central position (to cropped image)
+# -----------------------------------------------
 dxy=$(astfits $crop -h1 \
           | grep ICF1PIX \
           | sed -e"s/'/ /g" -e's/\:/ /g' -e's/,/ /' \
@@ -485,16 +457,19 @@ ycenter=$(echo "$ycenter $cropwidth $dxy" \
 # is over-sampled. This is only done if the user request this with the
 # option --oversample.
 values=$tmpdir/values.fits
+valuesstd=$tmpdir/valuesstd.fits
 if [ x$oversample = x ]; then
     ln -fs $crop $values
+    if [ x"$instd" != x ] && [ -f "$instd" ]; then
+        ln -fs $cropstd $valuesstd
+    fi
 else
-    astwarp $crop --scale=$oversample,$oversample -o$values
     xcenter=$(echo $xcenter | awk '{print '$oversample'*$1}')
     ycenter=$(echo $ycenter | awk '{print '$oversample'*$1}')
     rmax=$(echo    $rmax    | awk '{print '$oversample'*$1}')
-    if [ x"$sn" != x ] && [ $instdtype = "file" ]; then
-        astwarp $cropstd --scale=$oversample,$oversample -o$stdvalues
-        finalinstd="--instd="$stdvalues" "
+    astwarp $crop --scale=$oversample,$oversample -o$values
+    if [ x"$instd" != x ] && [ -f "$instd" ]; then
+        astwarp $cropstd --scale=$oversample,$oversample -o$valuesstd
     fi
 fi
 
@@ -557,15 +532,16 @@ finalmeasure=$(echo "$measure" \
 
 
 
-# Set the used sigma-clipping parameters
-# --------------------------------------
+# MakeCatalog configuration options
+# ---------------------------------
 #
-# If not given, don't use anything and just use MakeCatalog's default
+# If not given, don't use anything and just let MakeCatalog use its default
 # values.
-if [ x"$sigmaclip" = x ]; then
-    finalsigmaclip=""
-else
-    finalsigmaclip="--sigmaclip=$sigmaclip";
+if [ x"$sigmaclip" = x ]; then finalsigmaclip=""
+else                           finalsigmaclip="--sigmaclip=$sigmaclip";
+fi
+if [ x"$zeropoint" = x ]; then finalzp=""
+else                           finalzp="--zeropoint=$zeropoint";
 fi
 
 
@@ -581,9 +557,8 @@ fi
 # values.
 cat=$tmpdir/catalog.fits
 astmkcatalog $apertures -h1 --valuesfile=$values --valueshdu=1 --ids \
-             $finalsn $finalinstd $finalmeasure $finalsigmaclip \
-            --stdhdu=1 --output=$cat \
-             $quiet
+             $finalinstd $finalmeasure $finalsigmaclip $finalzp \
+            --stdhdu=1 --output=$cat $quiet
 
 
 
@@ -612,11 +587,11 @@ fi
 
 
 
-# Remove temporal files
-# ---------------------
+# Remove temporary files
+# ----------------------
 #
 # If the user does not specify to keep the temporal files with the option
 # `--keeptmp', then remove the whole directory.
 if [ $keeptmp = 0 ]; then
-    rm -rf $tmpdir
+    rm -r $tmpdir
 fi
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index a8fb258..ab03808 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -21176,17 +21176,13 @@ $ astscript-radial-profile image.fits
 
 ## Generate the radial profile centered at x=44 and y=37 (in pixels),
 ## up to  a radial distance of 19 pixels, use the mean value.
-$ astscript-radial-profile image.fits      \
-                           --center=44,37  \
-                           --rmax=19
+$ astscript-radial-profile image.fits --center=44,37 --rmax=19
 
 ## Generate the radial profile centered at x=44 and y=37 (in pixels),
 ## up to a radial distance of 100 pixels, compute sigma clipped
 ## mean and standard deviation (sigclip-mean and sigclip-std) using
 ## 3 sigma and 10 iterations.
-$ astscript-radial-profile image.fits       \
-                           --center=44,37   \
-                           --rmax=100       \
+$ astscript-radial-profile image.fits --center=44,37 --rmax=100 \
                            --sigmaclip=3,10 \
                            --measure=sigclip-mean,sigclip-std
 
@@ -21194,41 +21190,34 @@ $ astscript-radial-profile image.fits       \
 ## DEC=0.9454292263, up to a radial distance of 88 pixels,
 ## axis ratio equal to 0.32, and position angle of 148 deg.
 ## Name the output table as `radial-profile.fits'
-$ astscript-radial-profile image.fits --mode=wcs             \
+$ astscript-radial-profile image.fits --mode=wcs \
                            --center=20.53751695,0.9454292263 \
-                           --rmax=88                         \
-                           --axisratio=0.32                  \
+                           --rmax=88 --axisratio=0.32 \
                            --positionangle=148 -oradial-profile.fits
 
 ## Generate the radial profile centered at RA=40.062675270971,
 ## DEC=-8.1511992735126, up to a radial distance of 20 pixels,
 ## and calculate the SNR using the INPUT-NO-SKY and SKY-STD
 ## extensions of the NoiseChisel output file.
-$ astscript-radial-profile  image_detected.fits -hINPUT-NO-SKY        \
-                            --mode=wcs                                \
-                            --center=40.062675270971,-8.1511992735126 \
-                            --rmax=20                                 \
-                            --sn --stdhdu=SKY_STD
+$ astscript-radial-profile image_detected.fits -hINPUT-NO-SKY \
+                           --mode=wcs --measure=sn \
+                           --center=40.062675270971,-8.1511992735126 \
+                           --rmax=20 --stdhdu=SKY_STD
 
 ## Generate the radial profile centered at RA=40.062675270971,
 ## DEC=-8.1511992735126, up to a radial distance of 20 pixels,
 ## and compute the SNR with a fixed value for std, std=10.
-$ astscript-radial-profile  image.fits -h1                            \
-                            --mode=wcs                                \
-                            --rmax=20                                 \
-                            --center=40.062675270971,-8.1511992735126 \
-                            --sn --instd=10
+$ astscript-radial-profile image.fits -h1 --mode=wcs --rmax=20 \
+                           --center=40.062675270971,-8.1511992735126 \
+                           --measure=sn --instd=10
 
 ## Generate the radial profile centered at X=1201, Y=1201 pixels, up
 ## to a radial distance of 20 pixels and compute the median and the
 ## SNR using the first extension of sky-std.fits as the dataset for std
 ## values.
-$ astscript-radial-profile image.fits -h1                             \
-                           --mode=img                                 \
-                           --rmax=20                                  \
-                           --center=1201,1201                         \
-                           --measure=median                           \
-                           --sn --instd=sky-std.fits --stdhdu=1
+$ astscript-radial-profile image.fits -h1 --mode=img --rmax=20 \
+                           --center=1201,1201 --measure=median,sn \
+                           --instd=sky-std.fits
 @end example
 
 This installed script will read a FITS image and will use it as the basis for 
constructing the radial profile.
@@ -21310,11 +21299,15 @@ By default, it is @option{--pangle=0}, which means 
that the semi-major axis of t
 @itemx --measure=STR
 The operator for measuring the values over each radial distance.
 The values given to this option will be directly passed to @ref{MakeCatalog}.
-As a consequence, all MakeCatalog measurements like the median, mean, std, 
sigclip-mean, sigclip-number, etc. can be used here.
+As a consequence, all MakeCatalog measurements like the magnitude, magnitude 
error, median, mean, signal-to-noise ratio (S/N), std, surface brightness, 
sigclip-mean, sigclip-number, etc. can be used here.
 For a full list of MakeCatalog's measurements, please run 
@command{astmkcatalog --help}.
 Multiple values can be given to this option, each separated by a comma.
 This option can also be called multiple times.
 
+Some measurements by MakeCatalog require a per-pixel sky standard deviation 
(for example magnitude error or S/N).
+Therefore when asking for such measurements, use the @option{--instd} option 
(described below) to specify the per-pixel sky standard deviation over each 
pixel.
+For other measurements like the magnitude or surface brightness, MakeCatalog 
will need a Zeropoint, which you can set with the @option{--zeropoint} option.
+
 For example, by setting @option{--measure=mean,sigclip-mean --measure=median}, 
the mean, sigma-clipped mean and median values will be computed.
 The output radial profile will have 4 columns in this order: radial distance, 
mean, sigma-clipped and median.
 By default (when this option isn't given), the mean of all pixels at each 
radial position will be computed.
@@ -21331,6 +21324,10 @@ To see the default value of this option in 
MakeCatalog, you can run this command
 $ astmkcatalog -P | grep " sigmaclip "
 @end example
 
+@item --zeropoint=FLT
+The Zeropoint of the input dataset.
+This is necessary when you request measurements like Magnitude, or Surface 
brightess.
+
 @item -v INT
 @itemx --oversample=INT
 Oversample the input dataset to the fraction given to this option.
@@ -21338,14 +21335,12 @@ Therefore if you set @option{--rmax=20} for example 
and @option{--oversample=5},
 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 --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. Only relevant if 
@option{--sn} is requested.
+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).
+This is only necessary when the requested measurement (value given to 
@option{--measure}) by MakeCatalog needs the Standard deviation (for example 
the signal-to-noise ratio or magnitude error).
+If your measurements don't require a standard deviation, it is best to ignore 
this option (because it will slow down the script).
 
 @item --stdhdu=STR
-HDU/extension of the sky standard deviation image specified with 
@option{--instd}. Only relevant if @option{--sn} is requested.
-
-@item  -n
-@item --sn
-Compute the signal to noise ratio for each radius of the profile according to 
@option{--instd} and @option{--stdhdu}. A new column named SN is added to the 
output radial profile.
+HDU/extension of the sky standard deviation image specified with 
@option{--instd}.
 
 @item -t STR
 @itemx --tmpdir=STR
diff --git a/tests/during-dev.sh b/tests/during-dev.sh
index 3d14f4a..3cd5b22 100755
--- a/tests/during-dev.sh
+++ b/tests/during-dev.sh
@@ -181,6 +181,21 @@ if make -j$numjobs -C "$builddir"; then
     echo ""               >> .gnuastro/gnuastro.conf
     echo " lastconfig 1"  >> .gnuastro/gnuastro.conf
 
+    # A script can call any of the Gnuastro programs, we need to add this
+    # installation's programs in the PATH and add all configuration files.
+    if [ x"$longprefix" = x"script" ]; then
+        addpath=""
+        for f in "$builddir"/bin/*; do
+            if [ -d $f ]; then
+                if [ x"$addpath" = x ]; then addpath="$f"
+                else                         addpath="$f:$addpath"
+                fi
+            fi
+        done
+        export PATH="$addpath:$PATH"
+        cp "$srcdir"/bin/*/*.conf .gnuastro/
+    fi
+
     # Run the built utility with the given arguments and options.
     "$utility" $arguments $options $extraopts