[gnuastro-commits] master ff3bb03f 38/69: PSF select-stars: removing not used options and polishing the comments

[Mohammad Akhlaghi]

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

    PSF select-stars: removing not used options and polishing the comments
    
    Until this commit, there were some options that the script was not using.
    For example the '--show' option. With this commit, this option and other
    parts of the script that were not used have been removed. In addition to
    this, several parts like the comments and descriptions have been changed to
    be more clear and precise.
---
 bin/script/psf-create-select-stars.in | 216 ++++++++++++++++------------------
 1 file changed, 99 insertions(+), 117 deletions(-)

diff --git a/bin/script/psf-create-select-stars.in 
b/bin/script/psf-create-select-stars.in
index abf4c72f..da7497be 100644
--- a/bin/script/psf-create-select-stars.in
+++ b/bin/script/psf-create-select-stars.in
@@ -1,12 +1,12 @@
 #!/bin/sh
 
-# Build a catalogue, with column names "columns", of reference stars from
-# an astquery "dataset", with a $magnitud value between "min" and "max"
-# which satisfies a "criteria" specified as awk code. Additionaly, if a
-# segmented file is provided, only stars corresponding to clumps with
-# AXIS_RATIO > "minaxisrario" are selected. All the accepted stars
-# shouldn't have brilliant stars within a circle of radius
-# "mindistaarcsec".
+# Build a catalogue of "good stars" that will be considered for
+# constructing an extended and non parametric PSF. Here, "good stars" means
+# that they don't have close objects that affect it sourrondings and
+# consequently they are not contaminated.  The script will construct a
+# catalog of stars from reference datasets (Gaia) if the user does not
+# provide another one. In addition to this, other parameters like the axis
+# ratio are considered to filter the sample and select only proper stars.
 #
 # Run with '--help' for more information.
 #
@@ -48,8 +48,8 @@ quiet=""
 output=""
 tmpdir=""
 catalog=""
-segmented=""
 keeptmp=""
+segmented=""
 minaxisratio=0.9
 version=@VERSION@
 mindistdeg=0.015277778
@@ -78,12 +78,13 @@ print_help() {
    cat <<EOF
 Usage: $scriptname [OPTIONS] image.fits
 
-This script builds a catalogue, with column names "columns", of reference
-stars from an astquery "dataset", with a "field" magnitude value between "min"
-and "max" specified as a chunk of awk code.
-Additionaly, if a segmented file is provided, only stars which match clumps
-within a given "matchaperturedeg", in pixels, and with an AXIS_RATIO >
-"minaxisrario" are selected.
+Build a catalogue of "good stars" that will be considered for constructing
+an extended and non parametric PSF. Here, "good stars" means that they
+don't have close objects that affect it sourrondings and consequently they
+are not contaminated.  The script will construct a catalog of stars from
+reference datasets (Gaia) if the user does not provide another one. In
+addition to this, other parameters like the axis ratio are considered to
+filter the sample and select only proper stars.
 
 $scriptname options:
  Input:
@@ -94,27 +95,24 @@ $scriptname options:
                           ("phot_rp_mean_mag", etc.).
   -m, --min=FLT           Minimum value of field.
   -M, --max=FLT           Maximum value of field.
-  -a, --matchaperturedeg=FLT Aperture, in pixels, to match catalogue ra and
-                          dec coordinates with clumps' ra and dec.
   -Q, --minaxisratio=FLT  Minimum axis ratio of a clump to be accepted.
                           Default to 0.9.
-  -D, --mindistdeg=FLT    Minimum distance to more brilliant neighbour stars
+  -D, --mindistdeg=FLT    Minimum distance to more bright neighbour stars.
                           to be accepted, in degree.
   -c, --catalog=STR       Catalog of stras contain of ra, desc, magnitude,
                           parrallax and parrallax_error.
-
+  -a, --matchaperturedeg=FLT Aperture, in pixels, to match catalogue ra and
+                             dec coordinates with clumps' ra and dec.
  Output:
-  -k, --keeptmp         Keep the build directory.
-  -t, --tmpdir            Build directory (for intermediate files).
-  -o, --output            Catalogue file.
+  -o, --output            Output table with the object coordinates.
+  -t, --tmpdir            Directory to keep temporary files.
+  -k, --keeptmp           Keep temporal/auxiliar files.
 
  Operating mode:
   -h, --help              Print this help.
       --cite              BibTeX citation for this program.
   -q, --quiet             Don't print any commnent.
   -V, --version           Print program version.
-  -s, --show              Show all the selected stars on top of the image using
-                          ds9.
 
 Mandatory or optional arguments to long options are also mandatory or optional
 for any corresponfing short options.
@@ -252,7 +250,6 @@ do
        -V*|--version=*)        on_off_option_error --version -V;;
        --cite)                 astfits --cite; exit 0;;
        --cite=*)               on_off_option_error --cite;;
