[gnuastro-commits] master 156da6c7 28/39: Book: Increase readability and correction

[Mohammad Akhlaghi]

branch: master
commit 156da6c796cd6ae31676afd4ceced648412f35c5
Author: Zahra Sharbaf <zahra.sharbaf2@gmail.com>
Commit: Mohammad Akhlaghi <mohammad@akhlaghi.org>

    Book: Increase readability and correction
    
    Until now, the tutorial on the zero-point script was written by Elham
    Saremi, and some corrections have been added by other members.
    
    With this commit, I re-wrote some parts of the tutorial to increase
    readability, and some corrections have been added.
---
 doc/gnuastro.texi | 106 +++++++++++++++++++++++++++++-------------------------
 1 file changed, 58 insertions(+), 48 deletions(-)

diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index 8e55d623..748a1625 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -29612,16 +29612,16 @@ Due to this, in observational astronomy data 
analysis, mostly brightness and mag
 The essential thing here is that the magnitude is the same as the brightness 
which is reported in logarithem unit.
 In order to magnitude of an objecets to be dimensionless, its brightness is 
divided by the reference brightness.
 The amount of the reference brigntness is considered to be one, therefore 
reference magnitude commonly known as zero point magnitude.
-Zero point magnitude describe whole the hardware-specific which causes the 
difference in the magnitude of an object in differ images.
+The zero point magnitude describes the hardware-specific factors and 
observational factors that vary the magnitude of an object from image to image.
 More details are fully explained in @ref{Brightness flux magnitude}.
 
-Therefore, estimating the zero point is crucial calibration step in image 
processing.
+Therefore, estimating the zero point is a crucial calibration step in image 
processing.
 Moreover, zero point is essential to calibrate magnitude to standard magnitude.
