[gnuastro-commits] master c9647b5 31/32: Imported work on the radial profile script, minor conflict fixed

[Mohammad Akhlaghi]

branch: master
commit c9647b5279dd9608a15fcd621d2180924d9f1217
Merge: ea59208 362819c
Author: Mohammad Akhlaghi <mohammad@akhlaghi.org>
Commit: Mohammad Akhlaghi <mohammad@akhlaghi.org>

    Imported work on the radial profile script, minor conflict fixed
    
    A minor conflict appeared in the book that has been fixed. Some further
    small changes that have been implemented:
    
     - The rule to build and install the radial profile script and its man-page
       have been added. During this, I also noticed that we hadn't added the
       rule to build/install the man page for the 'astscript-make-ds9-reg'
       script! So that was also added.
    
     - The copyright notice was corrected (removing the years from the
       authors). This is because the copyright holder of Gnuastro's files is
       held by the FSF, not by individual authors.
    
     - One line of the output of '--help' was shortened to fit within 80
       characters.
---
 .gitignore                   |   1 +
 bin/script/Makefile.am       |  19 +-
 bin/script/radial-profile.in | 443 +++++++++++++++++++++++++++++++++++++++++++
 doc/Makefile.am              |  26 ++-
 doc/gnuastro.texi            | 183 +++++++++++++++++-
 5 files changed, 660 insertions(+), 12 deletions(-)

diff --git a/.gitignore b/.gitignore
index 26b30b4..c9bc5d4 100644
--- a/.gitignore
+++ b/.gitignore
@@ -44,6 +44,7 @@
 *.log
 *.pdf
 *.png
+*.swp
 *.toc
 *.trs
 *.txt
diff --git a/bin/script/Makefile.am b/bin/script/Makefile.am
index 3bbedcf..1e17699 100644
--- a/bin/script/Makefile.am
+++ b/bin/script/Makefile.am
@@ -27,9 +27,12 @@
 ## with the tarball ('EXTRA_DIST') and output files (to be cleaned with
 ## 'make clean').
 bin_SCRIPTS = astscript-make-ds9-reg \
+              astscript-radial-profile \
               astscript-sort-by-night
 
-EXTRA_DIST = make-ds9-reg.in sort-by-night.in
+EXTRA_DIST = make-ds9-reg.in \
+             radial-profile.in \
+             sort-by-night.in
 
 CLEANFILES = $(bin_SCRIPTS)
 
@@ -45,11 +48,15 @@ do_subst = sed -e 's,[@]VERSION[@],$(VERSION),g' \
 
 
 
-## Rules to build the scripts
-astscript-sort-by-night: sort-by-night.in Makefile
-       $(do_subst) < $(srcdir)/sort-by-night.in > $@
-       chmod +x $@
-
+## Rules to install the scripts.
 astscript-make-ds9-reg: make-ds9-reg.in Makefile
        $(do_subst) < $(srcdir)/make-ds9-reg.in > $@
        chmod +x $@