-       -s|--show)              show=1; shift;;
 
    # Unrecognized option:
        -*) echo "$scriptname: unknown option '$1'"; exit 1;;
@@ -277,15 +274,6 @@ if [ x"$inputs" = x ]; then
        exit 1
 fi
 
-# Check that if 'matchaperturedeg' is not specified as input,
-# Set its value to'3.0/3600'
-arcsec_per_pixel=$(astfits $inputs--hdu=$hdu --pixelscale -q \
-                      | awk '{print $1*3600}')
-if [ x"$matchaperturedeg" = x ]; then
-   matchaperturedeg=$(echo $matchaperturedeg $arcsec_per_pixel \
-                           | awk '{print $1*$2/3600}')
-fi
-
 # Check that 'segmented' is output of 'astsegment'.
 if [ x"$segmented" != x ]; then
     nhdu=$(astfits $segmented --listimagehdus \
@@ -304,8 +292,6 @@ fi
 
 
 
-
-
 # Define a temporal directory and thefinal output file
 # ----------------------------------------------------
 #
@@ -340,56 +326,45 @@ fi
 
 
 
-# Catalog of stars
-# ----------------
+# Obtain a catalog of stars
+# -------------------------
 #
-# At first check that user have catalog of stars or no. If the user geive a
-# catalog to script at first with help of "--skycoverage" check the
-# catalog's minimum (maximum) ra and dec are smaller (larger) than the
-# image edge. If it is true with "asttable" just choose stars that have
-# magnitude between 0 to maximum of magitude. If it isn't stop script. If
-# user don't provide catalog with help of "--astquery" download the
-# catalog.
+# Here, a catalogue of stars is constructed. If the user provides the
+# catalog, then check that the objects overlap with the input image and
+# filter the objects to have only the ones with proper brightness. If the
+# user does not provide a catalogue, obtain it using the program
+# 'astquery'.
 if [ x"$catalog" != x ]; then
-    # Find minimum value of image's ra.
+
+    # Find minimum and maximum RA/Dec values of the input image.
     minraimg=$(astfits $inputs --hdu=$hdu --skycoverage \
                | grep 'RA' | awk '{print $2}')
-
-    # Find minimum value of image's dec.
-    mindecimg=$(astfits $inputs --hdu=$hdu --skycoverage \
-                | grep 'DEC' | awk '{print $2}')
-
-    # Find maximum value of image's ra.
     maxraimg=$(astfits $inputs --hdu=$hdu --skycoverage \
                | grep 'RA' | awk '{print $3}')
 
-    # Find maximum value of image's dec.
+    mindecimg=$(astfits $inputs --hdu=$hdu --skycoverage \
+                | grep 'DEC' | awk '{print $2}')
     maxdecimg=$(astfits $inputs --hdu=$hdu --skycoverage \
                 | grep 'DEC' | awk '{print $3}')
 
-    # Find minimum value of catalog's ra.
+    # Find minimum and maximum RA/Dec values of the input catalog.
     minracatalog=$(asttable $catalog -cRA \
                    | aststatistics --minimum)
-
-    # Find minimum value of catalog's dec.
-    mindeccatalog=$(asttable $catalog -cDEC \
-                    | aststatistics --minimum)
-
-    # Find maximum value of catalog's ra.
     maxracatalog=$(asttable $catalog -cRA \
                    | aststatistics --maximum)
 
-    # Find maximum value of catalog's dec.
+    mindeccatalog=$(asttable $catalog -cDEC \
+                    | aststatistics --minimum)
     maxdeccatalog=$(asttable $catalog -cDEC \
                     | aststatistics --maximum)
 
-    # Check that catalog overlap the image or not.
+    # Check if the catalog overlap the image or not.
     check=$(echo $minraimg $minracatalog $mindecimg $mindeccatalog \
                  $maxraimg $maxracatalog $maxdecimg $maxdeccatalog \
-                | awk '{print ($1 >= $2 && $3 >= $4 && $5 <= $6 && $7 <= $8)}')
+                 | awk '{print ($1 >= $2 && $3 >= $4 && $5 <= $6 && $7 <= 
$8)}')
 
