[gnuastro-commits] master 458f6167 1/9: Book: considering only two set of stars for the extended PSF tutorial

[Mohammad Akhlaghi]

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

    Book: considering only two set of stars for the extended PSF tutorial
    
    Until now, the range of magnitudes for constructing the outer and inner
    part of the PSF (in the Building the extended PSF tutorial) were such as we
    only had a very few images for the outer part, and also saturated stars for
    the inner part. Although the original idea was to construct several inner
    parts and concatenate them together to have high signal to noise in the
    outer part and not saturation in the center, that could make the tutorial
    very long and difficult to follow. As a consequence, I decided to simplify
    it to only have two PSF parts: outer and inner.
    
    With this commit, only two set of stars are considered. One for the outer
    part (although mixing very different brightness stars) and the other for
    the core of the PSF (mixing saturated and not saturated stars). Eventhough
    this would not be the reality, it simplify a lot the tutorial because only
    two different PSFs are necessary while explaining the main ideas.
    
    With this commit several parts of the tutorial have been changed to take
    into account this changes. In addition to this, minor typos have been
    corrected. Right now, everything is ready to continue describing the
    process of joining the two different parts of the PSF (outer and inner).
---
 doc/gnuastro.texi | 67 +++++++++++++++++++++++++++++--------------------------
 1 file changed, 35 insertions(+), 32 deletions(-)

diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index 5d50a4b2..e0f327ca 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -5612,7 +5612,7 @@ $ astarithmetic sat-masked.fits 2 interpolate-maxofregion 
\
                 --output=sat-fill.fits
 $ astarithmetic sat-masked-conv.fits 2 interpolate-maxofregion \
                 --output=sat-fill-conv.fits
-$ ds9 sat-conv.fits -cmap sls -zoom 8
+$ ds9 sat-fill-conv.fits -cmap sls -zoom 8
 @end example
 
 @noindent
@@ -5684,9 +5684,9 @@ We see that the saturated pixels haven't caused any 
problems and the central clu
 We can now proceed to estimating the outer PSF in @ref{Building outer part of 
PSF}.
 
 But before that, let's make a ``standard'' segment output: one that can safely 
be fed into MakeCatalog for measurements.
-The main problem is again the saturted pixels: we interpolated them to be the 
maximum of their nearby pixels.
+The main problem is again the saturated pixels: we interpolated them to be the 
maximum of their nearby pixels.
 But this will cause problems in any measurement that is done over those 
regions.
-To let MakeCatalog know that those pixels shouldn't be used, the first 
extension of the file given to MakeCatlog should have blank values on those 
pixels.
+To let MakeCatalog know that those pixels shouldn't be used, the first 
extension of the file given to MakeCatalog should have blank values on those 
pixels.
 We will do this with the commands below:
 
 @example
@@ -5739,7 +5739,7 @@ So we are now ready to start building the outer parts of 
the PSF.
 
 First we will build the outer parts of the PSF, so we want the brightest stars.
 You will see we have several bright stars in this very large field of view, 
but we don't yet have a feeling how many they are, and at what magnitudes.
-So let's use Gnuastro's Query program to find the magnitudes of the brightest 
stars (those brighter than magnitude 12).
+So let's use Gnuastro's Query program to find the magnitudes of the brightest 
stars (those brighter than g-magnitude 12 in Gaia EDR3).
 For more on Query, see @ref{Query}.
 
 @example
@@ -5755,25 +5755,25 @@ $ astscript-ds9-region gaia.fits -cra,dec \
            --command="ds9 flat/67510.fits -zoom to fit -zscale"
 @end example
 
-You can see that we have several stars between magnitudes 6 to 10.
-Let's use @file{astscript-psf-create-select-stars} in the command below to 
select the relevant stars in the image (the brightest; with a magnitude between 
6 to 8).
+You can see that we have several stars between magnitudes 6 to 12.
+Let's use @file{astscript-psf-create-select-stars} in the command below to 
select the relevant stars in the image (the brightest; with a magnitude between 
6 to 12).
 Since this will select very bright stars, we will also increase the distance 