+
+astscript-radial-profile: radial-profile.in Makefile
+       $(do_subst) < $(srcdir)/radial-profile.in > $@
+       chmod +x $@
+
+astscript-sort-by-night: sort-by-night.in Makefile
+       $(do_subst) < $(srcdir)/sort-by-night.in > $@
+       chmod +x $@
diff --git a/bin/script/radial-profile.in b/bin/script/radial-profile.in
new file mode 100644
index 0000000..5191506
--- /dev/null
+++ b/bin/script/radial-profile.in
@@ -0,0 +1,443 @@
+#!/bin/sh
+
+# Obtain averaged radial profiles, run with `--help', or see description
+# under `print_help' (below) for more.
+#
+# Original author:
+#   Raul Infante-Sainz <infantesainz@gmail.com>
+# Contributing author(s):
+#   Mohammad Akhlaghi <mohammad@akhlaghi.org>
+#   Zahra Sharbaf <zahra.sharbaf2@gmail.com>
+#   Carlos Morales-Socorro <cmorsoc@gmail.com>
+# Copyright (C) 2020-2021, Free Software Foundation, Inc.
+#
+# Gnuastro is free software: you can redistribute it and/or modify it under
+# the terms of the GNU General Public License as published by the Free
+# Software Foundation, either version 3 of the License, or (at your option)
+# any later version.
+#
+# Gnuastro is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
+# more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with Gnuastro. If not, see <http://www.gnu.org/licenses/>.
+
+
+# Exit the script in the case of failure
+set -e
+
+
+
+
+
+# Default option values (can be changed with options on the command-line).
+hdu=1
+quiet=0
+qratio=1
+pangle=0
+tmpdir=""
+keeptmp=0
+rmax="max"
+mode="img"
+xcenter="center"
+ycenter="center"
+measure="--mean"
+sigmaclip="3,0.2"
+output="default"
+version=@VERSION@
+scriptname=@SCRIPT_NAME@
+
+
+
+
+
+# Output of `--usage' and `--help':
+print_usage() {
+    cat <<EOF
+$scriptname: run with '--help' for list of options
+EOF
+}
+
+print_help() {
+    cat <<EOF
+Usage: $scriptname [OPTION] FITS-files
+
+This script is part of GNU Astronomy Utilities $version.
+
+This script will consider the input image for constructing the radial
+profile around a given center with elliptical apertures.
+
+For more information, please run any of the following commands. In
+particular the first contains a very comprehensive explanation of this
+script's invocation: expected input(s), output(s), and a full description
+of all the options.
+
+     Inputs/Outputs and options:           $ info $scriptname
+     Full Gnuastro manual/book:            $ info gnuastro
+
+If you couldn't find your answer in the manual, you can get direct help from
+experienced Gnuastro users and developers. For more information, please run:
+
+     $ info help-gnuastro
+
+$scriptname options:
+ Input:
+  -h, --hdu=STR           HDU/extension of all input FITS files.
+  -O, --mode=STR          Coordinate mode: img or wcs.
+  -x, --xcenter=FLT       Coordinate of the center along the first axis.
+  -y, --ycenter=FLT       Coordinate of the center along the second axis.
+  -R, --rmax=FLT          Maximum radius for the radial profile (in pixels).
+  -Q, --qratio=FLT        Axis ratio for ellipse profiles (A/B).
+  -p, --pangle=FLT        Position angle for ellipse profiles.
+  -m, --measure="STR"     Measurement operator ("--mean", "--median", etc.).
+  -s, --sigmaclip=FLT,FLT Parameters for sigma clipping measure operators.
+
+ Output:
+  -k, --keeptmp           Keep temporal/auxiliar files.
+  -o, --output            Output table with the radial profile.
+
+ Operating mode:
+  -h, --help              Print this help list.
+      --cite              BibTeX citation for this program.
+  -q, --quiet             Don't print the list.
+  -V, --version           Print program version.
+
+Mandatory or optional arguments to long options are also mandatory or optional
+for any corresponding short options.
+
+GNU Astronomy Utilities home page: http://www.gnu.org/software/gnuastro/
+
+Report bugs to bug-gnuastro@gnu.org.
+EOF
+}
+
+
+
+
+
+# Output of `--version':
+print_version() {
+    cat <<EOF
+$scriptname (GNU Astronomy Utilities) $version
+Copyright (C) 2020-2021, Free Software Foundation, Inc.
+License GPLv3+: GNU General public license version 3 or later.
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+
+Written/developed by Raul Infante-Sainz
+EOF
+}
+
+
+
+
+
+# Functions to check option values and complain if necessary.
+on_off_option_error() {
+    if [ "x$2" = x ]; then
+        echo "$scriptname: '$1' doesn't take any values."
+    else
+        echo "$scriptname: '$1' (or '$2') doesn't take any values."
+    fi
+    exit 1
+}
+
+check_v() {
+    if [ x"$2" = x ]; then
+        echo "$scriptname: option '$1' requires an argument."
+        echo "Try '$scriptname --help' for more information."
+        exit 1;
+    fi
+}
+
+
+
+
+
+# Separate command-line arguments from options. Then put the option
+# value into the respective variable.
+#
+# OPTIONS WITH A VALUE:
+#
+#   Each option has three lines because we want to all common formats: for
+#   long option names: `--longname value' and `--longname=value'. For short
+#   option names we want `-l value', `-l=value' and `-lvalue' (where `-l'
+#   is the short version of the hypothetical `--longname' option).
+#
+#   The first case (with a space between the name and value) is two
+#   command-line arguments. So, we'll need to shift it two times. The
+#   latter two cases are a single command-line argument, so we just need to
+#   "shift" the counter by one. IMPORTANT NOTE: the ORDER OF THE LATTER TWO
+#   cases matters: `-h*' should be checked only when we are sure that its
+#   not `-h=*').
+#
+# OPTIONS WITH NO VALUE (ON-OFF OPTIONS)
+#
+#   For these, we just want the two forms of `--longname' or `-l'. Nothing
+#   else. So if an equal sign is given we should definitely crash and also,
+#   if a value is appended to the short format it should crash. So in the
+#   second test for these (`-l*') will account for both the case where we
+#   have an equal sign and where we don't.
+while [ $# -gt 0 ]
+do
+    case "$1" in
+        # Input parameters.
+        -h|--hdu)           hdu="$2";                                  check_v 
"$1" "$hdu";  shift;shift;;
+        -h=*|--hdu=*)       hdu="${1#*=}";                             check_v 
"$1" "$hdu";  shift;;
+        -h*)                hdu=$(echo "$1"  | sed -e's/-h//');        check_v 
"$1" "$hdu";  shift;;
+        -O|--mode)          mode="$2";                                 check_v 
"$1" "$mode";  shift;shift;;
+        -O=*|--mode=*)      mode="${1#*=}";                            check_v 
"$1" "$mode";  shift;;
+        -O*)                mode=$(echo "$1"  | sed -e's/-O//');       check_v 
"$1" "$mode";  shift;;
+        -x|--xcenter)       xcenter="$2";                              check_v 
"$1" "$xcenter";  shift;shift;;
+        -x=*|--xcenter=*)   xcenter="${1#*=}";                         check_v 
"$1" "$xcenter";  shift;;
+        -x*)                xcenter=$(echo "$1"  | sed -e's/-x//');    check_v 
"$1" "$xcenter";  shift;;
+        -y|--ycenter)       ycenter="$2";                              check_v 
"$1" "$ycenter";  shift;shift;;
+        -y=*|--ycenter=*)   ycenter="${1#*=}";                         check_v 
"$1" "$ycenter";  shift;;
+        -y*)                ycenter=$(echo "$1"  | sed -e's/-y//');    check_v 
"$1" "$ycenter";  shift;;
+        -R|--rmax)          rmax="$2";                                 check_v 
"$1" "$rmax";  shift;shift;;
+        -R=*|--rmax=*)      rmax="${1#*=}";                            check_v 
"$1" "$rmax";  shift;;
+        -R*)                rmax=$(echo "$1"  | sed -e's/-R//');       check_v 
"$1" "$rmax";  shift;;
+        -Q|--qratio)        qratio="$2";                               check_v 
"$1" "$qratio";  shift;shift;;
+        -Q=*|--qratio=*)    qratio="${1#*=}";                          check_v 
"$1" "$qratio";  shift;;
+        -Q*)                qratio=$(echo "$1"  | sed -e's/-Q//');     check_v 
"$1" "$qratio";  shift;;
+        -p|--pangle)        pangle="$2";                               check_v 
"$1" "$pangle";  shift;shift;;
+        -p=*|--pangle=*)    pangle="${1#*=}";                          check_v 
"$1" "$pangle";  shift;;
+        -p*)                pangle=$(echo "$1"  | sed -e's/-p//');     check_v 
"$1" "$pangle";  shift;;
+        -m|--measure)       measure="$2";                              check_v 
"$1" "$measure";  shift;shift;;
+        -m=*|--measure=*)   measure="${1#*=}";                         check_v 
"$1" "$measure";  shift;;
+        -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;;
+
+
+        # Output parameters
+        -k|--keeptmp)     keeptmp=1; shift;;
+        -k*|--keeptmp=*)  on_off_option_error --keeptmp -k;;
+        -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;;
+
+        # Non-operating options.
+        -q|--quiet)       quiet=1; shift;;
+        -q*|--quiet=*)    on_off_option_error --quiet -q;;
+        -?|--help)        print_help; exit 0;;
+        -'?'*|--help=*)   on_off_option_error --help -?;;
+        -V|--version)     print_version; exit 0;;
+        -V*|--version=*)  on_off_option_error --version -V;;
+        --cite)           astfits --cite; exit 0;;
+        --cite=*)         on_off_option_error --cite;;
+
+        # Unrecognized option:
+        -*) echo "$scriptname: unknown option '$1'"; exit 1;;
+
+        # Not an option (not starting with a `-'): assumed to be input FITS
+        # file name.
+        *) inputs="$1 $inputs"; shift;;
+    esac
+done
+
+
+
+
+
+# Basic sanity checks on arguments.
+if [ x"$inputs" = x ]; then
+    echo "$scriptname: no input FITS files."
+    echo "Run with '--help' for more information on how to run."
+    exit 1
+fi
+
+
+
+
+# If one of X or Y are given the other also needs to be given.
+if [ "z$xcenter" = zcenter ]; then
+  if ! [ "z$ycenter" = zcenter ]; then
+    echo "Center position's Y axis value is given, but not X!"
+    exit 1
+  fi
+else
+  if [ "z$ycenter" = zcenter ]; then
+    echo "Center position's X axis value is given, but not Y!"
+    exit 1
+  fi
+fi
+
+
+
+
+
+# Convert center to image coordinates if necessary
+# ------------------------------------------------
+#
+# If the user provides specific coordinates in WCS (--mode=wcs), then convert
+# them to image mode so we can safely assume image coordianates from now on. To
+# do that, WCS information from the input header image is used.
+if ! [ "z$xcenter" = zcenter ]; then
+  if [ $mode = wcs ]; then
+    xy=$(echo "$xcenter $ycenter" \
+             | asttable -c'arith $1 $2 wcstoimg' \
+                        --wcsfile=$inputs --wcshdu=$hdu)
+    xcenter=$(echo $xy | awk '{print $1}');
+    ycenter=$(echo $xy | awk '{print $2}');
+  fi
+fi
+
+
+
+
+
+# Set default central position
+# ----------------------------
+#
+# If the user does not set the x and y coordinates to be `center' (the
+# coordinates of the object), then compute the center of the image for
+# constructing the profiles. Here, we are assuming that the object is already
+# centered on the input image.
+#
+# In the FITS standard, pixels are counted from 1, and the integers are in
+# the center of the pixel. So after dividing the pixel size of the image by
+# 2, we should add it with 0.5 to be the `center' of the image.
+if [ "z$xcenter" = zcenter ]; 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}')
+fi
+
+
+
+
+
+# Calculate the maximum radius
+# ----------------------------
+#
+# If the user set the --rmax parameter to `max', then compute the maximum
+# radius possible on the image.
+#
+# If the user has not given any maximum radius, we give the most reliable
+# maximum radius (where the full circumference will be within the
+# image). If the radius goes outside the image, then the measurements and
+# calculations can be biased, so when the user has not provided any maximum
+# radius, we should only confine ourselves to a radius where the results
+# are reliable.
+#
+#             Y--------------
+#              |            |       The maximum radius (to ensure the profile
+#            y |........*   |       lies within the image) is the smallest
+#              |        .   |       one of these values:
+#              |        .   |              x, y, X-x, Y-y
+#              --------------
+#              0        x   X
+#
+if [ "z$rmax" = zmax ]; then
+  rmax=$(astfits $inputs --hdu=$hdu \
+             | awk '/^NAXIS1/{X=$3} /^NAXIS2/{Y=$3} \
+                    END{ x='$xcenter'; y='$ycenter'; \
+                         printf("%s\n%s\n%s\n%s", x, y, X-x, Y-y); }' \
+             | aststatistics --minimum )
+fi
+
+
+
+
+
+# Define the final output file and temporal directory
+# ---------------------------------------------------
+#
+# Here, it is defined the final output file containing the radial profile.
+# If the user has defined a specific path/name for the output, it will be
+# used for saving the output file. If the user does not specify a output name,
+# then a default value containing the center and mode will be generated.
+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. 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; fi
+mkdir -p $tmpdir
+
+
+
+
+
+# Crop image
+# ----------
+#
+# Crop the input image around the desired point so we can continue processing
+# only on those pixels (we do not need the other pixels).
+#
+# The crop's output always has the range of pixels from the original image used
+# in the `ICF1PIX' keyword value. So, to find the new center (important if it
+# is sub-pixel precission), we can simply get the first 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'.
+crop=$tmpdir/crop.fits
+cropwidth=$(echo $rmax | awk '{print $1*2+1}')
+astcrop $inputs --hdu=$hdu --center=$xcenter,$ycenter --mode=img \
+        --width=$cropwidth --output=$crop
+dxy=$(astfits $crop -h1 \
+          | grep ICF1PIX \
+          | sed -e"s/'/ /g" -e's/\:/ /g' -e's/,/ /' \
+          | awk '{print $3-1, $5-1}')
+xcenter=$(echo "$xcenter $cropwidth $dxy" | awk '{if($1>int($2/2)) print 
$1-$3; else print int($2/2)+$1-int($1)}')
+ycenter=$(echo "$ycenter $cropwidth $dxy" | awk '{if($1>int($2/2)) print 
$1-$4; else print int($2/2)+$1-int($1)}')
+
+
+
+
+
+# Generate the apertures image
+# ----------------------------
+#
+# The apertures image is generated using MakeProfiles with the parameters
+# specified in the echo statement:
+
+# rmax    -- maximum radius value (in pixels)
+# xcenter -- X center position (in pixels).
+# ycenter -- Y center position (in pixels).
+# 7       -- type of the profiles (radial distance).
+# 1       -- the Sersic or Moffat index.
+# pangle  -- position angle.
+# qratio  -- axis ratio.
+# rmax    -- magnitude of the profile within the truncation radius (rmax).
+# 1       -- Truncation in radius unit.
+apertures=$tmpdir/apertures.fits
+echo "$rmax $xcenter $ycenter 7 $rmax 1 $pangle $qratio $rmax 1" \
+     | astmkprof --background=$crop --backhdu=1 --mforflatpix \
+                 --mode=img --clearcanvas --type=int16 \
+                 --circumwidth=1 --replace --output=$apertures
+
+
+
+
+
+# Obtain the radial profile
+# -------------------------
+#
+# The radial profile is obtained using Catalog. In practice, what is done is to
+# obtain a catalogue using the segmentation image previously generated (the
+# elliptical apertures) and the original input image for measuring the values.
+astmkcatalog $apertures -h1 --valuesfile=$crop --valueshdu=1 \
+             --ids $measure --sigmaclip=$sigmaclip --output=$output
+
+
+
+
+
+# Remove temporal 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
+fi
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 12dc957..c5dff6a 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -153,6 +153,7 @@ dist_man_MANS = $(MAYBE_ARITHMETIC_MAN) 
$(MAYBE_BUILDPROG_MAN) \
   $(MAYBE_MKCATALOG_MAN) $(MAYBE_MKNOISE_MAN) $(MAYBE_MKPROF_MAN) \
   $(MAYBE_NOISECHISEL_MAN) $(MAYBE_QUERY_MAN) $(MAYBE_SEGMENT_MAN) \
   $(MAYBE_STATISTICS_MAN) $(MAYBE_TABLE_MAN) $(MAYBE_WARP_MAN) \