-    # If catalog overlap the image, just select stars with magnitude
-    # between 0 to maximmum range that user choose.
+    # If catalog overlap the image, select stars with magnitudes between
+    # the minimum and maximum values.
     if [ "$check" = 1 ]; then
 
         # Make a file for output of 'asttable'.
@@ -397,11 +372,11 @@ if [ x"$catalog" != x ]; then
         if [ -f $query ]; then
             echo "External Cataloge already exists "
         else
-            # Select stars with magnitude between 0 to maximum.
-            asttable $catalog --range=$field,0:$max --sort=$field \
+            # Select stars with magnitude between minimum to maximum.
+            asttable $catalog --range=$field,$min:$max --sort=$field \
                      --range=ra,$minraimg:$maxraimg \
                      --range=dec,$mindecimg:$maxdecimg \
-                     --output=$query
+                     --output=$query $quiet
 
             numstars=$(asttable $query -i | grep 'Number of rows' | awk 
'{print $4}')
             if [ "$numstars" = 0 ]; then
@@ -411,55 +386,55 @@ if [ x"$catalog" != x ]; then
             fi
         fi
     else
-        # If catalog doesn't overlap the image stop.
-        echo "Tha catalog is smaller than the image and don't overlap image."
+        # Stop if the catalog doesn't overlap with the image.
+        echo "The catalog is smaller than the image and doesn't overlap with 
the image."
         exit 1
     fi
-# If user doesn't provide catalog, with use of 'astquery' catalog of stars
-# with magnitude between 0 to max from gaia has been downloaded.
+
+# If the user doesn't provide a catalog, use 'astquery' to obtain it.
 else
-    # Make a 'query.fits' for output of 'astquery'.
+    # Check if the catalog already exist.
     query=$tmpdir/query.fits
     if [ -f $query ]; then
         echo "External Cataloge already exists "
     else
-        # Download catalog of stars with magnitude between 0 to max from
-        # Gaia with '--astquery'.
-        astquery $dataset --output=$query --overlapwith=$inputs \
-                --hdu=$hdu --column=ra,dec,$field,parallax,parallax_error \
-                --range=$field,0:$max --sort=$field $quiet
+       # Download the catalog with the necessary parameters.
+        astquery $dataset --output=$query --overlapwith=$inputs --hdu=$hdu \
+                 --column=ra,dec,$field,parallax,parallax_error \
+                --range=$field,$min:$max --sort=$field $quiet
     fi
 fi
 
 
 
 
-# Select stars with good parallax.
-#---------------------------------
+
+# Select stars with good parallax
+# -------------------------------
 #
-# With some options of 'asttable' such as '--noblank'
-# remove all stras have parallax larger than three
-# times of parallax-error.
+# Only stars with small parallaxes are allowed. Here, stars with high value
+# of parallax are removed. More in particular, with some options of
+# 'asttable' such as '--noblank', stars that have parallax larger than
+# three times the parallax-error are removed.
 goodparallax=$tmpdir/parallax-good.fits
 asttable $query -cra,dec -c$field \
          --range=$field,$min:$max --colinfoinstdout --noblank=4 \
         -c'arith parallax parallax abs \
                   parallax_error 3 x lt nan where ' \
-        | asttable -cra,dec -c$field --output=$goodparallax
+        | asttable -cra,dec -c$field --output=$goodparallax $quiet
 
 
 
 
 
-# Find circular objects.
-#-----------------------
+# Find circular objects
+# ---------------------
 #
-# Considering only objects with an axis ratio above 1.
-# To do that, first of all a catalogue of clumps is
-# computed using 'astmkcatalog'. In second step, match
-# catalogue of stars from Gaia data sets with clump
-# catalogue. Finally apply the mimimumm axis atio
-# criteria.
+# Consider only objects with an axis ratio above 'minaxisrario'
+# (minaxisratio=1 <--> circular shape).  To do that, a catalogue is
+# computed using 'astmkcatalog' using as input the segmented image. Then,
+# that catalogue is matched with the Gaia catalog and filtered by the
+# 'minaxisratio' criteria.
 circular=$tmpdir/circular-objects.fits
 if [ -f $circular ]; then
     echo "Catalog of circular objects already exists "
