[gnuastro-commits] master 04a8bec 29/32: Book: simplifying documentation of astscript-radial-profile

[Mohammad Akhlaghi]

branch: master
commit 04a8bec9dc4c5e6f8fd0911c42fdc273cdf3094e
Author: Raul Infante-Sainz <infantesainz@gmail.com>
Commit: Raul Infante-Sainz <infantesainz@gmail.com>

    Book: simplifying documentation of astscript-radial-profile
    
    Until this commit, the documentation of the radial profile script were
    not updated properly according with the modification of the previous
    commits. So, the documentation was not describing the actual script.
    
    With this commit, the description of the radial profile script and its
    options have been modified in order to consider the latest
    modifications. In addition to that, very minor modifications in the
    actual code of the script was done. The main one is to not use the
    program `realpath' when considering the temporal directory.
---
 bin/script/radial-profile.in |  20 ++++----
 doc/gnuastro.texi            | 118 +++++++++++++++++--------------------------
 2 files changed, 56 insertions(+), 82 deletions(-)

diff --git a/bin/script/radial-profile.in b/bin/script/radial-profile.in
index 2cc361e..050cd6e 100644
--- a/bin/script/radial-profile.in
+++ b/bin/script/radial-profile.in
@@ -209,13 +209,15 @@ do
         -m*)                measure=$(echo "$1"  | sed -e's/-m//');    check_v 
"$1" "$measure";  shift;;
         -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;;
+        -s*)                sigmaclip=$(echo "$1"  | sed -e's/-s//');  check_v 
"$1" "$sigmaclip";  shift;;
+
 
         # Output parameters
         -k|--keeptmp)     keeptmp=1; shift;;
         -k*|--keeptmp=*)  on_off_option_error --keeptmp -k;;
-        --tmpdir)         tmpdir="$2";                          check_v "$1" 
"$tmpdir"; shift;shift;;
-        --tmpdir=*)       tmpdir="${1#*=}";                     check_v "$1" 
"$tmpdir"; shift;;
+        -t|--tmpdir)      tmpdir="$2";                          check_v "$1" 
"$tmpdir";  shift;shift;;
+        -t=*|--tmpdir=*)  tmpdir="${1#*=}";                     check_v "$1" 
"$tmpdir";  shift;;
+        -t*)              tmpdir=$(echo "$1" | sed -e's/-t//'); check_v "$1" 
"$tmpdir";  shift;;
         -o|--output)      output="$2";                          check_v "$1" 
"$output"; shift;shift;;
         -o=*|--output=*)  output="${1#*=}";                     check_v "$1" 
"$output"; shift;;
         -o*)              output=$(echo "$1" | sed -e's/-o//'); check_v "$1" 
"$output"; shift;;
@@ -354,13 +356,13 @@ bname_prefix=$(basename $inputs | sed 's/\.fits/ /' | awk 
'{print $1}')
 defaultname=$(pwd)/"$bname_prefix"_rprofile_$mode"_$xcenter"_"$ycenter"
 if [ z$output = zdefault ]; then output="$defaultname.fits"; fi
 
-# Construct the temporal directory. There, necessary temporal files will be
-# kept during the execution of the script. If the user wants to keep this
-# directory (--keeptmp option), it will not be deleted.
+# Construct the temporal directory. If the user does not specify any directory,
+# then a default one with the base name of the input image will be constructed.
+# If the user set the directory, then make it. This directory will be deleted
+# at the end of the script if the user does not want to keep it (with the
+# `--keeptmp' option).
 if [ z$tmpdir = z        ]; then tmpdir=$defaultname
-else                             tmpdir=$(realpath $tmpdir); fi
-if ! [ -d $tmpdir ]; then mkdir $tmpdir; fi
-
+else                             mkdir -p $tmpdir; fi
 
 
 
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index 25f7e0e..079b30e 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -15679,13 +15679,12 @@ Sometimes it is necessary to compute a radial profile 
of an astronomical object.
 For example, imagine you want to study how the light of a galaxy is 
distributed as a function of the radial distance from the center.
 This is exactly what a radial profile is.
 Gnuastro's @file{astscript-radial-profile} script is created to obtain such 
radial profiles.
-It uses @command{astmkprof} to generate elliptical apertures with the values 
equal to the distance from the center of the object and @command{astmkcatalog} 
for measuring the values and signal to noise ratio over the apertures.
-With the default options, the script will generate a circular radial profile 
up to a radial distance of 10 pixels using the median value and centered at the 
center of the image.
+It uses @command{astmkprof} to generate elliptical apertures with the values 
equal to the distance from the center of the object and @command{astmkcatalog} 
for measuring the values over the apertures.
+With the default options, the script will generate a circular radial profile 
using the mean value and centered at the center of the image.
 In order to have more flexibility, several options are available and the user 