+  man/astscript-make-ds9-reg.1 man/astscript-radial-profile.1 \
   man/astscript-sort-by-night.1
 
 
@@ -224,11 +225,6 @@ man/astquery.1: $(top_srcdir)/bin/query/args.h  
$(ALLMANSDEP)
        $(MAYBE_HELP2MAN) -n "query remote data servers and download"      \
                          --libtool $(toputildir)/query/astquery
 
-man/astscript-sort-by-night.1: $(top_srcdir)/bin/script/sort-by-night.in   \
-                               $(ALLMANSDEP)
-       $(MAYBE_HELP2MAN) -n "Sort input FITS files by night"              \
-                         --libtool $(toputildir)/script/astscript-sort-by-night
-
 man/astsegment.1: $(top_srcdir)/bin/segment/args.h  $(ALLMANSDEP)
        $(MAYBE_HELP2MAN) -n "segmentation based on signal structure"      \
                          --libtool $(toputildir)/segment/astsegment
@@ -248,3 +244,23 @@ man/asttable.1: $(top_srcdir)/bin/table/args.h  
$(ALLMANSDEP)
 man/astwarp.1: $(top_srcdir)/bin/warp/args.h  $(ALLMANSDEP)
        $(MAYBE_HELP2MAN) -n "warp (transform) input dataset"              \
                          --libtool $(toputildir)/warp/astwarp
