[gnuastro-commits] master 354906d9: astscript-psf-stamp: default tmpdir includes location, not files

[Mohammad Akhlaghi]

branch: master
commit 354906d93b14ec0d273b0178b70c454546ebe5fb
Author: Sepideh Eskandarlou <sepideh.eskandarlou@gmail.com>
Commit: Mohammad Akhlaghi <mohammad@akhlaghi.org>

    astscript-psf-stamp: default tmpdir includes location, not files
    
    Until now, when this installed script was run, it would create a fixed
    temporary directory (independent of the input), and the temporary files
    would get an extra identifier for the input coordinates. This had two
    problems:
    
     - When the user gave a desired temporary directory and wanted to keep it,
       they would still need to track the position of their desired object.
    
     - A new run of this script would put temporary files in the same
       directory; making it confusing and potentially buggy (for the user).
    
     - It is not the way other installed scripts work.
    
    With this commit, the temporary directory now contains the position of the
    desired cut, and the contents of a certain step always have the same
    name.
    
    Also, thanks to the reminder by Raul Infante-Sainz, we noticed that the
    zero point paper was not actually mentioned at all in the book! So this
    commit also includes several citations to that paper in the relevant parts.
---
 bin/script/psf-stamp.sh | 79 ++++++++++++++++++++++---------------------------
 doc/gnuastro.texi       | 14 +++++++--
 2 files changed, 47 insertions(+), 46 deletions(-)

diff --git a/bin/script/psf-stamp.sh b/bin/script/psf-stamp.sh
index f9c96a14..402ac34b 100644
--- a/bin/script/psf-stamp.sh
+++ b/bin/script/psf-stamp.sh
@@ -317,8 +317,6 @@ do
         -p=*|--position-angle=*)   positionangle="${1#*=}";                    
         check_v "$1" "$positionangle";  shift;;
         -p*)                       positionangle=$(echo "$1"  | sed 
-e's/-p//');        check_v "$1" "$positionangle";  shift;;
 
-
-
         # Output parameters
         -k|--keeptmp)     keeptmp=1; shift;;
         -k*|--keeptmp=*)  on_off_option_error --keeptmp -k;;
@@ -510,19 +508,17 @@ fi
 # 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 will be
 # generated.
-objectid="$xcoord"_"$ycoord"
+objectid="$xcoord"-"$ycoord"
 bname_prefix=$(basename "$inputs" | sed 's/\.fits/ /' | awk '{print $1}')
 if [ x"$tmpdir" = x ]; then \
-  tmpdir=$(pwd)/"$bname_prefix"_stamp
+  tmpdir=$(pwd)/"$bname_prefix"-stamp-$objectid
 fi
 
-if [ -d "$tmpdir" ]; then
-  junk=1
-else
-  mkdir -p "$tmpdir"
-fi
+# Existance of the temporary directory (delete it if already exists).
+if [ -d "$tmpdir" ]; then  rm -r "$tmpdir"; fi
+mkdir "$tmpdir"
 
-# Output
+# Output.
 if [ x"$output" = x ]; then
   output="$bname_prefix"_stamp_$objectid.fits
 fi
@@ -565,7 +561,7 @@ fi
 # We are setting '--checkcenter=0' in Crop so it doesn't check if the
 # central pixel is covered or not (we may be interested in the outer parts
 # of the PSF of a star that is centered outside of the image).
-cropped=$tmpdir/cropped-$objectid.fits
+cropped=$tmpdir/cropped.fits
 astcrop $inputs --hdu=$hdu --mode=img --checkcenter=0 \
         --width=$xwidthinpix,$ywidthinpix \
         --center=$xcenter,$ycenter \
@@ -632,13 +628,13 @@ EOF
 
     else
         # To help in debugging (when '--quiet' is not called)
-        if [ x"$quiet" = x ]; then
+        if [ x"$quiet" = x ] && [ x"$center" != x ]; then
             echo "$scriptname: $segment: at $center, found clump $clab in 
object $olab"
         fi
 
         # Crop the object and clump image to same size as desired stamp.
-        cropclp=$tmpdir/cropped-clumps-$objectid.fits
-        cropobj=$tmpdir/cropped-objects-$objectid.fits
+        cropclp=$tmpdir/cropped-clumps.fits
+        cropobj=$tmpdir/cropped-objects.fits
         astcrop $segment --hdu=OBJECTS --mode=img \
                 --center=$xcenter,$ycenter \
                 --width=$xwidthinpix,$ywidthinpix --output=$cropobj $quiet
@@ -647,7 +643,7 @@ EOF
                 --width=$xwidthinpix,$ywidthinpix --output=$cropclp $quiet
 
         # Mask all the undesired regions.
-        cropped_masked=$tmpdir/cropped-masked-$objectid.fits
+        cropped_masked=$tmpdir/cropped-masked.fits
         astarithmetic $cropped --hdu=1 set-i --output=$cropped_masked $quiet \
                       $cropobj --hdu=1 set-o \
                       $cropclp --hdu=1 set-c \