can play with them in order to obtain the wanted radial profile.
-In this sense, it can be changed the center position, the maximum radius, the 
axis ratio and the position angle (because elliptical apertures are 
considered), the operator for obtaining the values, and some other options.
-In addition to this, the user is also able to binning the data and operate 
both columns for changing them from the original computed values.
+In this sense, it can be changed the center position, the maximum radius, the 
axis ratio and the position angle (elliptical apertures are considered), the 
operator for obtaining the values, and some other options.
 
-@node Invoking astscript-radial-profile, Radial Profile
+@node Invoking astscript-radial-profile, Radial profile
 @subsection Invoking astscript-radial-profile
 
 For more on installed scripts please see (see @ref{Installed scripts}).
@@ -15703,19 +15702,26 @@ Examples:
 $ 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, and
-## name the output columns `RADIUS` and `VALUES`.
-$ astscript-radial-profile image.fits      \
-                            --mode=img     \
-                            --xcenter=44   \
-                            --ycenter=37   \
-                            --rmax=19      \
-                            --iname=RADIUS \
-                            --jname=VALUES
+## up to  a radial distance of 19 pixels, use the mean value.
+$ astscript-radial-profile image.fits     \
+                           --xcenter=44   \
+                           --ycenter=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, sigclip-std) using
+## 3 sigma and 10 iterations.
+$ astscript-radial-profile image.fits       \
+                           --xcenter=44     \
+                           --ycenter=37     \
+                           --rmax=100       \
+                           --sigmaclip=3,10 \
+                           --measure="sigclip-mean sigclip-std"
 
 ## Generate the radial profile centered at RA=20.53751695,
 ## DEC=0.9454292263, up to a radial distance of 88 pixels,
-## axis ratio equal to 0.32 and position  angle of 148 deg.
+## 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   \
                            --xcenter=20.53751695   \
@@ -15726,7 +15732,7 @@ $ astscript-radial-profile image.fits --mode=wcs   \
 @end example
 
 This installed script will read a FITS image and will use it as the basis for 
constructing the radial profile.
-The output radial profile is a FITS table with two columns: radius and 
measured values.
+The output radial profile consists in a FITS table containing the radial 
distance from the center in the first column and the specified measurements in 
the other columns (mean, median, sigclip-mean, sigclip-median, etc.).
 
 @table @option
 @item -h STR
@@ -15735,18 +15741,18 @@ The HDU/extension to use.
 
 @item -O STR
 @itemx --mode=STR
-Interpret the center position of center position (@option{--xcenter} and 
@option{--ycenter}) in image or WCS coordinates.
-This option thus accepts only two values: @option{img} and @option{wcs}.
+Interpret the center position of the object (@option{--xcenter} and 
@option{--ycenter}) in image or WCS coordinates.
+This option thus accepts only two values: @option{img} or @option{wcs}.
 By default, it is @option{--mode=img}.
 
 @item -x FLT
 @itemx --xcenter=FLT
 Center coordinate along the first dimension.
 This option will be used for placing the center of the profiles.
-If @option{--mode=img} is considered, then @option{--xcenter} has to be in 
image coordinates.
-If @option{--mode=wcs} is considered, then @option{--xcenter} has to be in WCS 
coordinates.
+If @option{--mode=img} is considered, then @option{--xcenter} has to be in 
image units (pixels).
+If @option{--mode=wcs} is considered, then @option{--xcenter} has to be in WCS 
units.
 By default, it is @option{--xcenter=center}, which means that it will put the 
center of the radial profiles in the center of the image.
-This parameter is used as the @option{--ccol} option for generating the 
profiles with @command{astmkprof}.
+This parameter is used as the @option{--ccol} option for generating the 
apertures with @command{astmkprof}.
 
 @item -y FLT
 @itemx --ycenter=FLT