to nearby neighbors with brighter or similar magnitudes (the default value is 1 
arcmin).
 To do this, we will set @option{--mindistdeg=0.05}, which corresponds to 3 
arcmin (or 3/60 degrees).
 
 @example
 $ mkdir outer
 $ astscript-psf-create-select-stars flat/67510.fits \
-           --magnituderange=6,8 --mindistdeg=0.05 \
-           --output=outer/67510-6-8.fits
+           --magnituderange=6,12 --mindistdeg=0.05 \
+           --output=outer/67510-6-12.fits
 @end example
 
 @noindent
 Let's have a look at the selected stars in the image (it is very important to 
visually check every step when you are first discovering a new dataset).
 
 @example
-$ astscript-ds9-region outer/67510-6-8.fits -cra,dec \
+$ astscript-ds9-region outer/67510-6-12.fits -cra,dec \
            --namecol=phot_g_mean_mag \
-           --command='ds9 flat/67510.fits -zoom to fit -zscale'
+           --command="ds9 flat/67510.fits -zoom to fit -zscale"
 @end example
 
 Now that the catalog of good stars is ready, it is time to construct the 
individual stamps for each star of the catalog.
@@ -5793,11 +5793,12 @@ Otherwise the script will not generate the radial 
profile.
 As a consequence, in this step we put the normalization radii equal to the 
size of the stamps.
 By doing this, the script will generate the radial profile of the entire stamp.
 In this particular step we set it to @code{--normradii=150,160}.
+Furthermore, since there are several stars, we iterate over each row of the 
catalog using a while loop.
 
 @example
 $ counter=1
 $ mkdir finding-normradii
-$ asttable outer/67510-6-8.fits \
+$ asttable outer/67510-6-12.fits \
            | while read -r ra dec mag; do
                astscript-psf-create-make-stamp label/67510-seg.fits \
                     --mode=wcs \
@@ -5820,24 +5821,26 @@ $ topcat finding-normradii/rprofile*.fits
 $ ds9 finding-normradii/cropped-masked*.fits
 @end example
 
-After some study of this data, we could say that a good normalization ring is 
those pixels between R=50 and R=60 pixels.
+After some study of this data, we could say that a good normalization ring is 
those pixels between R=20 and R=30 pixels.
 Such a ring ensures having a high number of pixels so the estimation of the 
flux normalization will be robust.
 Also, at such distance from the center the signal to noise is high and there 
are not obvious features that can affect the normalization.
+Note that the profiles are different because we are considering a wide range 
of magnitudes, so the fainter stars are much more noisy.
+However, in this tutorial we will keep these stars in order to have a higher 
number of stars for the outer part.
+In a real case scenario, we should look for stars with a much more similar 
brightness (smaller range of magnitudes) to not lose signal to noise as a 
consequence of the inclusion of fainter stars.
 
 We later need the normalization radii in the next steps also.
 Therefore, to avoid typos or chances of a mistake, we'll define the two 
@code{NORMRADII_INNER} and @code{NORMRADII_OUTER} variables.
-Furthermore, since there are several stars (as you saw from the output of the 
previous command), we iterate over each row of the catalog.
 
 @example
 $ counter=1
 $ mkdir outer/stamps
-$ asttable outer/67510-6-8.fits \
+$ asttable outer/67510-6-12.fits \
            | while read -r ra dec mag; do
                astscript-psf-create-make-stamp label/67510-seg.fits \
                     --mode=wcs \
                     --stampwidth=500 \
                     --center=$ra,$dec \
-                    --normradii=50,60 \
+                    --normradii=20,30 \
                     --segment=label/67510-seg.fits \
                     --output=outer/stamps/67510-$counter.fits; \
                counter=$((counter+1)); \