@@ -656,7 +652,6 @@ EOF
                       1 dilate set-cmask \
                       o o $olab eq 0 where set-omask \
                       i omask cmask or nan where
-
     fi
 
     # Apply the signal-to-noise threshold if the user provided one, and
@@ -666,49 +661,47 @@ EOF
         # Mask all the pixels that are below the threshold based on the
         # signal to noise value which is obtained form the SKY_STD. Finally
         # label the separate regions.
-       cropsnt=$tmpdir/cropped-snt-$objectid.fits
-       cropstd=$tmpdir/cropped-std-$objectid.fits
-        croplab=$tmpdir/cropped-lab-$objectid.fits
-       astcrop $segment --hdu=SKY_STD --mode=img \
+        cropsnt=$tmpdir/cropped-snt.fits
+        cropstd=$tmpdir/cropped-std.fits
+        croplab=$tmpdir/cropped-lab.fits
+        astcrop $segment --hdu=SKY_STD --mode=img \
                 --center=$xcenter,$ycenter \
                 --width=$xwidthinpix,$ywidthinpix \
-               --output=$cropstd $quiet
+                --output=$cropstd $quiet
 
         # Fill the NAN pixels with maximum value of the image plus one (so
         # the fill value is not present in the image).
         fillval=$(astarithmetic $cropped_masked maxvalue 1 + -q)
-        fill=$tmpdir/cropped-masked-fill-nan-pix-$objectid.fits
+        fill=$tmpdir/cropped-masked-fill-nan-pix.fits
         astarithmetic $cropped_masked set-i i i isblank $fillval \
                       where --output=$fill
 
         # Apply the threshold and label the regions above the threshold.
         astarithmetic $fill -h1 set-v \
-                     $cropstd -h1        set-s \
-                     v s /               set-sn \
-                     v sn $snthresh lt \
-                     2 dilate nan where set-all \
+                      $cropstd -h1        set-s \
+                      v s /               set-sn \
+                      v sn $snthresh lt \
+                      2 dilate nan where set-all \
                       all tofilefree-$cropsnt \
                       all isnotblank 2 connected-components \
                       --output=$croplab
 
         # Extract the label of the central coordinate.