+
+
+
+
+
+# The Scripts:
+man/astscript-make-ds9-reg.1: $(top_srcdir)/bin/script/make-ds9-reg.in   \
+                               $(ALLMANSDEP)
+       $(MAYBE_HELP2MAN) -n "Create an SAO DS9 region file from a table" \
+                         --libtool $(toputildir)/script/astscript-make-ds9-reg
+
+man/astscript-radial-profile.1: $(top_srcdir)/bin/script/radial-profile.in   \
+                               $(ALLMANSDEP)
+       $(MAYBE_HELP2MAN) -n "Create a radial profile of an object in an image" 
\
+                         --libtool 
$(toputildir)/script/astscript-radial-profile
+
+man/astscript-sort-by-night.1: $(top_srcdir)/bin/script/sort-by-night.in   \
+                               $(ALLMANSDEP)
+       $(MAYBE_HELP2MAN) -n "Sort input FITS files by night"              \
+                         --libtool $(toputildir)/script/astscript-sort-by-night
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index 0fc804c..548eefa 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -483,6 +483,7 @@ Data analysis
 * Match::                       Match two datasets.
 * Sort FITS files by night::    Sort and classify images in separate nights.
 * SAO DS9 region files from table::  Table's positional columns into DS9 
region file.
+* Generate radial profile::     Generate the radial profile of a target.
 
 Statistics
 