@@ -5862,8 +5865,8 @@ You clearly see that the number of masked pixels is 
significantly decreased and
 $ ds9 outer/stack.fits outer/stamps/*.fits
 @end example
 
-However, the bleeding, vertical saturation in the center still remains.
-Also, because we didn't have too many images (only three!), some small regions 
still remain that were (by chance!) masked in all three.
+However, the saturation in the center still remains.
+Also, because we didn't have too many images, some regions still are very 
noisy.
 If we had more bright stars in our selected magnitude range, we could have 
filled those outer remaining patches.
 In a large survey like J-PLUS (that we are using here), you can simply look 
into other fields that were observed soon before/after the tile ID 67510 that 
we used here (to have a similar PSF) and get more stars in those images to add 
to these.
 Infact, the J-PLUS DR2 tile ID of the field above was intentially preserved 
during the steps above to show how easy it is to use images from other fields 
and blend them all into the output PSF.
@@ -5890,45 +5893,45 @@ In @ref{Building outer part of PSF}, we were able to 
create a stack of the outer
 But the central part that was affected by saturation and non-linearity is 
still remaining, and we still don't have a ``complete'' PSF!
 In this section, we will use the same steps before to make stacks of more 
inner regions of the PSF to ultimately unite them all into a single PSF in 
@ref{Uniting the different PSF components}.
 
-For the outer PSF, we selected stars in the magnitude range of 6 to 8.
-So let's have a look and see how many stars we have in the magnitude range of 
8-10 and use the ds9 region script to visually inspect them:
+For the outer PSF, we selected stars in the magnitude range of 6 to 12.
+So let's have a look and see how many stars we have in the magnitude range of 
12-13 with a more relaxed condition on the minimum distance for neighbours, 
@option{--mindistdeg=0.01} (36 arcsec), and use the ds9 region script to 
visually inspect them:
 
 @example
-$ mkdir inner-1
+$ mkdir inner
 $ astscript-psf-create-select-stars flat/67510.fits \
-           --magnituderange=8,10 --mindistdeg=0.05 \
-           --output=inner-1/67510-8-10.fits
+           --magnituderange=12,13 --mindistdeg=0.01 \
+           --output=inner/67510-12-13.fits
 
-$ astscript-ds9-region inner-1/67510-8-10.fits -cra,dec \
+$ astscript-ds9-region inner/67510-12-13.fits -cra,dec \
            --namecol=phot_g_mean_mag \
            --command="ds9 flat/67510.fits -zoom to fit -zscale"
 @end example
 
-We only have two stars, but they if you zoom into their centers, you will see 
that they don't have any major bleeding-vertical saturations any more!
-Only the immediate center of the star is saturated.
+We have 41 stars, but if you zoom into their centers, you will see that they 
don't have any major bleeding-vertical saturations any more.
+Only the very central core of some of the star is saturated.
 We can therefore use these stars to fill the strong bleeding footprints that 
were present in the outer stack of @file{outer/stack.fits}.
 Similar to before, let's build ready-to-stack crops of these stars.
 To get a better feeling of the normalization radii, follow the same steps of 
@ref{Building outer part of PSF} (setting @option{--tmpdir} and 
@option{--keeptmp}).
 
 @example
 $ counter=1
-$ mkdir inner-1/stamps
-$ asttable inner-1/67510-8-10.fits \
+$ mkdir inner/stamps
+$ asttable inner/67510-12-13.fits \
            | while read -r ra dec mag; do
                astscript-psf-create-make-stamp label/67510-seg.fits \
                     --mode=wcs \
                     --stampwidth=500 \
                     --center=$ra,$dec \
-                    --normradii=30,40 \
+                    --normradii=5,10 \
                     --segment=label/67510-seg.fits \
-                    --output=inner-1/stamps/67510-$counter.fits; \
+                    --output=inner/stamps/67510-$counter.fits; \
                counter=$((counter+1)); \
              done
 
-$ imgs=inner-1/stamps/*.fits
+$ imgs=inner/stamps/*.fits
 $ numimgs=$(echo $imgs | wc -w)
-$ astarithmetic $imgs $numimgs median -g1 --output=inner-1/stack.fits
-$ ds9 inner-1/stack.fits inner-1/stamps/*.fits
+$ astarithmetic $imgs $numimgs median -g1 --output=inner/stack.fits
+$ ds9 inner/stack.fits inner/stamps/*.fits
 @end example
 
 @noindent