@@ -471,10 +446,10 @@ else
        qraw=$tmpdir/axisratio-raw.fits
        qmatch=$tmpdir/axisratio-match.fits
 
-       # Measure axisratios
+       # Measure axis ratios
        astmkcatalog $segmented --ids --ra --dec --axisratio \
                      --positionangle --fwhm --clumpscat \
-                     $quiet --output=$qraw
+                     --output=$qraw $quiet
 
        # Match with downloaded cataloge
        astmatch $goodparallax --ccol1=ra,dec \
@@ -493,36 +468,41 @@ fi
 
 
 
-# Determine the number of neighbors around each object.
-#------------------------------------------------------
+# Determine the number of neighbors around each object
+# -----------------------------------------------------
 #
-# First of all based on ra and dec of circular stars determine
-# the distance between the circular star and brigther stars in
-# minimumm distance and based on '--noblank' and 'where' remove
-# stars tha have distance larger than minimumm distance. Then
-# remove each circular stars that have more than 9 neighbors.
+# To have a good catalogue of stars to construct a PSF, it is necessary
+# that they are not contaminated by bright near objects. Here, those
+# objects that are contaminated by the presence of a nearby object are
+# rejected.
+
+# First of all based on ra and dec of circular stars determine the distance
+# between the circular star and brigther stars in minimumm distance and
+# based on '--noblank' and 'where' remove stars tha have distance larger
+# than minimumm distance. Then remove each circular stars that have more
+# than 9 neighbors.
 lessneighbor=$tmpdir/less-than-9-stars.txt
 moreneighbor=$tmpdir/more-than-9-stars.txt
 echo "# Column 1: ra [deg,f64] Right ascension" >> $lessneighbor
 echo "# Column 2: dec [deg,f64] Declination" >> $lessneighbor
 echo "# Column 3: photo-g-mean-mag [mag,f64] Magnitude" >> $lessneighbor
 
-# Find ra and dec of each circul star.
+# Find ra and dec of each star.
 asttable $circular -cra,dec -c$field | while read r d mag; do
 
    # Make a file for number of neighbourhood.
-   numberneighbor=$tmpdir/"$r"th-star-neighbor.fits
+   numberneighbor=$tmpdir/"$r_$d"th-star-neighbor.fits
 
    # Find number of neighborhod for each star.
    asttable $query -cra,dec -c$field \
-           --colinfoinstdout \
            -c'arith ra dec '$r' '$d' distance-on-sphere \
                      set-i i i '$mindistdeg' gt nan where' \
             --noblank=4 \
-            --output=$numberneighbor
+           --colinfoinstdout \
+            --output=$numberneighbor $quiet
 
-   # Check number of neighborhod and remove each star that
-   # has more than 9 neighbors.
+   # Check number of neighborhod and remove each star that has more than 9
+   # neighbors.
    lof=$(cat $numberneighbor | wc -l)
    if [ $lof -le 9 ]; then
        echo $r $d $mag >> $lessneighbor
@@ -535,20 +515,22 @@ done
 
 
 
-# Output of selected circular stars with good parallax and
-# less than 9 neighbors in fits format.
+# Create the final output catalogue
+# ---------------------------------
+#
+# Output of selected circular stars with good parallax and less than 9
+# neighbors in fits format.
 asttable $lessneighbor --output=$output
 
 
 
 
 
-# Run script quiet or not
-#------------------------
+# Print the statistics of the generated catalogue
+# -----------------------------------------------
 #
-# If user do not want to see all steps of run,
-# the 'quiet' option must be used. Without this
-# option user can see all steps of run.
+# If the user do not want to see all steps of run, the 'quiet' option must
+# be used. Without this option user can see all steps of run.
 if [ x"$quiet" = x ]; then
    echo "Number of downloaded stars from gaia: \
          $(asttable $query | wc -l)"
@@ -565,12 +547,12 @@ fi
 
 
 
+
 # Remove temporary directory
-#---------------------------
+# --------------------------
 #
-# If user dos not specify to keep build file
-# with the option of --keeptmp', then the
-# directory will be removed.
+# If user dos not specify to keep build file with the option of --keeptmp',
+# then the directory will be removed.
 if [ x"$keeptmp" = x ]; then
    rm -rf $tmpdir
 fi