@@ -551,6 +552,10 @@ SAO DS9 region files from table
 
 * Invoking astscript-make-ds9-reg::  How to call astscript-make-ds9-reg
 
+Generate radial profile
+
+* Invoking astscript-radial-profile::  How to call astscript-radial-profile
+
 Modeling and fitting
 
 * MakeProfiles::                Making mock galaxies and stars.
@@ -14121,6 +14126,7 @@ For example getting general or specific statistics of 
the dataset (with @ref{Sta
 * Match::                       Match two datasets.
 * Sort FITS files by night::    Sort and classify images in separate nights.
 * SAO DS9 region files from table::  Table's positional columns into DS9 
region file.
+* Generate radial profile::     Generate the radial profile of a target.
 @end menu
 
 @node Statistics, NoiseChisel, Data analysis, Data analysis
@@ -17779,6 +17785,22 @@ For random measurements on any area, please use the 
upper-limit columns of MakeC
 
 
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 @node Match, Sort FITS files by night, MakeCatalog, Data analysis
 @section Match
 
@@ -18240,7 +18262,7 @@ For example @code{--prefix=/path/to/processing/img-} 
will put all the links/copi
 
 
 
-@node SAO DS9 region files from table,  , Sort FITS files by night, Data 
analysis
+@node SAO DS9 region files from table, Generate radial profile, Sort FITS 
files by night, Data analysis
 @section SAO DS9 region files from table
 
 Once your desired catalog (containing the positions of some objects) is 
created (for example with @ref{MakeCatalog}, @ref{Match}, or @ref{Table}) it 
often happens that you want to see your selected objects on an image for a 
feeling of the spatial properties of your objects.
@@ -18388,6 +18410,165 @@ In the opened window, click on ``Command Line 
Options''.
 
 
 
+@node Generate radial profile,  , SAO DS9 region files from table, Data 
analysis
+@section Generate radial profile
+
+@cindex Radial profile
+@cindex Profile, profile
+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 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 (elliptical apertures are considered), the 
operator for obtaining the values, and some other options.
+
+@menu
+* Invoking astscript-radial-profile::  How to call astscript-radial-profile
+@end menu
+
+@node Invoking astscript-radial-profile,  , Generate radial profile, Generate 
radial profile
+@subsection Invoking astscript-radial-profile
+
+For more on installed scripts please see (see @ref{Installed scripts}).
+This script can be used with the following general template:
+
+@example
+$ astscript-radial-profile [OPTION...] FITS-file
+@end example
+
+@noindent
+Examples:
+
+@example
+## Generate the radial profile with default options
+$ 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     \
+                           --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 and 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.
+## Name the output table as `radial-profile.fits'
+$ astscript-radial-profile image.fits --mode=wcs   \
+                           --xcenter=20.53751695   \
+                           --ycenter=0.9454292263  \
+                           --rmax=88 --qratio=0.32 \
+                           --pangle=148 -oradial-profile.fits
+
+@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 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
+@itemx --hdu=STR
+The HDU/extension to use.
+
+@item -O STR
+@itemx --mode=STR
+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 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 
apertures with @command{astmkprof}.
+
+@item -y FLT
+@itemx --ycenter=FLT
+Center coordinate along the second dimension.
+Same than @option{--xcenter} argument, but for the second dimension (see above 
for details).
+
+@item -R FLT
+@itemx --rmax=FLT
+Maximum radius for the radial profile (in pixels).
+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 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}.
+
+@item -p FLT
+@itemx --pangle=FLT
+The position angle (in degrees) of the profiles relative to the first FITS 
axis (horizontal when viewed in SAO ds9).
+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 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 measuring the 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 -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 --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
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 @node Modeling and fittings, High-level calculations, Data analysis, Top
 @chapter Modeling and fitting