-        id=$(astcrop $croplab -h1 --mode=wcs \
+        id=$(astcrop $croplab -h1 --mode=$mode \
                      --center=$xcoord,$ycoord \
                      --widthinpix --width=1 --oneelemstdout -q)
 
-        # Mask all the pixels that do not belong to the main object.
-        msk=$tmpdir/mask-$objectid.fits
-        astarithmetic $cropsnt $croplab $id ne nan where -g1 \
-                      --output=$msk.fits
-
-        # Set all the originally NaN-valued pixels to NaN again.
-        astarithmetic $msk.fits set-i i i $fillval eq nan where \
-                      --output=$msk
+        # Mask all the pixels that do not belong to the main object and set
+        # all the originally NaN-valued pixels to NaN again.
+        msk=$tmpdir/mask.fits
+        astarithmetic $cropsnt $croplab $id ne nan where set-i \
+                      i i $fillval eq nan where -g1 --output=$msk
 
-        # Clean up.
-       mv $msk $cropped_masked
+        # Set the masked image to the desired output of this step.
+        mv $msk $cropped_masked
     fi
 
+# No '--segment' provided.
 else
     cropped_masked=$cropped
 fi
@@ -810,13 +803,13 @@ if [ $nocentering = 0 ]; then
 
     # Warp image based on the measured displacement (first component of the
     # output above).
-    warpped=$tmpdir/cropped-masked-warpforcenter-$objectid.fits
+    warpped=$tmpdir/cropped-masked-warpforcenter.fits
     DXY=$(echo "$warpcoord" | awk '{print $1}')
     astwarp $cropped_masked --translate=$DXY --output=$warpped
 
     # Crop image based on the calculated shift (second component of the
     # output above).
-    centermsk=$tmpdir/cropped-masked-centered-$objectid.fits
+    centermsk=$tmpdir/cropped-masked-centered.fits
     CXY=$(echo "$warpcoord" | awk '{print $2}')
     astcrop $warpped -h1 \
             --mode=img --output=$centermsk \
@@ -844,7 +837,7 @@ if [ x"$normradiusmin" != x   -a   x"$normradiusmax" != x 
]; then
     # Otherwise, compute the radial profile up to the outer part of the
     # ring for the normalization (to not wast CPU time). If the user
     # specifies sigma clip parameters, use them.
-    radialprofile=$tmpdir/rprofile-$objectid.fits
+    radialprofile=$tmpdir/rprofile.fits
     maxr=$(echo "$normradiusmax" | awk '{print $1+1}')
     if [ x"$sigmaclip" = x ]; then finalsigmaclip=""
     else                           finalsigmaclip="--sigmaclip=$sigmaclip";
@@ -867,9 +860,9 @@ if [ x"$normradiusmin" != x   -a   x"$normradiusmax" != x 
]; then
     values=$(asttable $radialprofile $quiet \
                       --range=1,$normradiusmin,$normradiusmax)
     if ! normvalue=$(echo "$values" \
-                          | aststatistics --column=2 --$normop \
-                                          $finalsigmaclip -q \
-                          2> /dev/null); then
+                         | aststatistics --column=2 --$normop \
+                                         $finalsigmaclip -q \
+                                         2> /dev/null); then
         normvalue=nan
     fi
 else
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index 03fb0dcd..42bcedbc 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -1174,7 +1174,8 @@ They can be run just like a program and behave very 
similarly (with minor differ
 
 @item astscript-pointing-simulate
 (See @ref{Pointing pattern simulation}) Given a table of pointings on the sky, 
create and a reference image that contains your camera's distortions and 
properties, generate a stacked exposure map.
-This is very useful in testing the coverage of dither patterns when designing 
your observing strategy and it is highly customizable, see the tutorial in 
@ref{Pointing pattern design}.
+This is very useful in testing the coverage of dither patterns when designing 
your observing strategy and it is highly customizable.
+See Akhlaghi @url{https://arxiv.org/abs/2310.15006,2023}, or the dedicated 
tutorial in @ref{Pointing pattern design}.
 
 @item astscript-radial-profile
 (See @ref{Generate radial profile}) Calculate the radial profile of an object 
within an image.
@@ -1184,13 +1185,15 @@ See Infante-Sainz et al. 
@url{https://arxiv.org/abs/2401.05303,2024}.
 @item astscript-color-faint-gray
 (see @ref{Color images with gray faint regions}) Given three images for the 
Red-Green-Blue (RGB) channels, this script will use the bright pixels for color 
and will show the faint/diffuse regions in grayscale.
 This greatly helps in visualizing the full dynamic range of astronical data.
-See Infante-Sainz et al. @url{https://arxiv.org/abs/2401.03814,2024}.
+See Infante-Sainz et al. @url{https://arxiv.org/abs/2401.03814,2024} or a 
dedicated tutorial in @ref{Color images with full dynamic range}.
 
 @item astscript-sort-by-night
 (See @ref{Sort FITS files by night}) Given a list of FITS files, and a HDU and 
keyword name (for a date), this script separates the files in the same night 
(possibly over two calendar days).
 
 @item astscript-zeropoint
 (see @ref{Zero point estimation}) Estimate the zero point (to calibrate pixel 
values) of an input image using a reference image or a reference catalog.
+This is necessary to produce measurements with physical units from new images.
+See Eskandarlou et al. @url{https://arxiv.org/abs/2312.04263,2023}, or a 
dedicated tutorial in @ref{Zero point of an image}.
 
 @item astscript-psf-*
 The following scripts are used to estimate the extended PSF estimation and 
subtraction as described in the tutorial @ref{Building the extended PSF}:
@@ -9366,6 +9369,7 @@ For more on the definition and importance of the zero 
point magnitude, see @ref{
 @cindex SDSS
 In this tutorial, we will use Gnuastro's @command{astscript-zeropoint}, to 
estimate the zero point of a single exposure image from the 
@url{https://www.j-plus.es, J-PLUS survey}, while using an 
@url{http://www.sdss.org, SDSS} image as reference (recall that all SDSS images 
have been calibrated to have a fixed zero point of 22.5).
 In this case, both images that we are using were taken with the SDSS @emph{r} 
filter.
+See Eskandarlou et al. @url{https://arxiv.org/abs/2312.04263,2023}.
 
 @cartouche
 @cindex Johnson filters
@@ -34122,6 +34126,7 @@ For the full set of options an a detailed description 
of each, see @ref{Invoking
 @node Invoking astscript-zeropoint,  , Zero point estimation, Zero point 
estimation
 @subsection Invoking astscript-zeropoint
 This installed script will calculate the zero point of an input image to 
calibrate it.
+A general overview of this script has been published in Eskandarlou et al. 
@url{https://arxiv.org/abs/2312.04263,2023}; please cite it if this script 
proves useful in your research.
 The reference can be an image or catalog (which have been previously 
calibrated)
 The executable name is @command{astscript-zeropoint}, with the following 
general template:
 
@@ -34339,8 +34344,11 @@ Use a non-standard Makefile for the Makefile to call.
 This option is primarily useful during the development of this script and its 
Makefile, not for normal/regular user.
 So if you are not developing this script, you can safely ignore this option.
 When this option is given, the default installed Makefile will not be used: 
the file given to this option will be read by @command{make} (within the 
script) instead.
-@end table
 
+@item --cite
+Give BibTeX and acknowledgment information for citing this script within your 
paper.
+For more, see @option{Operating mode options}.
+@end table
 
 @node Pointing pattern simulation, Color images with gray faint regions, Zero 
point estimation, Installed scripts
 @section Pointing pattern simulation