-Formerly, Vega star's magnitude was used as zeropoint magnitude for obtaining 
the standard magnitude.
-But Vega star is not eternaly in the sky, and it can not be used as reference 
of zero point magnitude.
-These days, instead of Vega's magnitude, AB magnitude standard is used for 
calibration@footnote{@url{https://en.wikipedia.org/wiki/AB_magnitude}}.
-Gnuastro’s @command{astscript-zeropoint} script is created to obtain zero 
point of an image in a device, based on the image or catalog of another device 
that overlap with original image and their zero point are known.
+Formerly, the Vega star's magnitude was used as a zero-point magnitude for 
obtaining the standard magnitude.
+But the Vega star is not eternally in the sky and can not be used as a 
reference of zero point magnitude.
+These days, instead of Vega's magnitude, the AB magnitude standard is used for 
the calibration@footnote{@url{https://en.wikipedia.org/wiki/AB_magnitude}}.
 
+Gnuastro’s @command{astscript-zeropoint} script is created to obtain the zero 
point of an image in a device, based on the image or catalog of another device 
that overlaps with the original image, and their zero point is known.
 
 All the details of this script are explained in @ref{Photometric calibration 
of images by zero point}, @ref{Zero point based on the reference image} and 
@ref{Zero point based on the reference catalog}.
 
@@ -29634,29 +29634,30 @@ All the details of this script are explained in 
@ref{Photometric calibration of
 @node Photometric calibration of images by zero point, Invoking 
astscript-zeropoint, Zero point estimation, Zero point estimation
 @subsection Photometric calibration of images by zero point
 
-As described in @ref{Brightness flux magnitude}, to convert astronomical data 
pixel values from counts to energy/time (such as Janskys), we need to know the 
zero point of the image.
-This conversion is necessary to compare two images independently of the 
facility used to retrieve them and calibrate an astronomical image to a common 
standard.
+As described in @ref{Brightness flux magnitude}, to convert astronomical data 
pixel values from counts to energy/time (physical units such as Janskys), we 
need to know the zero point of the image.
+This conversion is necessary to compare two images independent of the used 
instruments for observing them.
+The zero point is used to calibrate an astronomical image to the standard 
state.
 
-To find the zero point, it is common to use photometric systems, images or 
catalogs depending on the purpose.
-For example, the SDSS data can be a good reference for finding zero point in 
optical images, while 2MASS data is good for near infra-red images.
-The general steps that we use to estimate the zero point of an image are given 
below:
+To find the zero point is common to use photometric systems with defined zero 
points, such as some images or catalogs.
+For example, the SDSS data can be a good reference for finding the zero point 
in optical and 2MASS data for near-infrared images.
+The general outline of the steps that we use to estimate the zero point in an 
image is given below:
 
 @enumerate
 @item
-Download Gaia catalog using Gnuastro’s Query program (see @ref{Query}) to 
determine correct coordinates of stars in the image.
+Download the Gaia catalog using Gnuastro’s Query program (see @ref{Query}) to 
determine the correct coordinates of stars in the image.
 @item
-Select of reference image or catalog and download it.
+Select the reference image or catalog and download it.
 @item
 Perform Aperture photometry with MakeProfiles (see @ref{MakeProfiles}) and 
MakeCatalog (see @ref{MakeCatalog}); a complete tutorial can be found in 
@ref{Aperture photometry}.
 If the reference is an image, then we should perform aperture photometry also 
in that image.
 @item
-Match catalogs (see @ref{Match} and also a tutorial in @ref{Matching 
catalogs}) to obtain differences of magnitudes in two catalogs and estimate 
zero point value.
+Match catalogs (see @ref{Match} and also a tutorial in @ref{Matching 
catalogs}) to obtain differences of magnitudes in them and estimate zero point 
value.
 @end enumerate
 
-Clearly, all of the previous steps are very long and time consuming.
-Fortunately, Gnuastro has an installed script, designed to find zero point in 
an image based on a reference image or catalog with a defined zero point.
+All of the top steps are very long and somewhat complicated.
+Fortunately, Gnuastro has an installed script designed to find a zero point in 
an image based on a reference image or a catalog with a defined zero point.
 Here we have a tutorial on how to use @command{astscript-zeropoint}.
-This tutorial is divided into two parts; a first one using an image as a 
reference and the second one using a reference catalog.
+This tutorial is divided into two parts to cover both using an image or a 
catalog as reference data.
 
 @menu
 * Zero point based on the reference image::    Using SDSS images to find 
J-PLUS zero point
@@ -29666,10 +29667,11 @@ This tutorial is divided into two parts; a first one 
using an image as a referen
 @node Zero point based on the reference image, Zero point based on the 
reference catalog, Photometric calibration of images by zero point, Photometric 
calibration of images by zero point
 @subsubsection Zero point based on the reference image
 
-To understand how to use the @command{astscript-zeropoint}, we find the zero 
point for a single exposure image from the @url{https://www.j-plus.es,J-PLUS 
survey} based on an SDSS reference image @url{http://www.sdss.org/, Sloan 
Digital Sky Survey} with a zero point of 22.5 mag.
+To understand how to use the @command{astscript-zeropoint}, we find the zero 
point for a single exposure image from the @url{https://www.j-plus.es, J-PLUS 
survey} based on an SDSS reference image @url{htt\
+p://www.sdss.org/, Sloan Digital Sky Survey} with a zero point of 22.5 mag.
 
-First, let’s create a directory named @file{zp}, to keep things clean.
-Then, with the commands below you can download the image  used in @ref{Moire 
pattern and its correction} from the J-PLUS dataset in the r- Sloan band and  
crop the central part of the image to speed up the analysis.
+First, let’s create a directory named @file{zp} to keep things clean.
+Then with the commands below, you can download an image such as one used in 
@ref{Moire pattern and its correction} from the J-PLUS dataset in the r (SDSS) 
band and then crop the center part of the image to speed up the analysis in 
this tutorial.
 
 @example
 $ mkdir zp
@@ -29679,10 +29681,11 @@ $ astcrop zp/jplus.fits.fz --center=107.7263,40.1754 \
           --width=0.6 --output=zp/jplus-crop.fits
 @end example
 
-Although we cropped the J-PLUS image, it is still very large in comparison 
with the SDSS image (the J-PLUS field of view is almost @mymath{1.5\times1.5} 
deg@mymath{^2}, while the field of view of SDSS in each filter is almost 
@mymath{0.3\times0.5} deg@mymath{^2}).
-So let's download two SDSS images (and then decompress them) in the region of 
the J-PLUS cropped image for having a more accurate result.
-Make sure that the filters you use are the same since we have different 
@emph{r} filters (such as SDSS or Johnson).
-In this case we use the SDSS @emph{r} filter for both cases.
+Although we cropped the J-PLUS image is still very large in comparison with 
the SDSS image (the J-PLUS field of view is almost @mymath{1.\5\times1.5} 
deg@mymath{^2}, while the field of view of the SDSS in each filter is almost 
@mymath{0.3\times0.5} deg@mymath{^2}).
+So, let's download two SDSS images (and then decompress them) in the region of 
the J-PLUS cropped image to have a more accurate result.
+Make sure that the filters you use are both the same.
+The reason is that we have different @emph[r] filters, such as SDSS and 
Johnson.
+In this case, we use the SDSS @emph{r} filter for both cases.
 
 @example
 $ sdssbase=https://dr12.sdss.org/sas/dr12/boss/photoObj/frames
@@ -29700,19 +29703,18 @@ To have a feeling of the data, open all three images 
with @command{astscript-fit
 $ astscript-fits-view zp/jplus-crop.fits zp/sdss1.fits zp/sdss2.fits
 @end example
 
-Before continuing, due to the fact that the referenced image (SDSS) is a 
Sky-subtracted and calibrated image, we should remove the Sky value also from 
the J-PLUS data in order to make a comparison.
-To subtract the Sky value, we use the @code{INPUT-NO-SKY} extension of 
NoiseChisel’s output.
-See @ref{NoiseChisel} for more details.
+Before continuing, as the reference image (SDSS) is a Sky-subtracted 
calibrated image, thus we should subtract the Sky value from the J-PLUS image 
to be comparable.
+It is easy to subtract the Sky value using NoiseChisel's @code[INPUT-NO-SKY] 
extension.
+You can see @ref{NoiseChisel} for more details.
 
 @example
 $ astnoisechisel zp/jplus-crop.fits --output=zp/jplus-nc.fits
 @end example
 
-We are ready to start finding the zero point.
-Let's call the @command{astscript-zeropoint} with the @option{--help} to see 
the mandatory and optional parameters and see @ref{Invoking 
astscript-zeropoint} for more details.
-At first, we use the script in the most basic state by
-keeping only the essential options. These include the information of the input 
image, the reference image, and the aperture radius for the photometry. Let's 
assume an initial aperture of 3 arcsecond to start.
-
+We are now ready to start finding the zero point.
+Please, call the @command{astscript-zeropoint} with the @option{--help} to see 
option names and also see @ref{Invoking astscript-zeropoint} for more details.
+For the first time, let's use the script in a simple state.
+Keep only the essential options that are including the information of the 
input image and reference images, and also determine an aperture radius, for 
example, 3 arcsec to start:
 
 @example
 $ astscript-zeropoint --help
@@ -29762,10 +29764,16 @@ Number of rows: 321
 --------
 @end example
 
-As you can see, in the first extension, there are the zero point and the 
standard deviation of zero point (@code{ZPSTD}) for the selected aperture size.
-The second extension instead, contains a table including the SDSS magnitudes 
and the differences with J-PLUS magnitudes for estimating the zero point.
-Now that we got more familiar with the script and its initial result, let’s 
continue by considering more options to obtain a more accurate estimate.
+As you see, in the first extension, there is a zero point and the standard 
deviation of the zero point (@code{ZPSTD}) for the selected aperture size.
+The second extension contains a table including the SDSS magnitudes and 
differences with the J-PLUS magnitudes for estimating the zero point.
+Now that we know about the script and its initial result; let’s continue by 
considering options to obtain a more accurate result.
 
+One of the most important parameters of this script is the aperture size, 
@option{--aperarcsec}, for the aperture photometry of the images and creating 
the catalogs.
+On the one hand, if the selected aperture radius is too small, a part of the 
light of the star will be ignored in the magnitude estimation.
+On the other hand, with a large aperture size, the light of neighboring stars 
affects the magnitude calculation.
+Logically we should select an aperture radius around 2 to 3 times the FWHM of 
the image.
+Practically, we compare the result for several aperture sizes and choose the 
best one based on the minimum @code{ZPSTD} parameter. However, it should 
calculate in a proper range of magnitude that we will explain in continuing.
+For now, let's assume the values 2, 3, 4, 5, and 6 arcsec for this option.
 
 One of the most important parameters of this script is the aperture size, 
@option{--aperarcsec}, for the aperture photometry of images.
 On one hand, if the selected aperture radius is too small, part of the light 
of the star will be not taken into account in the magnitude estimation and it 
would be underestimated.
@@ -29776,8 +29784,8 @@ What the code does is to compare the result for several 
aperture sizes and choos
 However, it should be computed in a proper range of magnitude.
 As a matter of fact, the next important point is whether all of the bright or 
faint stars in the input image are comparable with reference stars.
 To better clarify, let’s check the result of matching the J-PLUS catalog with 
the SDSS reference catalog.
-Note that two catalogs created by aperture photometry from SDSS image are 
merged so that there are more stars to compare.
-If you like to access the temporary files in the intermediate steps, you can 
use @option{--keeptmp} option, that otherwise are being removed.
+Note that the two catalogs created by aperture photometry from the SDSS image 
are merged so that there are more stars to compare.
+If you like to access the temporal files in the intermediate steps, you can 
use @option{--keeptmp} option to prevent from being removed of them.
 
 Using Gnuastro’s @command{astscript-fits-view}, you can visualize a table 
created from matching J-PLUS and SDSS catalogs in the second extension of the 
output file as a plot by @code{TOPCAT}.
 
@@ -29788,7 +29796,8 @@ $ astscript-fits-view zp/jplus-zeropoint.fits --hdu=2
 
 After @code{TOPCAT} opens, you can select the ``Graphics'' menu and then 
``Plain plot'' to see a plot that shows the difference of magnitudes of J-PLUS 
and SDSS stars versus SDSS magnitudes for a specific aperture radius which is 3 
arcsec, here.
 
-After @code{TOPCAT} opens, you can select the ``Graphics'' menu and then 
``Plain plot'' to see a plot that shows the difference of magnitudes of J-PLUS 
and SDSS stars versus SDSS magnitudes for a specific aperture radius which is 3 
arcsec in this case.
+Ideally, it is expected that differences in magnitudes be around a straight 
line with very small fluctuations.
+But in practice, as you can see in your plot, this behavior is seen only for 
stars with magnitudes about 16 to 18 mag in reference SDSS catalog.
 
 Ideally, one would expect that the differences in magnitudes are placed along 
a straight line with very small fluctuations.
 But in practice, as you can see in your plot, this behavior is seen only for 
stars with magnitudes between 16 to 18 mag in the SDSS catalog.
@@ -29796,13 +29805,12 @@ But in practice, as you can see in your plot, this 
behavior is seen only for sta
 The brighter stars are probably saturated and thus they do not have the 
correct magnitude in the SDSS catalogs (for more details about saturated pixels 
and recognition of the saturated level of the image, please see @ref{Saturated 
pixels and Segment's clumps}).
 You can check some of these stars visually by opening the images.
 
-On the other hand, it is natural that there are no accurate magnitudes for the 
faint stars in the SDSS catalog, because the completeness limit of each image 
is limited and so such faint stars are not good references for estimating zero 
point.
+On the other hand, it is natural there are no accurate magnitudes for the 
faint stars in the SDSS catalog because the completeness limit of each image is 
limited and so such faint stars are not good references for estimating the zero 
points.
 So, let's limit the range of used magnitudes from the SDSS catalog to 
calculate a more accurate zero point for the J-PLUS image.
 For that, there is the @option{--magnituderange} option in the 
@command{astscript-zeropoint}.
 
-Before continuing, to further understand the effect of subtracting the sky 
from the J-PLUS image, repeat the above commands only by changing the input 
file to ``jplus-crop.fits''.
-Then use Gnuastro’s @command{astscript-fits-view} again to draw a plot by 
@code{TOPCAT} such as before.
-Clearly, you can see a bad result. This means that this is not a reasonable 
range of magnitude for finding the zero point.
+Before continuing, for more understanding of the effect of subtracting the sky 
from the J-PLUS image, please, repeat the above commands only by changing the 
input file to ``jplus-crop.fits''.
+Then use Gnuastro’s @command{astscript-fits-view} again to draw a plot by 
@code{TOPCAT} such as before. You can see a bad result so that there is not any 
reasonable range of magnitude for finding the zero point.
 
 Let's re-run the script with this new option (@option{--magnituderange}) and 
more values for aperture size as pointed out.
 Also, use the useful @option{--keepzpap} option to keep the result of matching 
the catalogs made with selected apertures in the different extensions of the 
output file.
@@ -29815,8 +29823,8 @@ $ astscript-zeropoint zp/jplus-nc.fits 
--hdu=INPUT-NO-SKY \
                       --keepzpap --output=zp/jplus-zeropoint.fits
 @end example
 
-Now the output file includes 6 extensions.
-The first one shows the zero point properties for different apertures and all 
the others are related to the different magnitudes at each aperture radius.
+Now the output file is including 6 extensions.
+The first one shows the zero point properties in various apertures and all 
others are related to the different magnitudes at each aperture radius.
 
 Plot all magnitude tables by @code{TOPCAT} and at the same time, see the 
@code{ZPSTD} of zero points for each aperture to estimate an accurate magnitude 
range.
 
@@ -29838,7 +29846,7 @@ So the apertures with radii of 2 and 3 arcseconds are 
better than others.
 Let's focus on the magnitude plots in these two apertures and determine a more 
accurate range of magnitude.
 The more reliable option is the range between 16.4 and 17.8 mag.
 
-To see the final result for zero point, re-run the script with the new 
magnitude range.
+To see the final result for the zero point, please, re-run the script with the 
new magnitude range.
 
 @example
 $ astscript-zeropoint zp/jplus-nc.fits --hdu=INPUT-NO-SKY \
@@ -29849,7 +29857,9 @@ $ astscript-zeropoint zp/jplus-nc.fits 
--hdu=INPUT-NO-SKY \
                       --output=zp/jplus-zeropoint.fits
 @end example
 
-Luckly, the @command{astscript-zeropoint} script can estimate automatically 
the best aperture (as @code{ZPAPER} keyword) and thus the best zero point (as 
@code{ZPVALUE} keyword) based on the minimum of @code{ZPSTD}. You can save them 
with the magnitude range (as @code{MAGMIN} and @code{MAGMAX} keywords) in the 
header of the output file with the command below:
+Fortunately, the @command{astscript-zeropoint} script can estimate the best 
aperture (as @code{ZPAPER} keyword) and thus the best zero point (as 
@code{ZPVALUE} keyword) based on the minimum of @code{ZPSTD} automatically.
+Then set them along with the magnitude range (as @code{MAGMIN} and 
@code{MAGMAX} keywords) in the header of the output file easily.
+Please see it by the command like below:
 
 @example
 $ astfits zp/jplus-zeropoint.fits --hdu=1 --quiet \
@@ -29900,7 +29910,7 @@ Please see the @code{ZPSTD} of zero points for each 
aperture at the first extens
 The best @code{ZPSTD}s are related to aperture radii of 2 and 3 arcsec.
 At the same time, please open the output file by TOPCAT and plot all magnitude 
tables and especially those which are related to aperture sizes of 2 and 3 
arcsec to estimate an accurate magnitude range.
 As you can see, the differences in magnitudes are around a straight line in 
the range of around 15.5 to 18 mag, however, there are many fluctuations in the 
plot.
-Although we use the sigma clipping in calculating zero points and so remove 
the most of outliers (for more details please see @ref{Sigma clipping}), 
nevertheless, it is good to limit the range of magnitude.
+Although we use the sigma clipping in calculating the zero points and so 
remove the most of outliers (for more details please see @ref{Sigma clipping}), 
nevertheless, it is good to limit the range of magnitude.
 We can select an area with lower fluctuations for example around 16.8 to 17.8 
mag.
 
 @example
@@ -29922,7 +29932,7 @@ $ astfits zp/jplus-zeropoint.fits --hdu=1 --quiet \
 2.000000  26.336220  0.029594  16.799999  17.799999
 @end example
 
-The @command{astscript-zeropoint} script selected an aperture radius of 2 
arcsec as best, however, you can see that the result for an aperture size of 3 
arcsec is acceptable, also.
+The @command{astscript-zeropoint} script selected an aperture radius of 2 
arcsec as the best, however, you can see that the result for an aperture size 
of 3 arcsec is acceptable, also.
 Actually, @code{ZPSTD}s for them have no significant difference.
 So it is good to check all of the results in the first extension of the output 
file before making a final decision.