[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[gnuastro-commits] master 23b809aa 3/5: Book: minor changes in the descr
From: |
Mohammad Akhlaghi |
Subject: |
[gnuastro-commits] master 23b809aa 3/5: Book: minor changes in the description of PSF scripts options |
Date: |
Sat, 19 Mar 2022 14:22:41 -0400 (EDT) |
branch: master
commit 23b809aa03913de4f7610dfe6838ab0e61723073
Author: Raul Infante-Sainz <infantesainz@gmail.com>
Commit: Mohammad Akhlaghi <mohammad@akhlaghi.org>
Book: minor changes in the description of PSF scripts options
Until now, the documentation about how to invoke the PSF scripts and their
options were not updated properly.
With this commit, several minor changes have been done with the aim of keep
everything up-to-date. In addition to that, minor changes have been also
done in two PSF scripts.
---
bin/script/psf-stamp.in | 4 +-
bin/script/psf-unite.in | 9 +++--
doc/gnuastro.texi | 99 ++++++++++++++++++++++++-------------------------
3 files changed, 56 insertions(+), 56 deletions(-)
diff --git a/bin/script/psf-stamp.in b/bin/script/psf-stamp.in
index e0146e48..37be18a1 100644
--- a/bin/script/psf-stamp.in
+++ b/bin/script/psf-stamp.in
@@ -382,7 +382,7 @@ objectid="$xcoord"_"$ycoord"
# mode will be generated.
bname_prefix=$(basename "$inputs" | sed 's/\.fits/ /' | awk '{print $1}')
if [ x"$tmpdir" = x ]; then \
- tmpdir=$(pwd)/"$bname_prefix"_psfcreatemakestamp
+ tmpdir=$(pwd)/"$bname_prefix"_stamp
fi
if [ -d "$tmpdir" ]; then
@@ -393,7 +393,7 @@ fi
# Output
if [ x"$output" = x ]; then
- output="$bname_prefix"_psfcreatemakestamp_$objectid.fits
+ output="$bname_prefix"_stamp_$objectid.fits
fi
diff --git a/bin/script/psf-unite.in b/bin/script/psf-unite.in
index 33a2eff7..f92e9c50 100644
--- a/bin/script/psf-unite.in
+++ b/bin/script/psf-unite.in
@@ -301,7 +301,7 @@ fi
bname_outer=$(basename $inputs | sed 's/\.fits/ /' | awk '{print $1}')
bname_inner=$(basename $inner | sed 's/\.fits/ /' | awk '{print $1}')
if [ x$tmpdir = x ]; then \
- tmpdir=$(pwd)/"$bname_outer"_psfcreatejunction
+ tmpdir=$(pwd)/"$bname_outer"_unite
fi
if [ -d $tmpdir ]; then
@@ -312,7 +312,7 @@ fi
# Output
if [ x$output = x ]; then
- output="$bname_outer"_"$bname_inner"_psfcreatejunction.fits
+ output="$bname_outer"_"$bname_inner"_unite.fits
fi
@@ -491,8 +491,9 @@ echo "1 $xcentmask $ycentmask 5 $radius 1 $positionangle
$axisratio 1 1" \
# image with the same pixels of the inner image.
astarithmetic $inputs --hdu=$hdu set-outer \
$innerfluxscaled --hdu=1 set-inner \
- $maskimage --hdu=1 set-mask \
- outer mask inner where -o$output $quiet --wcsfile=none
+ $maskimage --hdu=1 set-mask \
+ outer mask inner where \
+ --wcsfile=none --output=$output $quiet
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index ea9a7844..d56e400e 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -24896,7 +24896,7 @@ The initial DS9 window geometry (value to DS9's
@option{-geometry} option).
@section PSF construction and subtraction
The point spread function (PSF) describes how the light of a point-like source
is affected by several optical scattering effects (atmosphere, telescope,
instrument, etc.).
-Since the light all astrophysical sources undergoes all these effects,
characterizing the PSF is key in astronomical analysis (for small and large
objects).
+Since the light of all astrophysical sources undergoes all these effects,
characterizing the PSF is key in astronomical analysis (for small and large
objects).
Consequently, having a good characterization of the PSF is fundamental to any
analysis.
In some situations@footnote{An example scenario where a parametric PSF may be
enough: you are only interested in very small, high redshift objects that only
extended a handful of pixels.} a parametric (analytical) model is sufficient
for the PSF (Gaussian, Moffat, etc., see @ref{PSF}).
@@ -24945,17 +24945,17 @@ All scripts are independent of each other, meaning
this that you are free to use
For constructing the PSF from your dataset, the first step is to obtain a
catalog of stars within it (you can't use galaxies to build the PSF!).
But you can't blindly use all the stars either!
For example we don't want contamination from other bright, and nearby objects.
-The first script below is therefore designed for selecting only good candidate
stars in your image.
+The first script below is therefore designed for selecting only good star
candidates in your image.
It will use different criteria, for example good parallax (where available, to
avoid confusion with galaxies), not being near to bright stars, axis ratio, etc.
For more on this script, see @ref{Invoking astscript-psf-select-stars}.
-Once the catalog of stars is constructed, another script is in charge of
making appropiate stamps of the stars.
+Once the catalog of stars is constructed, another script is in charge of
making appropriate stamps of the stars.
Each stamp is a cropped image of the star with the desired size, normalization
of the flux, and mask of the contaminant objects.
For more on this script, see @ref{Invoking astscript-psf-stamp}
After obtaining a set of star stamps, they can be stacked for obtaining the
combined PSF from many stars (for example with @ref{Stacking operators}).
In the combined PSF, the masked background objects of each star's image will
be covered and the signal-to-noise ratio will increase, giving a very nice view
of the ``clean'' PSF.
-However, is usually necessary to obtain different regions of the same PSF from
different stars.
+However, it is usually necessary to obtain different regions of the same PSF
from different stars.
For example, to construct the far outer wings of the PSF, it is necessary to
consider very bright stars.
However, these stars will be saturated in the most inner part, and immediately
outside of the saturation level, they will be deformed due to non-linearity
effects.
Consequently, fainter stars are necessary for the inner regions.
@@ -24975,10 +24975,12 @@ We therefore have another script that will calculate
the scale (multiplication)
For more on the scaling script, see @ref{Invoking astscript-psf-scale-factor}.
Once the flux factor has been computed, a final script is in charge of placing
the scaled PSF over the proper location in the image, and subtracting it.
+It is also possible to only obtain the modeled star by the PSF.
For more on the scaling and positioning script, see @ref{Invoking
astscript-psf-subtract}.
As mentioned above, in the following sections, each script has its own
documentation and list of options for very detailed customization (if
necessary).
-But if you are new to these scripts, before continuing, we recommend that you
do the tutorial @ref{Building the extended PSF}, just don't forget to run every
command, and try to tweek its steps based on the logic to nicely understand it.
+But if you are new to these scripts, before continuing, we recommend that you
do the tutorial @ref{Building the extended PSF}.
+Just don't forget to run every command, and try to tweek its steps based on
the logic to nicely understand it.
@@ -25006,8 +25008,10 @@ $ astscript-psf-select-stars image.fits \
--magnituderange=6,10 --mindistdeg=0.02
@end example
-The input of this script is an image, and the output is a catalog of stars in
requested range of magnitudes (provided with @option{--magnituderange}).
-The output catalog will also only contain stars that are sufficiently distant
(@option{--mindistdeg}) from all brighter, and some fainter stars.
+The input of this script is an image, and the output is a catalog of stars
with brightness in the requested range of magnitudes (provided with
@option{--magnituderange}).
+The output catalog will also only contain stars that are sufficiently distant
(@option{--mindistdeg}) from all other brighter, and some fainter stars.
+It is possible to consider different datasets with the option
@option{--dataset}.
+By default, Gaia eDR3 dataset is considered: @option{--dataset="gaia
--dataset=edr3"}
All stars that are @option{--faintmagdiff} fainter than the faintest limit
will also be accounted for, when selecting good stars.
The @option{--magnituderange}, and @option{--mindistdeg} are mandatory: if not
specified the code will abort.
@@ -25040,7 +25044,7 @@ When this option is given, @option{--dataset}
(described below) will be ignored
@item -d STR
@itemx --dataset=STR
-Optional dataset to query (with @ref{Query}).
+Optional dataset to query (see @ref{Query}).
It should contain the database and dataset entries to Query.
Its value will be immediately given to @command{astquery}.
By default, its value is @code{gaia --dataset=edr3} (so it connects to the
Gaia database and requests the early data release 3).
@@ -25052,18 +25056,18 @@ See their description for more.
@item -r STR
@itemx --racolumn=STR
The name of the column containing the Right Ascension (RA) in the requested
dataset (@option{--dataset}).
-If the user does not determine this option the, by default the @code{ra} will
be assumed.
+If the user does not determine this option, the default value is assumed to be
@code{ra}.
@item -d STR
@itemx --deccolumn=STR
The name of the column containing the Declination (Dec) in the requested
dataset (@option{--dataset}).
-If the user does not determine this option the, by default the @code{dec} will
be assumed.
+If the user does not determine this option, the default value is assumed to be
@code{dec}.
@item -f STR
@itemx --field=STR
The name of the column containing the magnitude in the requested dataset
(@option{--dataset}).
The output will only contain stars that have a value in this column, between
the values given to @option{--magnituderange} (see below).
-By default, the value of this option is @option{phot_g_mean_mag} (that
corresponds to the name of the magnitude in the Gaia catalog).
+By default, the value of this option is @option{phot_g_mean_mag} (that
corresponds to the name of the magnitude of the G-band in the Gaia catalog).
@item -m FLT,FLT
@itemx --magnituderange=FLT,FLT
@@ -25073,9 +25077,8 @@ This option is mandatory and no default value is
assumed.
@item -p STR,STR
@itemx --parallaxanderrorcolumn=STR,STR
With this option the user can provide the parallax and parallax error column
names in the requested dataset.
-When given, the output will only contain stars where the parallax has a
signal-to-noise ratio larger than 3.
-If the user does not provide this option, the script will not use parallax
information in selecting the stars.
-
+When given, the output will only contain stars for which the parallax value is
smaller than three times the parallax error.
+If the user does not provide this option, the script will not use parallax
information for selecting the stars.
In the case of Gaia, if you want to use parallax to further limit the good
stars, you can pass @option{parallax,parallax_error}.
@item -D FLT
@@ -25087,7 +25090,8 @@ For fainter stars (when constructing the center of the
PSF), you should decrease
@item -b INT
@itemx --brightmag=INT
The brightest star magnitude to avoid (should be brighter than the brightest
of @option{--magnituderange}).
-The basic idea is this: if a user asks for stars with magnitude 6 to 10 and
one of those stars is near a magnitude 3 star, that star (with a magnitude of 6
to 10) should be rejected!
+The basic idea is this: if a user asks for stars with magnitude 6 to 10 and
one of those stars is near a magnitude 3 star, that star (with a magnitude of 6
to 10) should be rejected because it is contaminated.
+But since the catalog is constrained to stars of magnitudes 6-10, the star
with magnitude 3 is not present and can not be compared with!
Therefore, when considering proximity to nearby stars, it is important to use
a larger magnitude range than the user's requested magnitude range for good
stars.
The acceptable proximity is defined by @option{--mindistdeg}.
@@ -25109,6 +25113,7 @@ For more, see the description of @option{--brightmag}.
@itemx --minaxisratio=FLT
Minimum acceptable axis ratio for the selected stars.
In other words, only stars with axis ratio between @option{--minaxisratio} to
1.0 will be selected.
+Default value is @option{--minaxisratio=0.9}.
Recall that the axis ratio is only used when you also give a segmented image
with @option{--segmented}.
@item -t
@@ -25225,14 +25230,6 @@ To do that, a central region is considered in order to
compute the values of the
Once it has been identified, that pixels are not masked.
With this option, it is possible to control the size of the central region for
computing the central object label (on the segmentation image).
-@item -R FLT
-@itemx --rmax=FLT
-Maximum radius (in pixels) for computing the radial profile.
-By default, the radial profile will be computed up to a radial distance equal
to the outer radius of the normalization region (@option{--normradii}).
-If the user wants to compute larger radial profile it is possible with this
option.
-Situations in which this option is necessary are those in which the user wants
to check individual radial profiles to ensure everything is fine.
-To be able to check the radial profile use the option @option{--keeptmp} to
not delete temporary files, see below.
-
@item -N STR
@itemx --normop=STR
The operator for measuring the values within the ring defined by the option
@option{--normradii}.
@@ -25277,7 +25274,7 @@ For example, to check that the intermediate images have
the desired center, they
@itemx --output=STR
Filename of stamp image.
By default the name of the stamp will be a combination of the input image
name, the name of the script, and the coordinates of the center.
-For example, if the input image is named image.fits and the center is
@option{--center=33,78}, then the output name wil be:
image_psfcreatemakestamp_33_78.fits
+For example, if the input image is named image.fits and the center is
@option{--center=33,78}, then the output name wil be: image_stamp_33_78.fits
The main reason of setting this name is to have an unique name for each stamp
by default.
@end table
@@ -25303,22 +25300,22 @@ Examples:
## Multiply inner.fits by 3 and put it in the center of
## outer.fits. The core goes up to a radius of 25 pixels.
$ astscript-psf-unite outer.fits \
- --core=inner.fits --fluxfactor=3 \
+ --core=inner.fits --scale=3 \
--radius=25 --output=joined.fits
## Same example than the above, but considering an
## ellipse (instead of a circle).
$ astscript-psf-unite outer.fits \
- --core=inner.fits --fluxfactor=3 \
+ --core=inner.fits --scale=3 \
--radius=25 --axisratio=0.5 \
--positionangle=40 --output=joined.fits
@end example
The junction is done by considering the input image as the outer part.
-The central part is specified by the option @option{--core} and it is
multiplied by the factor @option{--fluxfactor}.
-Then, the core image is cropped and appened to the outer image at a radius
specified by the option @option{--radius} (in pixels).
-The factor by which the core is multiplied has to be provided manually.
+The central part is specified by the option @option{--inner} and it is
multiplied by the factor @option{--scale}.
+Then, the inner image is cropped and appened to the outer image at a radius
specified by the option @option{--radius} (in pixels).
+The factor by which the inner part is multiplied has to be explicitly
provided, see below to know how to compute it.
Note that this script assumes that PSF is centered in both images.
More options are available with the goal of obtaining a good junction.
A full description of each option is given below.
@@ -25329,24 +25326,24 @@ A full description of each option is given below.
@itemx --hdu=STR
The HDU/extension of the input image to use.
-@item -c STR
-@itemx --core=STR
-Filename of the core PSF.
+@item -i STR
+@itemx --inner=STR
+Filename of the inner PSF.
This image is considered to be the central part of the PSF.
-It will be cropped at the radius specified by the option @option{--radius},
and multiplied by the factor specified by @option{--fluxfactor}.
+It will be cropped at the radius specified by the option @option{--radius},
and multiplied by the factor specified by @option{--scale}.
After that, it will be appened to the outer part (input image).
-@item -C STR
-@itemx --corehdu=STR
-The HDU/extension of the core PSF (option @option{--core}).
+@item -I STR
+@itemx --innerhdu=STR
+The HDU/extension of the inner PSF (option @option{--inner}).
@item -r FLT
@itemx --radius=FLT
Radius (in pixels) at which the junction of the images is done.
@item -f FLT
-@itemx --fluxfactor=FLT
-Factor by which the core (@option{--core}) is multiplied.
+@itemx --scale=FLT
+Factor by which the inner part (@option{--inner}) is multiplied.
This factor is necessary to put the two different parts of the PSF at the same
flux level.
A convenient way of obtaining this value is by using the script
@file{astscript-model-scale-factor}, see @ref{Invoking
astscript-psf-scale-factor}.
@@ -25381,7 +25378,9 @@ This option is useful for debugging.
@node Invoking astscript-psf-scale-factor, Invoking astscript-psf-subtract,
Invoking astscript-psf-unite, PSF construction and subtraction
@subsection Invoking astscript-psf-scale-factor
-This installed script will find the multiplication (scale) factor to multiply
with a PSF image in order to scale it to a star within another image (the
coordinates of the star in the different image should be given).
+This installed script will compute the multiplicative factor (scale) that is
necessary to match the PSF to a given star.
+The match in flux is done within a ring of pixels.
+With this script, it is also possible to compute the scale factor by which it
is necessary to multiply the inner part of the PSF when uniting two parts of
the PSF.
This script can be used with the following general template:
@@ -25393,25 +25392,25 @@ $ astscript-psf-scale-factor [OPTION...] FITS-file
Examples:
@example
-## Compute the flux factor for the object at (x,y)=(53,69) for
+## Compute the scale factor for the object at (x,y)=(53,69) for
## the PSF (psf.fits). Compute it in the ring 20-30 pixels.
$ astscript-psf-scale-factor image.fits --mode=img \
--center=53,69 --normradii=20,30 --psf=psf.fits
## Iterate over a catalog with positions of stars that are
-## in the the input image to compute their flux factors.
+## in the the input image to compute their scale factors.
$ asttable catalog.fits | while read -r ra dec mag; do \
astscript-psf-scale-factor image.fits \
--mode=wcs \
--psf=psf.fits \
--center=$ra,$dec \
- --normradii=20,30 > fluxfactor-"$ra"-"$dec".txt; done
+ --normradii=20,30 > scale-"$ra"-"$dec".txt; done
@end example
-The input should be an image containing the star that you want to scale with
the PSF.
+The input should be an image containing the star that you want to match in
flux with the PSF.
The output will be a single number that is printed on the command-line.
-That number is the multiplication factor to multiply with the PSF image
(@option{--psf}) to scale it with the given star (which is located in
@option{--center} of the input image).
+That number is the multiplicative factor to scale the PSF image
(@option{--psf}) to match in flux with the given star (which is located in
@option{--center} of the input image).
The scale factor will be calculated within the ring of pixels specified by the
option @option{--normradii}.
All the pixels within this ring will be separated from both the PSF and input
images.
@@ -25419,7 +25418,7 @@ For the input image, around the selected coordinate;
while masking all other sou
The finally selected pixels of the input image will then be divided by those
of the PSF image.
This gives us an image containing one scale factor per pixel.
The finally reported value is the sigma-clipped median of all the scale
factors in the finally-used pixels.
-To fully understand the process, we recommend running this script once with
@option{--keeptmp} and inspect the files inside of it.
+To fully understand the process, we recommend running this script once with
@option{--keeptmp} and inspect the files inside of the temporary directory.
The most common use-cases of this scale factor are:
@enumerate
@@ -25461,7 +25460,7 @@ This option thus accepts only two values: @option{img}
or @option{wcs}.
@item -n INT,INT
@itemx --normradii=INT,INT
-Inner and outer radii (in units of pixels) around the central position in
which the flux factor is computed.
+Inner and outer radii (in units of pixels) around the central position in
which the scale factor is computed.
The option takes two values separated by a comma (@key{,}).
The first value is the inner radius, the second is the outer radius.
These two radius define a ring of pixels around the center that is used for
obtaining the flux factor value.
@@ -25518,7 +25517,7 @@ For example, to check that the intermediate images have
the desired center, they
@node Invoking astscript-psf-subtract, , Invoking astscript-psf-scale-factor,
PSF construction and subtraction
@subsection Invoking astscript-psf-subtract
-This installed script will put the provided PSF into a given position of the
sky within the input image, and then it will subtract it.
+This installed script will put the provided PSF into a given position on the
sky within the input image, and then it will subtract it.
It is aimed to model and subtract the scattered light field of an input image.
It is also possible to obtain the modeled star with the PSF (and not make the
subtraction of it from the original image).
@@ -25544,7 +25543,7 @@ $ astscript-psf-subtract image.fits \
## Iterate over a catalog with positions of stars that are
## in the the input image. Use WCS coordinates.
$ asttable catalog.fits | while read -r ra dec mag; do
- scale=$(cat fluxfactor-"$ra"_"$dec".txt)
+ scale=$(cat scale-"$ra"_"$dec".txt)
astscript-psf-subtract image.fits \
--mode=wcs \
--psf=psf.fits \
@@ -25558,11 +25557,11 @@ The result is the same image but with the star
subtracted (modeled by the PSF).
The modeling of the star is done with the PSF image specified with the option
@option{--psf}, and flux-scaled with the option @option{--scale} at the
position defined by @option{--center}.
Instead of obtaining the PSF-subtracted image, it is also possible to obtain
the modeled star by the PSF.
To to that, use the option @option{--modelonly}.
-With this option, the output will an image with the same size as the original
one with the PSF situated in the center and flux-scaled.
+With this option, the output will be an image with the same size as the
original one with the PSF situated in the star coordinates and flux-scaled.
In this case, the region not covered by the PSF are set to zero values.
Note that this script works over individual objects.
-As a consequence, to generate a scattered light field of many stars it is
necessary to make multiple calls and then combine all the individual modeled
stars.
+As a consequence, to generate a scattered light field of many stars, it is
necessary to make multiple calls.
A full description of each option is given below.
@table @option