@@ -15756,12 +15762,12 @@ Same than @option{--xcenter} argument, but for the 
second dimension (see above f
 @item -R FLT
 @itemx --rmax=FLT
 Maximum radius for the radial profile (in pixels).
-By default, it is @option{--rmax=10}, which means that the radial profile will 
be computed up to a radial distance of 10 pixels from the centers.
+By default, it is @option{--rmax=max}, which means that the radial profile 
will be computed up to a radial distance equal to the maximum radius that fits 
into the image (assuming circular shape).
 This parameter is used as the options @option{--fcol} and @option{--tcol} in 
the generation of the apertures with @command{astmkprof}.
 
 @item -Q FLT
 @itemx --qratio=FLT
-The axis ratio of the profiles (minor axis divided by the major axis in a 2D 
ellipse).
+The axis ratio of the apertures (minor axis divided by the major axis in a 2D 
ellipse).
 By default, it is @option{--qratio=1}, which means that the radial profile 
will be circular.
 This parameter is used as the option @option{--qcol} in the generation of the 
apertures with @command{astmkprof}.
 
@@ -15771,69 +15777,35 @@ The position angle (in degrees) of the profiles 
relative to the first FITS axis
 By default, it is @option{--pangle=0}, which means that the semi-major axis of 
the profiles will be parallel to the first FITS axis.
 This parameter is used as the option @option{--pcol} in the generation of the 
apertures with @command{astmkprof}.
 
-@item -m STR
-@itemx --measure=STR
-The operator for measuring the values over each different profile.
-By default, it is @option{--measure=median}, which means that the median of 
all pixels inside each profile will be computed.
+@item -m "STR"
+@itemx --measure="STR"
+The operator for measuring the values over each different aperture.
+By default, it is @option{--measure="--mean"}, which means that the mean of 
all pixels inside each aperture will be computed.
 This parameter is used for computing the measured values with 
@command{astmkcatalog}.
 As a consequence, all operators like median, mean, std, sigclip-mean, 
sigclip-number, etc. can be used here.
+Multiple operators can be specified at once.
+For example, by setting @option{--measure="--mean --median"} the mean and 
median values will be computed.
+In this case, the output radial profile will have 3 columns: radial distance, 
mean, and median.
 
 @item -s FLT,FLT
 @itemx --sigmaclip=FLT,FLT
 Sigma clipping parameters if @option{--measure} operator requested is any of 
the available sigma-clipping operators.
 By default, it is @option{--sigmaclip=3,0.2}, see @ref{Arithmetic operators} 
for more details.
 
-@item -b INT
-@itemx --binning=INT
-Binning the radial profile by averaging group of pixels.
-By default, it is @option{--binning=1}, which means that no binning of the 
data will be done.
-For example, by setting @option{--rmax=100} and @option{--binning=4}, the 
output radial profile will be averaged over group of 4 pixels, so it will have 
a total number 25 points.
-This option is useful when it is necessary to increase the signal to noise 
ratio of the radial profile.
-
-@item -a STR
-@itemx --cprofiles=STR
-Configuration file for @command{astmkprof}.
-As this script uses @command{astmkprof} internally for generating the 
profiles, it may be necessary to use a configuration file for this program.
-
-@item -c STR
-@itemx --ccatalog=STR
-Configuration file for @command{astmkcatalog}.
-As this script uses @command{astmkcatalog} internally for measuring over the 
profiles, it may be necessary to use a configuration file for this program.
-
-@item -X STR
-@itemx --xarith=STR
-Operation to be done with the first column of the radial profile (radius).
-By default, the first column of the radial profile is the distance from the 
center (in pixels).
-But it is possible to operate this column with the same column arithmetic as 
described in @ref{Column arithmetic}.
-For example, if the each pixel is 0.35 arcsec, it is possible to obtain the 
first column in units of arcsec with  @option{--xarith="0.35 x"}.
-
-@item -Y STR
-@itemx --yarith=STR
-Same option than @option{--xarith} but for the second column of the radial 
profile (measured values).
-See above for details.
-For example, if the measured values are in units of mJy (mili-Jansky) but it 
is wanted to have it in Jy and then compute the base-10 logarithm, it is 
possible to do it with @option{--yarith="1000 / log10"}.
-
-@item -i STR
-@itemx --iname=STR
-Name of the first column of the radial profile.
-By default it is @option{--iname=radius}.
-For example, @option{--iname=DISTANCE} will set the name of the first column 
to DISTANCE.
-
-@item -j STR
-@itemx --jname=STR
-Name of the second column of the radial profile.
-By default, the name of the second column will be the operator used for making 
the measurement with the leter "v" at the beginning: (@option{--jname=vmedian}).
-For example, measuring the mean values with @option{--measure=mean} will set 
the output column name to "vmean" while using if using @option{--measure=std} 
will set the output column to "vstd".
-In order to thange the name to any other one, for example FLUX, use 
@option{--jname=FLUX}.
+@item -t
+@itemx --tmpdir=STR
+Several intermediate files are necessary to obtain the radial profile.
+All of these temporal files are saved into a temporal directory.
+With the option @option{--tmpdir} the user can specify this directory.
+Once the radial profile has been obtained, this directory is removed if the 
option @option{--keeptmp} is not used (see below for more details).
 
 @item -k
-@itemx --keeptemp
-Several intermediate files are generated for obtaining the radial profile.
-But, by default they are all removed.
-With the option @option{--keeptemp} (no argument is required) all of these 
files will not be removed.
+@itemx --keeptmp
+With the option @option{--keeptmp} (no argument is required) all temporal 
files generated into the temporal directory @option{--keeptmp} will not be 
removed.
 This option is useful for debugging.
 For example, to check that the profiles generated for obtaining the radial 
profile have the same shape and orientation than the source.
 
+@end table