[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[gnuastro-commits] master 21cd71bf 39/39: astscript-zeropoint: edits for
|
From: |
Mohammad Akhlaghi |
|
Subject: |
[gnuastro-commits] master 21cd71bf 39/39: astscript-zeropoint: edits for merging into master branch |
|
Date: |
Wed, 19 Apr 2023 12:18:28 -0400 (EDT) |
branch: master
commit 21cd71bf23f49e44e94c41412f2e526ca360857f
Author: Mohammad Akhlaghi <mohammad@akhlaghi.org>
Commit: Mohammad Akhlaghi <mohammad@akhlaghi.org>
astscript-zeropoint: edits for merging into master branch
Until now, Sepideh had lead a team effort (including many people) in a
separate branch to add a new zero point estimation script within Gnuastro.
With this commit, that branch has been rebased over the 'master' branch and
is being merged into the 'master' branch for general use. The following
edits and changes were made in the script, Makefile and documentation:
- The recipes to install this script were added to
'bin/scripts/Makefile.am'.
- The "Acknowledgement" section of the output of this script (and all the
other scripts) are now in one line (to fit any terminal width) and not
adjusted into short lines (of 80 characters). This makes them similar to
the same section of the Gnuastro programs.
- In the output of '--help', the options were grouped based on their
operation to be more clear for a new user.
- The following options were added:
--starcat: to avoid using Gaia when not possible or not necessary.
--starcatra: to specify the RA column in '--starcat'.
--starcatdec: to specify the Dec column in '--starcat'.
- The following options were renamed:
--refcatra: replaces '--racolumn' which was not clear if it is for the
reference catalog or the stars catalog.
--refcatdec: replaces '--deccolumn', similar to '--refcatra'.
--refcatmag: replaces '--magcolumn', similar to '--refcatra'.
--refimgszp: replaces '--referencezp' to be more clear that it only
applies to reference image mode.
- The script now finds the number of threads available on the host
operating system and will run its internal Makefile on that many threads
(until now, when '--numthreads' wasn't given, it would only run on a
single thread).
---
.mailmap | 3 +-
NEWS | 12 +
bin/script/Makefile.am | 16 +-
bin/script/psf-scale-factor.in | 10 +-
bin/script/psf-select-stars.in | 10 +-
bin/script/psf-stamp.in | 10 +-
bin/script/psf-subtract.in | 10 +-
bin/script/psf-unite.in | 10 +-
bin/script/zeropoint.in | 427 +++++++++++++---------
bin/script/zeropoint.mk | 158 ++++----
doc/gnuastro.texi | 812 ++++++++++++++++++++++++++++-------------
11 files changed, 934 insertions(+), 544 deletions(-)
diff --git a/.mailmap b/.mailmap
index a38e3396..f49a7780 100644
--- a/.mailmap
+++ b/.mailmap
@@ -1,6 +1,6 @@
# Map different emails to people in Git.
#
-# Copyright (C) 2015-2022 Free Software Foundation, Inc.
+# Copyright (C) 2015-2023 Free Software Foundation, Inc.
#
# Copying and distribution of this file, with or without modification,
# are permitted in any medium without royalty provided the copyright
@@ -9,6 +9,7 @@
Boud Roukema <boud@cosmo.torun.pl>
Elham Saremi <saremi.elham@yahoo.com>
+Zohreh Ghaffari <zoh.ghaffari@gmail.com>
Mohammad Akhlaghi <mohammad@akhlaghi.org>
Carlos Morales-Socorro <cmorsoc@gmail.com>
<mohammad@akhlaghi.org> <akhlaghi@gnu.org>
diff --git a/NEWS b/NEWS
index 9cbc6348..2e7be7a5 100644
--- a/NEWS
+++ b/NEWS
@@ -8,6 +8,18 @@ See the end of the file for license conditions.
** New features
+ New program:
+ - astscript-zeropoint: this script is used for calibrating the pixel
+ values in one image (finding its "zero point") based on a reference
+ catalog or (any number of) reference image(s). The script allows for
+ checking many apertures in the same command to let you choose the
+ best; and will operate in parallel where necessary. The documentation
+ of this script contains two tutorials on how to optimally use it and
+ interpret its results; please read and run them once before using it.
+ This script was written as a team effort lead by Sepideh Eskandarlou
+ and including (in alphabetical order): Elham Saremi, Giulia Golini,
+ Raul Infante-Sainz, Samane Raji, Zahra Sharbaf, Zohreh Ghaffari.
+
Arithmetic
--writeall: Write all datasets on the stack as separate HDUs in the
output; this is useful in debugging incomplete Arithmetic commands.
diff --git a/bin/script/Makefile.am b/bin/script/Makefile.am
index 1f3425bf..ca601af7 100644
--- a/bin/script/Makefile.am
+++ b/bin/script/Makefile.am
@@ -22,8 +22,9 @@
-# Desktop files (for graphic environments)
-pkgdata_DATA = astscript-fits-view.desktop
+# Data files (necessary for various components like desktop files for GUIs
+# or Makefiles that are called within scripts).
+pkgdata_DATA = astscript-fits-view.desktop zeropoint.mk
astscript-fits-view.desktop: $(srcdir)/fits-view.desktop.in Makefile
sed -e 's|@PREFIX[@]|$(exec_prefix)|g' \
$(srcdir)/fits-view.desktop.in > $@
@@ -39,6 +40,7 @@ astscript-fits-view.desktop: $(srcdir)/fits-view.desktop.in
Makefile
bin_SCRIPTS = astscript-fits-view \
astscript-psf-unite \
astscript-psf-stamp \
+ astscript-zeropoint \
astscript-ds9-region \
astscript-psf-subtract \
astscript-sort-by-night \
@@ -49,6 +51,8 @@ bin_SCRIPTS = astscript-fits-view \
EXTRA_DIST = fits-view.in \
psf-unite.in \
psf-stamp.in \
+ zeropoint.in \
+ zeropoint.mk \
ds9-region.in \
psf-subtract.in \
sort-by-night.in \
@@ -65,13 +69,15 @@ CLEANFILES = $(bin_SCRIPTS) \
## Command to do basic substitutions (anything surrounded by an '@').
-do_subst = sed -e 's,[@]VERSION[@],$(VERSION),g' \
+do_subst = sed -e 's,[@]PREFIX[@],$(exec_prefix),g' \
+ -e 's,[@]VERSION[@],$(VERSION),g' \
-e 's,[@]SCRIPT_NAME[@],$@,g'
+
## Rules to install the scripts.
astscript-fits-view: fits-view.in Makefile
$(do_subst) < $(srcdir)/fits-view.in > $@
@@ -81,6 +87,10 @@ astscript-ds9-region: ds9-region.in Makefile
$(do_subst) < $(srcdir)/ds9-region.in > $@
chmod +x $@
+astscript-zeropoint: zeropoint.in Makefile
+ $(do_subst) < $(srcdir)/zeropoint.in > $@
+ chmod +x $@
+
astscript-radial-profile: radial-profile.in Makefile
$(do_subst) < $(srcdir)/radial-profile.in > $@
chmod +x $@
diff --git a/bin/script/psf-scale-factor.in b/bin/script/psf-scale-factor.in
index f2e40b66..ccef6dce 100644
--- a/bin/script/psf-scale-factor.in
+++ b/bin/script/psf-scale-factor.in
@@ -192,15 +192,7 @@ First paper introducing Gnuastro
Acknowledgement
---------------
-This work was partly done using GNU Astronomy Utilities (Gnuastro,
-ascl.net/1801.009) version $version. Work on Gnuastro has been funded by
-the Japanese Ministry of Education, Culture, Sports, Science, and
-Technology (MEXT) scholarship and its Grant-in-Aid for Scientific Research
-(21244012, 24253003), the European Research Council (ERC) advanced grant
-339659-MUSICOS, the Spanish Ministry of Economy and Competitiveness
-(MINECO, grant number AYA2016-76219-P) and the NextGenerationEU grant
-through the Recovery and Resilience Facility project
-ICTS-MRR-2021-03-CEFCA.
+This work was partly done using GNU Astronomy Utilities (Gnuastro,
ascl.net/1801.009) version $version. Work on Gnuastro has been funded by the
Japanese Ministry of Education, Culture, Sports, Science, and Technology (MEXT)
scholarship and its Grant-in-Aid for Scientific Research (21244012, 24253003),
the European Research Council (ERC) advanced grant 339659-MUSICOS, the Spanish
Ministry of Economy and Competitiveness (MINECO, grant number AYA2016-76219-P)
and the NextGenerationEU grant [...]
,
{|'--.
{{\ \ $empty
diff --git a/bin/script/psf-select-stars.in b/bin/script/psf-select-stars.in
index c9491987..0ddd1c7f 100644
--- a/bin/script/psf-select-stars.in
+++ b/bin/script/psf-select-stars.in
@@ -207,15 +207,7 @@ First paper introducing Gnuastro
Acknowledgement
---------------
-This work was partly done using GNU Astronomy Utilities (Gnuastro,
-ascl.net/1801.009) version $version. Work on Gnuastro has been funded by
-the Japanese Ministry of Education, Culture, Sports, Science, and
-Technology (MEXT) scholarship and its Grant-in-Aid for Scientific Research
-(21244012, 24253003), the European Research Council (ERC) advanced grant
-339659-MUSICOS, the Spanish Ministry of Economy and Competitiveness
-(MINECO, grant number AYA2016-76219-P) and the NextGenerationEU grant
-through the Recovery and Resilience Facility project
-ICTS-MRR-2021-03-CEFCA.
+This work was partly done using GNU Astronomy Utilities (Gnuastro,
ascl.net/1801.009) version $version. Work on Gnuastro has been funded by the
Japanese Ministry of Education, Culture, Sports, Science, and Technology (MEXT)
scholarship and its Grant-in-Aid for Scientific Research (21244012, 24253003),
the European Research Council (ERC) advanced grant 339659-MUSICOS, the Spanish
Ministry of Economy and Competitiveness (MINECO, grant number AYA2016-76219-P)
and the NextGenerationEU grant [...]
,
{|'--.
{{\ \ $empty
diff --git a/bin/script/psf-stamp.in b/bin/script/psf-stamp.in
index a2e629ba..65c041ff 100644
--- a/bin/script/psf-stamp.in
+++ b/bin/script/psf-stamp.in
@@ -205,15 +205,7 @@ First paper introducing Gnuastro
Acknowledgement
---------------
-This work was partly done using GNU Astronomy Utilities (Gnuastro,
-ascl.net/1801.009) version $version. Work on Gnuastro has been funded by
-the Japanese Ministry of Education, Culture, Sports, Science, and
-Technology (MEXT) scholarship and its Grant-in-Aid for Scientific Research
-(21244012, 24253003), the European Research Council (ERC) advanced grant
-339659-MUSICOS, the Spanish Ministry of Economy and Competitiveness
-(MINECO, grant number AYA2016-76219-P) and the NextGenerationEU grant
-through the Recovery and Resilience Facility project
-ICTS-MRR-2021-03-CEFCA.
+This work was partly done using GNU Astronomy Utilities (Gnuastro,
ascl.net/1801.009) version $version. Work on Gnuastro has been funded by the
Japanese Ministry of Education, Culture, Sports, Science, and Technology (MEXT)
scholarship and its Grant-in-Aid for Scientific Research (21244012, 24253003),
the European Research Council (ERC) advanced grant 339659-MUSICOS, the Spanish
Ministry of Economy and Competitiveness (MINECO, grant number AYA2016-76219-P)
and the NextGenerationEU grant [...]
,
{|'--.
{{\ \ $empty
diff --git a/bin/script/psf-subtract.in b/bin/script/psf-subtract.in
index eb3ee4f7..03f47dc9 100644
--- a/bin/script/psf-subtract.in
+++ b/bin/script/psf-subtract.in
@@ -184,15 +184,7 @@ First paper introducing Gnuastro
Acknowledgement
---------------
-This work was partly done using GNU Astronomy Utilities (Gnuastro,
-ascl.net/1801.009) version $version. Work on Gnuastro has been funded by
-the Japanese Ministry of Education, Culture, Sports, Science, and
-Technology (MEXT) scholarship and its Grant-in-Aid for Scientific Research
-(21244012, 24253003), the European Research Council (ERC) advanced grant
-339659-MUSICOS, the Spanish Ministry of Economy and Competitiveness
-(MINECO, grant number AYA2016-76219-P) and the NextGenerationEU grant
-through the Recovery and Resilience Facility project
-ICTS-MRR-2021-03-CEFCA.
+This work was partly done using GNU Astronomy Utilities (Gnuastro,
ascl.net/1801.009) version $version. Work on Gnuastro has been funded by the
Japanese Ministry of Education, Culture, Sports, Science, and Technology (MEXT)
scholarship and its Grant-in-Aid for Scientific Research (21244012, 24253003),
the European Research Council (ERC) advanced grant 339659-MUSICOS, the Spanish
Ministry of Economy and Competitiveness (MINECO, grant number AYA2016-76219-P)
and the NextGenerationEU grant [...]
,
{|'--.
{{\ \ $empty
diff --git a/bin/script/psf-unite.in b/bin/script/psf-unite.in
index c2726e89..eaa7bc21 100644
--- a/bin/script/psf-unite.in
+++ b/bin/script/psf-unite.in
@@ -186,15 +186,7 @@ First paper introducing Gnuastro
Acknowledgement
---------------
-This work was partly done using GNU Astronomy Utilities (Gnuastro,
-ascl.net/1801.009) version $version. Work on Gnuastro has been funded by
-the Japanese Ministry of Education, Culture, Sports, Science, and
-Technology (MEXT) scholarship and its Grant-in-Aid for Scientific Research
-(21244012, 24253003), the European Research Council (ERC) advanced grant
-339659-MUSICOS, the Spanish Ministry of Economy and Competitiveness
-(MINECO, grant number AYA2016-76219-P) and the NextGenerationEU grant
-through the Recovery and Resilience Facility project
-ICTS-MRR-2021-03-CEFCA.
+This work was partly done using GNU Astronomy Utilities (Gnuastro,
ascl.net/1801.009) version $version. Work on Gnuastro has been funded by the
Japanese Ministry of Education, Culture, Sports, Science, and Technology (MEXT)
scholarship and its Grant-in-Aid for Scientific Research (21244012, 24253003),
the European Research Council (ERC) advanced grant 339659-MUSICOS, the Spanish
Ministry of Economy and Competitiveness (MINECO, grant number AYA2016-76219-P)
and the NextGenerationEU grant [...]
,
{|'--.
{{\ \ $empty
diff --git a/bin/script/zeropoint.in b/bin/script/zeropoint.in
index ed08169f..06b3d601 100644
--- a/bin/script/zeropoint.in
+++ b/bin/script/zeropoint.in
@@ -7,16 +7,16 @@
# computation of the zero point. These parameters are saved into a
# configuration Makefile. Finally, the Makefile is executed at the end of
# this script. The reason of using Make is to parallelize the computation
-# of the zero point so it obtained faster than using a simpler script.
+# of the zero point so it obtained faster than using a script.
#
# Run with '--help' for more information.
#
-# Original author:
-# Sepideh Eskandarlou <sepideh.eskandarlou@gmail.com>
-# Contributing author:
-# Mohammad Akhlaghi <mohammad@akhlaghi.org>
-# Raul Infante-Sainz <infantesainz@gmail.com>
-# Copyright (C) 2020-2023 Free Software Foundation, Inc.
+# Current maintainer:
+# 2022-2023 Sepideh Eskandarlou <sepideh.eskandarlou@gmail.com>
+# Contributing authors:
+# 2022-2023 Mohammad Akhlaghi <mohammad@akhlaghi.org>
+# 2022-2023 Raul Infante-Sainz <infantesainz@gmail.com>
+# Copyright (C) 2022-2023 Free Software Foundation, Inc.
#
# Gnuastro is free software: you can redistribute it and/or modify it under
# the terms of the GNU General Public License as published by the Free
@@ -46,26 +46,30 @@ export LC_NUMERIC=C
# Default parameter's values
hdu=1
-jobs=1
quiet=""
output=""
tmpdir=""
refcat=""
+refimgs=""
+starcat=""
keeptmp=""
keepzpap=""
-refimgs=""
-aperarcsec=""
+refimgszp=""
refcathdu=""
-racolumn="RA"
-referencezp=""
+numthreads=0
+starcathdu=""
+aperarcsec=""
+refcatra="RA"
refimgshdu=""
-deccolumn="DEC"
+starcatra="RA"
+refcatdec="DEC"
matchradius=0.2
+starcatdec="DEC"
magnituderange=""
-magcolumn="MAGNITUDE"
-version=@VERSION@magmg
+version=@VERSION@
+refcatmag="MAGNITUDE"
scriptname=@SCRIPT_NAME@
-
+installdir=@PREFIX@/share/gnuastro
@@ -86,37 +90,46 @@ print_help() {
cat <<EOF
Usage: $scriptname [OPTIONS] image.fits
-Calculate the Zeropoint of the image based on the reference images or
+Calculate the Zeropoint of the image based on a reference images or
catalog.
$scriptname options:
- Input:
- -h, --hdu=STR/INT HDU/Extension name or number of the input file.
- -c, --refcat=STR Reference catalog considered as the reference.
- -C, --refcathdu=STR/INT HDU/Extension name of number of the ref.
catalog.
- -r, --racolumn=STR Right Ascension (R.A.) column name of the ref.
catalog.
- -d, --deccolumn=STR Declination (Dec) column name of the ref.
catalog.
- -m, --magcolumn=STR Magnitude column name of the ref. catalog.
+ Input(s):
+ -h, --hdu=STR/INT HDU/Extension name or number of input.
+ -S, --starcat=STR Catalog with positions for aperture photomery.
+ --starcathdu=STR/INT HDU of table in '--starcat'.
+ --starcatra=STR/INT Column in '--starcat' that contains RA.
+ --starcatdec=STR/INT Column in '--starcat' that contains DEC.
+
+ Output:
+ -o, --output Output file name.
+ -t, --tmpdir Directory to keep temporary files.
+ -k, --keeptmp Keep temporal/auxiliar files.
+ -K, --keepzpap Keep each aperture's zp in a different HDU.
+
+ General settings
+ -a, --aperarcsec=FLT[,FLT] Aperture radius (in arc-seconds) for photometry.
-M, --magnituderange=FLT,FLT Range of the magnitude to be considered.
- -s, --matchradius=FLT Matching distance with the ref. catalog.
- -R, --refimgs=STR[,STR] Image(s) considered as the reference(s).
- -z, --referencezp=FLT[,FLT] Zero point(s) of the reference image(s).
- -H, --refimgsdu=STR/INT HDU/Extension name(s) or number(s) the ref. images.
- -a, --aperarcsec=FLT[,FLT] Aperture radius (in arco seconds) for
photometry.
- -K, --keepzpap Keep the zero point from each aperture in a
different HDU.
- -j, --jobs=INT Number of threads; maximum jobs with no arg.
+ Reference catalog mode
+ -c, --refcat=STR Reference catalog file name.
+ -C, --refcathdu=STR/INT Reference catalog HDU name of number.
+ -r, --refcatra=STR Reference catalog Right Ascension (R.A.) column.
+ -d, --refcatdec=STR Reference catalog Declination (Dec) column.
+ -m, --refcatmag=STR Reference catalog Magnitude column.
+ -s, --matchradius=FLT Radius (arcsec) to match stars and ref. catalog.
- Output:
- -o, --output Output with zero point estimation and best aperture.
- -t, --tmpdir Directory to keep temporary files.
- -k, --keeptmp Keep temporal/auxiliar files.
+ Reference image mode
+ -R, --refimgs=STR[,STR] Reference image name(s) with known zeropoint.
+ -H, --refimgshdu=STR/INT Reference image HDU name(s) or number (s).
+ -z, --refimgszp=FLT[,FLT] Zero point(s) of the reference image(s).
Operating mode:
- -h, --help Print this help.
- --cite BibTeX citation for this program.
- -q, --quiet Don't print any extra information in stdout.
- -V, --version Print program version.
+ -h, --help Print this help.
+ --cite BibTeX citation for this program.
+ -q, --quiet Don't print any extra information in stdout.
+ -V, --version Print program version.
+ -N, --numthreads=INT Number of threads; maximum if not given.
Mandatory or optional arguments to long options are also mandatory or optional
for any corresponfing short options.
@@ -135,12 +148,12 @@ EOF
print_version() {
cat <<EOF
$scriptname (GNU Astronomy Utilities) $version
-Copyright (C) 2020-2023 Free Software Foundation, Inc.
+Copyright (C) 2022-2023 Free Software Foundation, Inc.
License GPLv3+: GNU General public license version 3 or later.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
-Written/developed by Sepideh Eskandarlou.
+Written/developed by Sepideh Eskandarlou et al.
EOF
}
@@ -179,15 +192,8 @@ First paper introducing Gnuastro
Acknowledgement
---------------
-This work was partly done using GNU Astronomy Utilities (Gnuastro,
-ascl.net/1801.009) version $version. Work on Gnuastro has been funded by
-the Japanese Ministry of Education, Culture, Sports, Science, and
-Technology (MEXT) scholarship and its Grant-in-Aid for Scientific Research
-(21244012, 24253003), the European Research Council (ERC) advanced grant
-339659-MUSICOS, the Spanish Ministry of Economy and Competitiveness
-(MINECO, grant number AYA2016-76219-P) and the NextGenerationEU grant
-through the Recovery and Resilience Facility project
-ICTS-MRR-2021-03-CEFCA.
+
+This work was partly done using GNU Astronomy Utilities (Gnuastro,
ascl.net/1801.009) version $version. Work on Gnuastro has been funded by the
Japanese Ministry of Education, Culture, Sports, Science, and Technology (MEXT)
scholarship and its Grant-in-Aid for Scientific Research (21244012, 24253003),
the European Research Council (ERC) advanced grant 339659-MUSICOS, the Spanish
Ministry of Economy and Competitiveness (MINECO, grant number AYA2016-76219-P)
and the NextGenerationEU grant [...]
,
{|'--.
{{\ \ $empty
@@ -228,6 +234,7 @@ EOF
+
# Separate command-line arguments from options and put the option values
# into the respective variables.
#
@@ -257,78 +264,85 @@ EOF
inputs=""
while [ $# -gt 0 ]
do
- case "$1" in
- # Input parameters.
- -h|--hdu) hdu="$2";
check_v "$1" "$hdu"; shift;shift;;
- -h=*|--hdu=*) hdu="${1#*=}";
check_v "$1" "$hdu"; shift;;
- -h*) hdu=$(echo "$1" | sed -e's/-h//');
check_v "$1" "$hdu"; shift;;
- -c|--refcat) refcat="$2";
check_v "$1" "$refcat"; shift;shift;;
- -c=*|--refcat=*) refcat="${1#*=}";
check_v "$1" "$refcat"; shift;;
- -c*) refcat=$(echo "$1" | sed -e's/-c//');
check_v "$1" "$refcat"; shift;;
- -C|--refcathdu) refcathdu="$2";
check_v "$1" "$refcathdu"; shift;shift;;
- -C=*|--refcathdu=*) refcathdu="${1#*=}";
check_v "$1" "$refcathdu"; shift;;
- -C*) refcathdu=$(echo "$1" | sed -e's/-C//');
check_v "$1" "$refcathdu"; shift;;
- -r|--racolumn) racolumn="$2";
check_v "$1" "$racolumn"; shift;shift;;
- -r=*|--racolumn=*) racolumn="${1#*=}";
check_v "$1" "$racolumn"; shift;;
- -r*) racolumn=$(echo "$1" | sed -e's/-r//');
check_v "$1" "$racolumn"; shift;;
- -d|--deccolumn) deccolumn="$2";
check_v "$1" "$deccolumn"; shift;shift;;
- -d=*|--deccolumn=*) deccolumn="${1#*=}";
check_v "$1" "$deccolumn"; shift;;
- -d*) deccolumn=$(echo "$1" | sed -e's/-d//');
check_v "$1" "$deccolumn"; shift;;
- -m|--magcolumn) magcolumn="$2";
check_v "$1" "$magcolumn"; shift;shift;;
- -m=*|--magcolumn=*) magcolumn="${1#*=}";
check_v "$1" "$magcolumn"; shift;;
- -m*) magcolumn=$(echo "$1" | sed -e's/-m//');
check_v "$1" "$magcolumn"; shift;;
- -s|--matchradius) matchradius="$2";
check_v "$1" "$matchradius"; shift;shift;;
- -s=*|--matchradius=*) matchradius="${1#*=}";
check_v "$1" "$matchradius"; shift;;
- -s*) matchradius=$(echo "$1" | sed -e's/-s//');
check_v "$1" "$matchradius"; shift;;
-
- -M|--magnituderange) magnituderange="$2";
check_v "$1" "$magnituderange"; shift;shift;;
- -M=*|--magnituderange=*) magnituderange="${1#*=}";
check_v "$1" "$magnituderange"; shift;;
- -M*) magnituderange=$(echo "$1" | sed -e's/-M//');
check_v "$1" "$magnituderange"; shift;;
- -R|--refimgs) refimgs="$2";
check_v "$1" "$refimgs"; shift;shift;;
- -R=*|--refimgs=*) refimgs="${1#*=}";
check_v "$1" "$refimgs"; shift;;
- -R*) refimgs=$(echo "$1" | sed -e's/-R//');
check_v "$1" "$refimgs"; shift;;
- -z|--referencezp) referencezp="$2";
check_v "$1" "$referencezp"; shift;shift;;
- -z=*|--referencezp=*) referencezp="${1#*=}";
check_v "$1" "$referencezp"; shift;;
- -z*) referencezp=$(echo "$1" | sed -e's/-z//');
check_v "$1" "$referencezp"; shift;;
- -H|--refimgshdu) refimgshdu="$2";
check_v "$1" "$refimgshdu"; shift;shift;;
- -H=*|--refimgsdu=*) refimgshdu="${1#*=}";
check_v "$1" "$refimgshdu"; shift;;
- -H*) refimgshdu=$(echo "$1" | sed -e's/-H//');
check_v "$1" "$refimgshdu"; shift;;
- -a|--aperarcsec) aperarcsec="$2";
check_v "$1" "$aperarcsec"; shift;shift;;
- -a=*|--aperarcsec=*) aperarcsec="${1#*=}";
check_v "$1" "$aperarcsec"; shift;;
- -a*) aperarcsec=$(echo "$1" | sed -e's/-a//');
check_v "$1" "$aperarcsec"; shift;;
- -j|--jobs) jobs="$2";
check_v "$1" "$jobs"; shift;shift;;
- -j=*|--jobs=*) jobs="${1#*=}";
check_v "$1" "$jobs"; shift;;
- -j*) jobs=$(echo "$1" | sed -e's/-j//');
check_v "$1" "$jobs"; shift;;
- -K|--keepzpap) keepzpap=1; shift;;
- -K*|--keepzpap=*) on_off_option_error --keepzpap -K;;
-
-# Output parameters
- -k|--keeptmp) keeptmp=1; shift;;
- -k*|--keeptmp=*) on_off_option_error --keeptmp -k;;
- -t|--tmpdir) tmpdir="$2";
check_v "$1" "$tmpdir"; shift;shift;;
- -t=*|--tmpdir=*) tmpdir="${1#*=}";
check_v "$1" "$tmpdir"; shift;;
- -t*) tmpdir=$(echo "$1" | sed -e's/-t//');
check_v "$1" "$tmpdir"; shift;;
- -o|--output) output="$2";
check_v "$1" "$output"; shift;shift;;
- -o=*|--output=*) output="${1#*=}";
check_v "$1" "$output"; shift;;
- -o*) output=$(echo "$1" | sed -e's/-o//');
check_v "$1" "$output"; shift;;
-
- # Non-operating options.
- -q|--quiet) quiet=" -q"; shift;;
- -q*|--quiet=*) on_off_option_error --quiet -q;;
- -?|--help) print_help; exit 0;;
- -'?'*|--help=*) on_off_option_error --help -?;;
- -V|--version) print_version; exit 0;;
- -V*|--version=*) on_off_option_error --version -V;;
- --cite) print_citation; exit 0;;
- --cite=*) on_off_option_error --cite;;
-
- # Unrecognized option:
- -*) echo "$scriptname: unknown option '$1'"; exit 1;;
-
- # Not an option (not starting with a `-'): assumed to be input FITS
- # file name.
- *) if [ x"$inputs" = x ]; then inputs="$1"; else inputs="$inputs $1";
fi; shift;;
- esac
+ case "$1" in
+
+ # Input parameters.
+ -h|--hdu) hdu="$2";
check_v "$1" "$hdu"; shift;shift;;
+ -h=*|--hdu=*) hdu="${1#*=}";
check_v "$1" "$hdu"; shift;;
+ -h*) hdu=$(echo "$1" | sed -e's/-h//');
check_v "$1" "$hdu"; shift;;
+ -s|--starcat) starcat="$2";
check_v "$1" "$starcat"; shift;shift;;
+ -s=*|--starcat=*) starcat="${1#*=}";
check_v "$1" "$starcat"; shift;;
+ -s*) starcat=$(echo "$1" | sed -e's/-c//');
check_v "$1" "$starcat"; shift;;
+ --starcathdu) starcathdu="$2";
check_v "$1" "$starcathdu"; shift;shift;;
+ --starcathdu=*) starcathdu="${1#*=}";
check_v "$1" "$starcathdu"; shift;;
+ -c|--refcat) refcat="$2";
check_v "$1" "$refcat"; shift;shift;;
+ -c=*|--refcat=*) refcat="${1#*=}";
check_v "$1" "$refcat"; shift;;
+ -c*) refcat=$(echo "$1" | sed -e's/-c//');
check_v "$1" "$refcat"; shift;;
+ -C|--refcathdu) refcathdu="$2";
check_v "$1" "$refcathdu"; shift;shift;;
+ -C=*|--refcathdu=*) refcathdu="${1#*=}";
check_v "$1" "$refcathdu"; shift;;
+ -C*) refcathdu=$(echo "$1" | sed -e's/-C//');
check_v "$1" "$refcathdu"; shift;;
+ -r|--refcatra) refcatra="$2";
check_v "$1" "$refcatra"; shift;shift;;
+ -r=*|--refcatra=*) refcatra="${1#*=}";
check_v "$1" "$refcatra"; shift;;
+ -r*) refcatra=$(echo "$1" | sed -e's/-r//');
check_v "$1" "$refcatra"; shift;;
+ -d|--refcatdec) refcatdec="$2";
check_v "$1" "$refcatdec"; shift;shift;;
+ -d=*|--refcatdec=*) refcatdec="${1#*=}";
check_v "$1" "$refcatdec"; shift;;
+ -d*) refcatdec=$(echo "$1" | sed -e's/-d//');
check_v "$1" "$refcatdec"; shift;;
+ -m|--refcatmag) refcatmag="$2";
check_v "$1" "$refcatmag"; shift;shift;;
+ -m=*|--refcatmag=*) refcatmag="${1#*=}";
check_v "$1" "$refcatmag"; shift;;
+ -m*) refcatmag=$(echo "$1" | sed -e's/-m//');
check_v "$1" "$refcatmag"; shift;;
+ -R|--refimgs) refimgs="$2";
check_v "$1" "$refimgs"; shift;shift;;
+ -R=*|--refimgs=*) refimgs="${1#*=}";
check_v "$1" "$refimgs"; shift;;
+ -R*) refimgs=$(echo "$1" | sed -e's/-R//');
check_v "$1" "$refimgs"; shift;;
+ -H|--refimgshdu) refimgshdu="$2";
check_v "$1" "$refimgshdu"; shift;shift;;
+ -H=*|--refimgshdu=*) refimgshdu="${1#*=}";
check_v "$1" "$refimgshdu"; shift;;
+ -H*) refimgshdu=$(echo "$1" | sed -e's/-H//');
check_v "$1" "$refimgshdu"; shift;;
+
+ # Parameters.
+ -M|--magnituderange) magnituderange="$2";
check_v "$1" "$magnituderange"; shift;shift;;
+ -M=*|--magnituderange=*) magnituderange="${1#*=}";
check_v "$1" "$magnituderange"; shift;;
+ -M*) magnituderange=$(echo "$1" | sed -e's/-M//');
check_v "$1" "$magnituderange"; shift;;
+ -s|--matchradius) matchradius="$2";
check_v "$1" "$matchradius"; shift;shift;;
+ -s=*|--matchradius=*) matchradius="${1#*=}";
check_v "$1" "$matchradius"; shift;;
+ -s*) matchradius=$(echo "$1" | sed -e's/-s//');
check_v "$1" "$matchradius"; shift;;
+ -z|--refimgszp) refimgszp="$2";
check_v "$1" "$refimgszp"; shift;shift;;
+ -z=*|--refimgszp=*) refimgszp="${1#*=}";
check_v "$1" "$refimgszp"; shift;;
+ -z*) refimgszp=$(echo "$1" | sed -e's/-z//');
check_v "$1" "$refimgszp"; shift;;
+ -a|--aperarcsec) aperarcsec="$2";
check_v "$1" "$aperarcsec"; shift;shift;;
+ -a=*|--aperarcsec=*) aperarcsec="${1#*=}";
check_v "$1" "$aperarcsec"; shift;;
+ -a*) aperarcsec=$(echo "$1" | sed -e's/-a//');
check_v "$1" "$aperarcsec"; shift;;
+
+ # Output parameters
+ -k|--keeptmp) keeptmp=1; shift;;
+ -k*|--keeptmp=*) on_off_option_error --keeptmp -k;;
+ -t|--tmpdir) tmpdir="$2";
check_v "$1" "$tmpdir"; shift;shift;;
+ -t=*|--tmpdir=*) tmpdir="${1#*=}";
check_v "$1" "$tmpdir"; shift;;
+ -t*) tmpdir=$(echo "$1" | sed -e's/-t//');
check_v "$1" "$tmpdir"; shift;;
+ -o|--output) output="$2";
check_v "$1" "$output"; shift;shift;;
+ -o=*|--output=*) output="${1#*=}";
check_v "$1" "$output"; shift;;
+ -o*) output=$(echo "$1" | sed -e's/-o//');
check_v "$1" "$output"; shift;;
+ -K|--keepzpap) keepzpap=1; shift;;
+ -K*|--keepzpap=*) on_off_option_error --keepzpap -K;;
+
+ # Operating mode options.
+ -N|--numthreads) numthreads="$2";
check_v "$1" "$numthreads"; shift;shift;;
+ -N=*|--numthreads=*) numthreads="${1#*=}";
check_v "$1" "$numthreads"; shift;;
+ -N*) numthreads=$(echo "$1" | sed -e's/-j//');
check_v "$1" "$numthreads"; shift;;
+ -q|--quiet) quiet=" -q"; shift;;
+ -q*|--quiet=*) on_off_option_error --quiet -q;;
+ -?|--help) print_help; exit 0;;
+ -'?'*|--help=*) on_off_option_error --help -?;;
+ -V|--version) print_version; exit 0;;
+ -V*|--version=*) on_off_option_error --version -V;;
+ --cite) print_citation; exit 0;;
+ --cite=*) on_off_option_error --cite;;
+
+ # Unrecognized option:
+ -*) echo "$scriptname: unknown option '$1'"; exit 1;;
+
+ # Not an option (not starting with a `-'): assumed to be input FITS
+ # file name.
+ *) if [ x"$inputs" = x ]; then inputs="$1"; else inputs="$inputs $1";
fi; shift;;
+ esac
done
@@ -362,10 +376,24 @@ EOF
fi
fi
-# If an aperture size is not given at all.
+# If an aperture size is not given.
if [ x"$aperarcsec" = x ]; then
cat <<EOF
-$scriptname: ERROR: '--aperarcsec' (or '-a') is necessary at least with one
value. Run with '--help' for more information.
+$scriptname: ERROR: '--aperarcsec' (or '-a') is necessary at least with one
value. Run with '--help' for more information
+EOF
+ exit 1
+fi
+
+# If atleast one of '--refcat' or '--refimgs' are given, but not together.
+if [ x"$refcat$refimgs" = x ]; then
+ cat <<EOF
+$scriptname: ERROR: no reference image(s)/catalog provided! Please use
'--refcat' or '--refimgs' to specify the reference
+EOF
+ exit 1
+fi
+if [ x"$refcat" != x ] && [ x"$refimgs" != x ]; then
+ cat <<EOF
+$scriptname: ERROR: only one of '--refimgs' or '--refcat' should be given
EOF
exit 1
fi
@@ -393,14 +421,13 @@ if [ x"$tmpdir" = x ]; then \
tmpdir=$(pwd)/"$basename"_zeropoint
fi
-# This script will be run in a Makefile. In Make if the all the
-# prerequiesits are exist the Make do not build the prerequiesit in second
-# run. But we do not want it in Gnuastro, because sometimes user change a
-# option and she/he wants to check the final result but the final output do
-# not want to change because all the prerequiesit exist. Due to this at
-# first we will remove temeporary directory.
+# The main job of this script is managed in a Makefile. In Make, if the all
+# the prerequiesits exist, Make will not build the prerequisite in a second
+# run. To ensure that each run will repeat the full analysis (in case a
+# user changes a parameter for example), we need to make sure that the
+# temporary directory is empty.
if [ -d "$tmpdir" ]; then
- rm "$tmpdir"/*
+ rm -f "$tmpdir"/*
else
mkdir "$tmpdir"
fi
@@ -417,78 +444,84 @@ fi
# Overlap check between input and reference images
# ------------------------------------------------
#
-# In this step, we have to check and be sure if input image overlaps with
-# reference catalog or reference images. If they overlap, everything is
-# fine and script can contiue. But if they do not overlap together the
-# script will stop and let the user know that the input image does not
-# overlap with reference catalog or image.
-#
+# In this step, we have to check and be sure if the input image overlaps
+# with the reference catalog or reference images. If they overlap,
+# everything is fine and script can contiue. But if they do not overlap
+# together the script will stop and let the user know that the input image
+# does not overlap with reference catalog or image.
+
# Find minimum and maximum RA/Dec values of the input image.
allradecinput=$(astfits $inputs --hdu=$hdu --skycoverage -q | awk 'NR==2')
-minrainput=$(echo $allradecinput | awk '{print $1}')
-maxrainput=$(echo $allradecinput | awk '{print $2}')
+minrainput=$(echo $allradecinput | awk '{print $1}')
+maxrainput=$(echo $allradecinput | awk '{print $2}')
mindecinput=$(echo $allradecinput | awk '{print $3}')
maxdecinput=$(echo $allradecinput | awk '{print $4}')
+
+# Reference is a catalog.
if [ x"$refcat" != x ]; then
# Find the overlaping area between catalog and image.
- skycoverage=$tmpdir/skycoverage.fits
- asttable $refcat --inpolygon=$racolumn,$deccolumn \
- --polygon="$minrainput,$mindecinput \
+ overlap=$tmpdir/overlap.fits
+ asttable $refcat --inpolygon=$refcatra,$refcatdec \
+ --polygon=" $minrainput,$mindecinput \
: $minrainput,$maxdecinput \
: $maxrainput,$mindecinput \
: $maxrainput,$maxdecinput" \
- --output=$skycoverage
+ --output=$overlap
- # The number of stars in the overlaping area.
- number=$(asttable $skycoverage | wc -l)
+ # Find the number of stars in the overlaping area.
+ number=$(astfits $overlap -h1 --keyvalue=NAXIS2 -q)
# Stop the execution if the number of sources is zero (common sources
# not found).
if [ "$number" = 0 ]; then
# Stop if the catalog doesn't overlap with the image.
- echo "Image and catalog do not overlap."
- echo "Please provide an image and a catalog that overlap together."
+ cat <<EOF
+$scriptname: input image and reference catalog do not overlap on the sky
+EOF
exit 1
fi
-elif [ x"$reference" != x ]; then
+# Reference is an image.
+else
- # Compute how many references images are used.
+ # Find how many references images are used and go over all of them.
+ number=0
nums=$(echo $refimgs \
- | awk 'BEGIN{FS=","}{for(i=1;i<=NF;++i) printf "%s ", i}')
-
+ | awk 'BEGIN{FS=","}{for(i=1;i<=NF;++i) printf "%s ", i}')
for n in $nums; do
- # Extract the reference images name and their HDU.
- img=$(echo $refimgs | awk 'BEGIN{FS=","}{printf "%s", $'$n'}')
+ # Extract this reference image name and its HDU.
+ img=$(echo $refimgs | awk 'BEGIN{FS=","}{printf "%s", $'$n'}')
hduimg=$(echo $refimgshdu | awk 'BEGIN{FS=","}{printf "%s", $'$n'}')
- # Find the overlaping area between the catalog and the image.
+ # See if any of the edges of this reference image are within the
+ # input image.
skycoverage=$tmpdir/skycoverage-$n.fits
astfits $img --hdu=$hduimg --skycoverage -q \
- | awk 'NR==2 {printf "%f %f\n%f %f\n%f %f\n%f %f\n",
$1,$3,$1,$4,$2,$3,$2,$4}' \
- | asttable --polygon="$minrainput,$mindecinput \
+ | awk 'NR==2 {printf "%f %f\n%f %f\n%f %f\n%f %f\n", \
+ $1,$3,$1,$4,$2,$3,$2,$4}' \
+ | asttable --polygon=" $minrainput,$mindecinput \
: $minrainput,$maxdecinput \
: $maxrainput,$mindecinput \
: $maxrainput,$maxdecinput" \
--output=$skycoverage
- # The number of stars in the overlaping area.
- number=$(asttable $skycoverage | wc -l)
-
- # If reference image overlaps with input image, the script will
- # continue and obtain the zero point. While, if they do not overlap
- # the script will stopped.
- if [ "$number" = 0 ]; then
-
- # Stop if the catalog doesn't overlap with the image.
- echo "Image and catalog do not overlap."
- echo "Please provide an image that overlap with $input image."
- exit 1
- fi
+ # The number of edges in the overlaping area.
+ num=$(asttable $skycoverage | wc -l)
+ number=$((number+num))
done
+
+ # If reference image(s) overlap(s) with input image, the script will
+ # continue and obtain the zero point. While, if they do not overlap the
+ # script will stopped.
+ if [ "$number" = 0 ]; then
+ cat <<EOF
+$scriptname: input and reference image(s) does not overlap on the sky
+EOF
+ exit 1
+ fi
fi
@@ -508,16 +541,20 @@ echo "input = $inputs" >> $config
echo "hduinput = $hdu" >> $config
echo "output = $output" >> $config
echo "tmpdir = $tmpdir" >> $config
+echo "starcat = $starcat" >> $config
+echo "starcatra = $starcatra" >> $config
+echo "starcatdec = $starcatdec" >> $config
+echo "starcathdu = $starcathdu" >> $config
echo "matchradius = $matchradius" >> $config
-# Magnitude range. Empty string if not provided.
+# Magnitude range (empty string if not provided).
if [ x$magnituderange = x ]; then
echo "magrange = " >> $config
else
echo "magrange = $magnituderange" >> $config
fi
-# Size of the apertures. The comma should be change with a space.
+# Size of the apertures. In Make, the comma should be changed with a SPACE.
aper=$(echo $aperarcsec | sed 's|,| |g')
echo "aper-arcsec = $aper" >> $config
@@ -529,9 +566,9 @@ if [ x"$refcat" != x ]; then
echo "ref1 = $refcat" >> $config
echo "hduref1 = $refcathdu" >> $config
echo "refnumber = 1" >> $config
- echo "ra = $racolumn" >> $config
- echo "dec = $deccolumn" >> $config
- echo "mag = $magcolumn" >> $config
+ echo "ra = $refcatra" >> $config
+ echo "dec = $refcatdec" >> $config
+ echo "mag = $refcatmag" >> $config
else
@@ -547,7 +584,7 @@ else
for n in $num; do
img=$(echo $refimgs | awk 'BEGIN{FS=","}{printf "%s", $'$n'}')
hdu=$(echo $refimgshdu | awk 'BEGIN{FS=","}{printf "%s", $'$n'}')
- zp=$(echo $referencezp | awk 'BEGIN{FS=","}{printf "%s", $'$n'}')
+ zp=$(echo $refimgszp | awk 'BEGIN{FS=","}{printf "%s", $'$n'}')
echo "ref$n = $img" >> $config
echo "hduref$n = $hdu" >> $config
echo "zpref$n = $zp" >> $config
@@ -573,8 +610,28 @@ fi
+# If the user hasn't set the number threads, find it
+# --------------------------------------------------
+#
+# Note that on different operating systems, the command to read the number
+# of threads differs: for example in GNU/Linux based systems, it is
+# 'nproc', but in macOS is is a special case of 'sysctl'.
+if [ x"$numthreads" = x0 ]; then
+ if type nproc > /dev/null 2> /dev/null; then
+ numthreads=$(nproc --all);
+ else
+ numthreads=$(sysctl -a | awk '/^hw\.ncpu/{print $2}')
+ if [ x"$numthreads" = x ]; then numthreads=1; fi
+ fi
+fi
+
+
+
+
+
# Call the Makefile
# -----------------
+
#
# Here, Makefile is invoked.
if [ x$installdir = x ]; then
@@ -582,7 +639,7 @@ if [ x$installdir = x ]; then
else
mksrc=$installdir/zeropoint.mk
fi
-make -f $mksrc tmpdir=$tmpdir --jobs=$jobs
+make -f $mksrc tmpdir=$tmpdir --jobs=$numthreads
@@ -594,5 +651,21 @@ make -f $mksrc tmpdir=$tmpdir --jobs=$jobs
# If user does not specify to keep the build file with the option of
# --keeptmp', then the directory will be removed.
if [ x"$keeptmp" = x ]; then
- rm -rf $tmpdir
+ rm -r $tmpdir
+fi
+
+
+
+
+
+# Inform the user
+# ---------------
+#
+# The outputs are complex and it may not be clear to a new user that the
+# job is complete without any errors. So we will print the following
+# message:
+if [ x"$quiet" = x ]; then
+ cat <<EOF
+$scriptname: SUCCESS! Output: '$output'
+EOF
fi
diff --git a/bin/script/zeropoint.mk b/bin/script/zeropoint.mk
index 96916e5d..20c14685 100644
--- a/bin/script/zeropoint.mk
+++ b/bin/script/zeropoint.mk
@@ -1,27 +1,36 @@
-# Estimate the zero point of an image
+# Estimate the zero point of an image from a reference (image or catalog)
#
-# Original authors:
-# Copyright (C) 2022-2023 Sepideh Eskandarlou <sepideh.eskandarlou@gmail.com>
+# This Makefile should not be used independently. It will be called from
+# the Zeropoint script.
#
-# Contributers:
-# Copyright (C) 2019-2023 Samane Raji <samaneraji@gmail.com>
-# Copyright (C) 2019-2023 Mohammad Akhlaghi <mohammad@akhlaghi.org>
-# Copyright (C) 2019-2023 Zahra sharbaf <zahra.sharbaf2@gmail.com>
-# Copyright (C) 2019-2023 Raul Infante-Sainz <infantesainz@gmail.com>
+# NOTE ON FORMAT OF RECIPES: Non-GNU implementations of Make don't have
+# '.ONESHELL', so without connecting the recipe lines with a '\', they will
+# be executed in separate shells (which will not preserve variable
+# values). Therefore, we cannot use comments in between the separate
+# commands.
#
-# This Makefile is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
+# Current maintainer:
+# 2022-2023 Sepideh Eskandarlou <sepideh.eskandarlou@gmail.com>
+# Contributing authors:
+# 2019-2023 Mohammad Akhlaghi <mohammad@akhlaghi.org>
+# 2019-2023 Raul Infante-Sainz <infantesainz@gmail.com>
+# 2019-2022 Samane Raji <samaneraji@gmail.com>
+# 2019-2022 Zahra sharbaf <zahra.sharbaf2@gmail.com>
+# Copyright (C) 2022-2023 Free Software Foundation, Inc.
#
-# This Makefile is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-# GNU General Public License for more details.
+# This Makefile is free software: you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by the
+# Free Software Foundation, either version 3 of the License, or (at your
+# option) any later version.
#
-# You should have received a copy of the GNU General Public License
-# along with this Makefile. If not, see <http://www.gnu.org/licenses/>.
-# Set input & Final target
+# This Makefile is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
+# Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this Makefile. If not, see <http://www.gnu.org/licenses/>. Set
+# input & Final target
@@ -31,9 +40,6 @@
# Final target.
all: final
-# Make all the commands in the recipe in one shell.
-.ONESHELL:
-
# Second expansion.
.SECONDEXPANSION:
@@ -59,39 +65,46 @@ $(tmpdir):; mkdir $@
#
# Use Gaia catalog and only keep the objects with good parallax (to
# confirm that they are stars).
-stars=$(tmpdir)/gaia.fits
-$(stars): $(input) \
- | $(tmpdir)
+stars=$(tmpdir)/stars.fits
+$(stars): $(input) | $(tmpdir)
-# Download from Gaia.
-# Only keep stars (with good parallax).
-# Clean up.
+# Recipe if 'starcat' is NOT given (get it from Gaia)
+ifeq ($(strip $(starcat)),)
raw=$(subst .fits,-raw.fits,$@); \
astquery gaia --dataset=dr3 \
--overlapwith=$(input) \
-csource_id -cra -cdec -cparallax \
- -cphot_g_mean_mag -cparallax_error \
- -cpmra -cpmdec --output=$$raw; \
- asttable $$raw -cra,dec \
- -cphot_g_mean_mag --colinfoinstdout \
+ -cparallax_error -cpmra -cpmdec --output=$$raw; \
+ asttable $$raw -cra,dec --colinfoinstdout \
-c'arith parallax parallax abs \
parallax_error 3 x lt nan where ' \
- --colmetadata=4,PARALLAX,int32,"Stars with good parallax." \
- --noblankend=PARALLAX \
- | asttable -cra,dec -cphot_g_mean_mag \
- --output=$@; \
+ --colmetadata=3,GOODPLX,int32,"Stars with good parallax." \
+ --noblankend=GOODPLX \
+ | asttable -cra,dec --output=$@; \
rm $$raw
+# Recipe if 'starcat' is given (just use the 'ra' and 'dec'
+# columns). If the input doesn't have an 'ra' or 'dec' columns,
+# 'asttable' is going to complain directly. So there is no need to add
+# extra checks here.
+else
+ if [ "x$(starcathdu)" = x ]; then hdu=1; \
+ else hdu=$(starcathdu); fi; \
+ asttable $(starcat) --hdu=$$hdu --output=$@ \
+ -c$(starcatra),$(starcatdec)
+endif
+
# If the reference type is 'img', 'gencat' will be a list with many names
-# as the number of input images. If it is a catalog, prepare the single
-# reference catalog with desired columns
+# as the number of input images.
ifeq ($(reftype),img)
gencat=$(foreach i, $(refnumber), ref$(i))
+# The reference is a catalog, prepare the single reference catalog with
+# desired columns.
else
gencat=
@@ -125,15 +138,15 @@ zpinput=0
aperture=$(foreach i,input $(gencat), \
$(foreach a,$(aper-arcsec), \
$(tmpdir)/$(i)-$(a)-cat.fits))
-$(aperture): $(tmpdir)/%-cat.fits: \
- $(stars)
-
-# Extract the names.
-# Convert the aperture size (arcsec) to pixels.
-# Make an aperture catalog by using aperture size in pixels
-# Make an image of apertures.
-# Build a catalog of this aperture image.
-# Clean up.
+$(aperture): $(tmpdir)/%-cat.fits: $(stars)
+
+# Brief summary of the steps done here:
+# - Extract the names.
+# - Convert the aperture size (arcsec) to pixels.
+# - Make an aperture catalog by using aperture size in pixels
+# - Make an image of apertures.
+# - Build a catalog of this aperture image.
+# - Clean up.
img=$($(word 1, $(subst -, ,$*))); \
zp=$(zp$(word 1, $(subst -, ,$*))); \
aperarcsec=$(word 2, $(subst -, ,$*)); \
@@ -224,7 +237,7 @@ $(aperzeropoint): $(tmpdir)/zeropoint-%.txt: \
zpstd=$$(asttable $$merged $$rangeopt -cMAG-DIFF \
| aststatistics --sigclip-median \
--sigclip-std --quiet); \
- echo "$* $$zpstd" > $@
+ echo "$* $$zpstd" > $@
@@ -241,7 +254,8 @@ $(zeropoint): $(aperzeropoint)
# Obtain the zeropoint and zero point STD of each aperture.
# Find the best aperture; its zero point and STD.
# Auxiliary/temporary file
-# If the user requested a certain magnitude range, add minmag and maxmag
to header.
+# If the user requested a certain magnitude range, add minmag and
+# maxmag to header.
# The 'bestaper' above is returned from 'asttable', that is saved
# as a floating point, so the extra digits in reading floating
# points
@@ -251,9 +265,10 @@ $(zeropoint): $(aperzeropoint)
# plot for the whole aperture.
# Clean up.
zp=$(subst .fits,-tmp.txt,$@); \
- echo "# Column 1: APERTURE [arcsec,f32,]" > $$zp; \
- echo "# Column 2: ZEROPOINT [mag,f32,]" >> $$zp; \
- echo "# Column 3: ZPSTD [mag,f32,]" >> $$zp; \
+ echo "# Column 1: APERTURE [arcsec,f32,] Aperture used." > $$zp;
\
+ echo "# Column 2: ZEROPOINT [mag, f32,] Zero point (sig-clip
median)." >> $$zp; \
+ echo "# Column 3: ZPSTD [mag, f32,] Zero point Standard
deviation." \
+ >> $$zp; \
for a in $(aper-arcsec); do \
cat $(tmpdir)/zeropoint-$$a.txt >> $$zp; \
done; \
@@ -267,28 +282,31 @@ $(zeropoint): $(aperzeropoint)
bestaper=$$(asttable $$zp --sort=ZPSTD --head=1 --column=APERTURE); \
bestzp=$$(asttable $$zp --sort=ZPSTD --head=1 --column=ZEROPOINT); \
beststd=$$(asttable $$zp --sort=ZPSTD --head=1 --column=ZPSTD); \
- astfits $@.fits --write=/,"Zeropoint properties"; \
- astfits $@.fits --write=ZPAPER,"$$bestaper","Best aperture."; \
- astfits $@.fits --write=ZPVALUE,"$$bestzp","Best zero point."; \
- astfits $@.fits --write=ZPSTD,"$$beststd","Best standard deviation of
zeropoint."; \
+ astfits $@.fits --update=EXTNAME,"ZEROPOINTS" \
+ --write=/,"Zeropoint properties" \
+ --write=ZPAPER,"$$bestaper","Best aperture." \
+ --write=ZPVALUE,"$$bestzp","Best zero point." \
+ --write=ZPSTD,"$$beststd","Best std. dev. of
zeropoint."; \
if ! [ x"$(magrange)" = x ]; then \
- astfits $@.fits --write=MAGMIN,"$$magmin","Minimum magnitude for
obtaining zeropoint."; \
- astfits $@.fits --write=MAGMAX,"$$magmax","Maximum magnitude for
obtaining zeropoint."; \
+ astfits $@.fits \
+ --write=ZPMAGMIN,"$$magmin","Min mag for obtaining
zeropoint."; \
+ astfits $@.fits \
+ --write=ZPMAGMAX,"$$magmax","Max mag for obtaining
zeropoint."; \
fi; \
if [ x"$(keepzpap)" = x ]; then \
- for a in $(aper-arcsec); do \
- check=$$(echo $$a \
- | awk -vb=$$bestaper \
- '$$1>b-1e-6 && $$1<b+1e-6{print "yes"}'); \
- if [ x$$check = xyes ]; then bestaperstr=$$a; fi; \
- done; \
- astfits $(tmpdir)/zeropoint-$$bestaperstr-merged.fits --copy=1
-o$@.fits; \
- mv $@.fits $@; \
+ for a in $(aper-arcsec); do \
+ check=$$(echo $$a \
+ | awk -vb=$$bestaper \
+ '$$1>b-1e-6 && $$1<b+1e-6{print "yes"}'); \
+ if [ x$$check = xyes ]; then bestaperstr=$$a; fi; \
+ done; \
+ astfits $(tmpdir)/zeropoint-$$bestaperstr-merged.fits --copy=1
-o$@.fits; \
+ mv $@.fits $@; \
else \
- for a in $(aper-arcsec); do \
- astfits $(tmpdir)/zeropoint-$$a-merged.fits --copy=1 -o$@.fits;
\
- done; \
- mv $@.fits $@; \
+ for a in $(aper-arcsec); do \
+ astfits $(tmpdir)/zeropoint-$$a-merged.fits --copy=1 -o$@.fits; \
+ done; \
+ mv $@.fits $@; \
fi; \
rm $$zp
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index bc5467e9..8c5207fe 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -219,7 +219,7 @@ To go to the sections or subsections, you have to click on
the menu entries that
@end ifhtml
@end ifnottex
-m
+
@menu
* Introduction:: General introduction.
* Tutorials:: Tutorials or Cookbooks.
@@ -750,13 +750,14 @@ Viewing FITS file contents with DS9 or TOPCAT
Zero point estimation
-* Photometric calibration of images by zero point:: Tutorial of zero point
estimation
+* Zero point tutorial with reference image:: Using SDSS images to find J-PLUS
zero point
+* Zero point tutorial with reference catalog:: Using SDSS catalog to find
J-PLUS zero point
* Invoking astscript-zeropoint:: How to call the script
-Photometric calibration of images by zero point
+Invoking astscript-zeropoint
-* Zero point based on the reference image::
-* Zero point based on the reference catalog:: Using SDSS catalog to find
J-PLUS zero point
+* zero point output:: Format of the output.
+* zero point options:: List and details of options.
PSF construction and subtraction
@@ -24500,6 +24501,7 @@ Using the zero point magnitude (@mymath{Z}), we can
write the magnitude relation
@cindex Janskys (Jy)
@cindex AB magnitude
@cindex Magnitude, AB
+Gnuastro has an installed script to estimate the zero point of any image, see
@ref{Zero point estimation} (it contains practical tutorials to help you get
started fast).
Having the zero point of an image, you can convert its pixel values to
physical units like microJanskys (or @mymath{\mu{}Jy}).
This enables direct pixel-based comparisons with images from other
instruments@footnote{Comparing data from different instruments assumes
instrument and observation signatures are properly corrected, things like the
flat-field or the Sky absorption.
It is also valid for pixel values, assuming that factors that can change the
morphology (like the @ref{PSF}) are the same.}.
@@ -29608,120 +29610,227 @@ With this option, you can have separate color bars
under each image.
@c Update the menu: C-u C-c C-u m
@node Zero point estimation, PSF construction and subtraction, Viewing FITS
file contents with DS9 or TOPCAT, Installed scripts
@section Zero point estimation
-The calibration of an astronomical image consists in obtaining its zero point
value, see @ref{Brightness flux magnitude}.
-Gnuastro’s @command{astscript-zeropoint} script is created to obtain the zero
point of an image by considering as the reference another image or catalogs
already calibrated.
-Details and examples on how to use this script in order to calibrate an
astronomical image (find its zero point) are shown in what follows.
-Two possibilities are possible for computing the zero point: use reference
images or use reference catalogs.
-The general outline of the steps that we use to estimate the zero point in an
image is given below:
-@menu
-* Photometric calibration of images by zero point:: Tutorial of zero point
estimation
-* Invoking astscript-zeropoint:: How to call the script
-@end menu
+@cindex Zero point
+@cindex Calibration
+@cindex Astrometry
+Through the ``zero point'', we are able to give physical units to the pixel
values of an image (often in units of ``counts'' or ADUs) and thus compare them
with other images (as well as measurements that are done on them).
+The zero point is therefore an important calibration of pixel values (as
astromerty is a calibration of the pixel positions).
+The fundamental concepts behind the zero point are described in
@ref{Brightness flux magnitude}.
+We will therefore not go deeper into the basics here and stick to the
practical aspects of it.
+
+The purpose of Gnuastro’s @command{astscript-zeropoint} script is to obtain
the zero point of an image by considering another image (where the zeropoint is
already known), or a catalog.
+In the
+The operation involves multiple lower-level programs in a standard series of
steps.
+For example, when using another image, the script will take the following
steps:
@enumerate
@item
-Download the Gaia catalog using Gnuastro’s Query program (see @ref{Query}) to
determine the correct coordinates of stars in the image.
-@item
-Select the reference image or catalog and download it.
+Download the Gaia catalog that overlaps with the input image using Gnuastro’s
Query program (see @ref{Query}).
+This is done to determine the stars within the image@footnote{Stars have an
almost identical shape in the image (as opposed to galaxies for example), using
confirmed stars will produce a more reliable result.}.
@item
-Perform aperture photometry with MakeProfiles (see @ref{MakeProfiles}) and
MakeCatalog (see @ref{MakeCatalog}); a complete tutorial can be found in
@ref{Aperture photometry}.
+Perform aperture photometry@footnote{For a complete tutorial on aperture
photometry, see @ref{Aperture photometry}.} with @ref{MakeProfiles}
@ref{MakeCatalog}.
+We will assume a zeropoint of 0 for the input image.
If the reference is an image, then we should perform aperture photometry also
in that image.
@item
-Match the catalogs (see @ref{Match} and also a tutorial in @ref{Matching
catalogs}).
-Then compare the calculated magnitude with respect to the reference catalog,
and estimate the zero point value as the averaged value of the difference of
magnitudes.
+Match the two catalogs@footnote{For a tutorial on matching catalogs, see
@ref{Matching catalogs}).} with @ref{Match}.
+@item
+The difference between the input and reference magnitudes should be
independent of the magnitude of the stars.
+This does not hold when the stars are saturated in one/both the images (giving
us a bright-limit for the magnitude range to use) or for stars fainter than a
certain magnitude, where the signal-to-noise ratio drops significantly in
one/both images (giving us a faint limit for the magnitude range to use).
+@item
+Since a zero point of 0 was used for the input image, the magnitude difference
above (in the reliable magnitude range) is the zero point of the input image.
@end enumerate
-All the above steps are very long and somehow complicated.
-With the aim of automatize them, Gnuastro has an installed script in charge of
doing this task: compute the zero point value.
-Here we have a tutorial on how to use @command{astscript-zeropoint}.
-This tutorial is divided into two parts to cover both cases: using an image or
a catalog as reference data.
+In the sections below we have prepared two totrials on the use of this script.
+The first uses an image as a reference (@ref{Zero point tutorial with
reference image}) and the second uses a catalog (@ref{Zero point tutorial with
reference catalog}).
+Afterwards, in @ref{Invoking astscript-zeropoint}, the details of all the
options and how to run this script are provided.
@menu
-* Zero point based on the reference image:: Using SDSS images to find
J-PLUS zero point
-* Zero point based on the reference catalog:: Using SDSS catalog to find
J-PLUS zero point
+* Zero point tutorial with reference image:: Using SDSS images to find J-PLUS
zero point
+* Zero point tutorial with reference catalog:: Using SDSS catalog to find
J-PLUS zero point
+* Invoking astscript-zeropoint:: How to call the script
@end menu
-@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
-@subsection Zero point based on the reference image
+@node Zero point tutorial with reference image, Zero point tutorial with
reference catalog, Zero point estimation, Zero point estimation
+@subsection Zero point tutorial with reference image
-To understand how to use the @command{astscript-zeropoint}, we will find the
zero point of a single exposure image from the @url{https://www.j-plus.es,
J-PLUS survey} considering an SDSS reference image @url{htt\
-p://www.sdss.org/, Sloan Digital Sky Survey} with a zero point of 22.5 mag.
+@cindex SDSS
+In this tutorial on how to use the @command{astscript-zeropoint}, we will find
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.
-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 the one used
in @ref{Moire pattern and its correction} from the J-PLUS dataset in the r
(SDSS) band.
+@cartouche
+@cindex Johnson filters
+@cindex Johnson vs. SDSS filters
+@cindex SDSS vs. Johnson filters
+@cindex Filter transmission curve
+@cindex Transmission curve of filters
+@cindex SVO database (filter transmission curve)
+@noindent
+@strong{Same filters and SVO filter database:} It is very important that both
your images are taken with the same filter.
+When looking at filter names, don't forget that different filter systems
sometimes have the same names for one filter, such as the name ``R''; which is
used in both the Johnson and SDSS filter systems.
+Hence if you confront an image in the ``R'' or ``r'' filter, double check to
see exactly which filter system it corresponds to.
+If you know which observatory your data came from, you can use the
@url{https://svo.cab.inta-csic.es/main/index.php, SVO database} to confirm the
similarity of the transmission curves of the filters of your input and
reference images.
+SVO contains the filter data for many of the observatories world-wide.
+@end cartouche
+
+First, let’s create a directory named @file{tutorial-zeropoint} to keep things
clean and work in that.
+Then, with the commands below, you can download an image from J-PLUS and SDSS.
To speed up the analysis, the image is cropped to have a smaller region around
its center.
@example
-$ mkdir zp
+$ mkdir tutorial-zeropoint
+$ cd tutorial-zeropoint
$ jplusdr2=http://archive.cefca.es/catalogues/vo/siap/jplus-dr2/reduced
-$ wget $jplusdr2/get_fits?id=771463 -O zp/jplus.fits.fz
-$ astcrop zp/jplus.fits.fz --center=107.7263,40.1754 \
- --width=0.6 --output=zp/jplus-crop.fits
+$ wget $jplusdr2/get_fits?id=771463 -O jplus.fits.fz
+$ astcrop jplus.fits.fz --center=107.7263,40.1754 \
+ --width=0.6 --output=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}).
-Therefore, 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.
-Note that we have different @emph{r} filters such as the SDSS-r or Johnson-R
filters.
-In this case, we use the SDSS @emph{r} filter in both cases.
-Be careful and make sure that the filters are the same.
+Therefore, let's download two SDSS images (and then decompress them) in the
region of the cropped J-PLUS image to have a more accurate result compared to a
single SDSS footprint: generally, your zero point estimation will have less
scatter with more overlap between your reference image(s) and your input image.
@example
$ sdssbase=https://dr12.sdss.org/sas/dr12/boss/photoObj/frames
$ wget $sdssbase/301/6509/5/frame-r-006509-5-0115.fits.bz2 \
- -O zp/sdss1.fits.bz2
-$ bunzip2 zp/sdss1.fits.bz2
+ -O sdss1.fits.bz2
$ wget $sdssbase/301/6573/5/frame-r-006573-5-0174.fits.bz2 \
- -O zp/sdss2.fits.bz2
-$ bunzip2 zp/sdss2.fits.bz2
+ -O sdss2.fits.bz2
+$ bunzip2 sdss1.fits.bz2
+$ bunzip2 sdss2.fits.bz2
+@end example
+
+To have a feeling of the data, let's open the three images with
@command{astscript-fits-view} using the command below.
+Wait a few seconds to see the three images ``blinking'' one after another.
+The largest one is the J-PLUS crop and the two smaller ones that partially
cover it in different regions are from SDSS.
+
+@example
+$ astscript-fits-view sdss1.fits sdss2.fits jplus-crop.fits \
+ --ds9extra="-lock frame wcs -single -zoom to fit -blink yes"
+@end example
+
+The test above showed that the three images are already astrometrically
calibrated (the coverage of the pixel positions on the sky is correct in both).
+To confirm, you can zoom-in to a certain object and confirm it on a pixel
level.
+It is always good to do the visual check above when you are confronted with
new images (and may not be confident about the accuracy of the astrometry).
+Do not forget that The goal here is to find the calibration of pixel values;
and that we assume pixel positions are already calibrated (the image already
has a good astrometry).
+
+The SDSS images are Sky subtracted, while this single-exposure J-PLUS image
still contains the counts related to the Sky emission within them.
+In the J-PLUS survey, the sky-level in each pixel is kept in a separate
@code{BACKGROUND_MODEL} HDU of @file{jplus.fits.fz}; this allows you to use a
different sky if you like.
+The SDSS image FITS files also have multiple extensions.
+To understand our inputs, let's have a fast look at the basic info of each:
+
+@example
+$ astfits sdss1.fits
+Fits (GNU Astronomy Utilities) @value{VERSION}
+Run on Fri Apr 14 11:24:03 2023
+-----
+HDU (extension) information: 'sdss1.fits'.
+ Column 1: Index (counting from 0, usable with '--hdu').
+ Column 2: Name ('EXTNAME' in FITS standard, usable with '--hdu').
+ ('n/a': no name in HDU metadata)
+ Column 3: Image data type or 'table' format (ASCII or binary).
+ Column 4: Size of data in HDU.
+ Column 5: Units of data in HDU (only images).
+ ('n/a': no unit in HDU metadata, or HDU is a table)
+-----
+0 n/a float32 2048x1489 nanomaggy
+1 n/a float32 2048 n/a
+2 n/a table_binary 1x3 n/a
+3 n/a table_binary 1x31 n/a
+
+
+
+$ astfits jplus.fits.fz
+Fits (GNU Astronomy Utilities) @value{VERSION}
+Run on Fri Apr 14 11:21:30 2023
+-----
+HDU (extension) information: 'jplus.fits.fz'.
+ Column 1: Index (counting from 0, usable with '--hdu').
+ Column 2: Name ('EXTNAME' in FITS standard, usable with '--hdu').
+ ('n/a': no name in HDU metadata)
+ Column 3: Image data type or 'table' format (ASCII or binary).
+ Column 4: Size of data in HDU.
+ Column 5: Units of data in HDU (only images).
+ ('n/a': no unit in HDU metadata, or HDU is a table)
+-----
+0 n/a no-data 0 n/a
+1 IMAGE float32 9216x9232 adu
+2 MASKED_PIXELS int16 9216x9232 n/a
+3 BACKGROUND_MODEL float32 9216x9232 n/a
+4 MASK_MODEL uint8 9216x9232 n/a
@end example
-To have a feeling of the data, open all the three images with
@command{astscript-fits-view}, then set the “Frame” to “lock frame wcs” and
compare the covered area.
+Therefore, in order to be able to compare the SDSS and J-PLUS images, we
should first subtract the sky from the J-PLUS image.
+To do that, we can either subtract the @code{BACKGROUND_MODEL} HDU from the
@code{IMAGE} HDU using @ref{Arithmetic}, or we can use @ref{NoiseChisel} to
find a good sky ourselves.
+As scientists we like to tweak and be creative, so let's estimate it ourselves!
+Also, in some cases, you may not have a pre-estimated Sky estimation, so you
should be prepared:
@example
-$ astscript-fits-view zp/jplus-crop.fits zp/sdss1.fits zp/sdss2.fits
+$ astnoisechisel jplus-crop.fits --output=jplus-nc.fits
+$ astscript-fits-view jplus-nc.fits
@end example
-Note that the SDSS images are sky background subtracted, while the J-PLUS
image has not been sky background corrected.
-In order to be able to compare them, we should subtract the sky background
from the J-PLUS image.
-To do that, let's use the @code{INPUT-NO-SKY} HDU extension from the
NoiseChisel's output, see @ref{NoiseChisel} for more details.
+Notice that there is a relatively bright star in the center-bottom of the
image.
+In the ``Cube'' window, click on the ``Next'' button to see the
@code{DETECTIONS} HDU.
+The large footprint of the bright star is obvious.
+Press the ``Next'' button one more time to get to the @code{SKY} HDU.
+You see that in the center-bottom, the footprint of the large star is clearly
visible in the measured Sky level.
+This is not good!
+With Sky values above 54 ADU in the center of the star (the white pixels).
+This over-subtracted Sky level in part of the image will affect your magnitude
measurements and thus the zero point!
+
+In @ref{General program usage tutorial}, we have a section on @ref{NoiseChisel
optimization for detection}, there is also a full tutorial on this in
@ref{Detecting large extended targets}.
+Therefore, we will not go into the details of NoiseChisel optimization here.
+Given the large images of J-PLUS, we will increase the tile-size to
@mymath{100\times100} pixels and the number of neighbors to identify outlying
tiles to 50 (these are usually the first parameters you should start editing
when you are confronted with a new image).
+After the second command, check the @code{SKY} extension to confirm that there
is no footprint of any bright object there.
+You will still see a gradient, but note the minimum and maximum values of the
Sky level: their difference is more than 26 times smaller than the noise
standard deviation (so statistically speaking, it is pretty flat!)
@example
-$ astnoisechisel zp/jplus-crop.fits --output=zp/jplus-nc.fits
+$ astnoisechisel jplus-crop.fits --output=jplus-nc.fits \
+ --tilesize=100,100 --outliernumngb=50
+$ astscript-fits-view jplus-nc.fits
+
+
+## Check that the gradient in the sky is statistically negligible.
+$ aststatistics jplus-nc.fits -hSKY --minimum --maximum \
+ | awk '@{print $2-$1@}'
+0.32809
+$ aststatistics jplus-nc.fits -hSKY_STD --median
+8.377977e+00
@end example
-Now, we are ready to start finding the zero point.
-Please, call the @command{astscript-zeropoint} with the @option{--help} to see
the 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:
+We are now ready to find the zero point!
+First, let's run the @command{astscript-zeropoint} with @option{--help} to see
the option names (recall that you can see more details of each option in
@ref{Invoking astscript-zeropoint}).
+For the first time, let's use the script in the most simple state possible.
+We will keep only the essential options: the names of the input and reference
images (and their HDUs), the name of the output, and also two apertures with
radii of 3 arcsec to start with:
@example
$ astscript-zeropoint --help
-$ astscript-zeropoint zp/jplus-nc.fits --hdu=INPUT-NO-SKY \
- --refimgs=zp/sdss1.fits,zp/sdss2.fits \
- --output=zp/jplus-zeropoint.fits \
- --referencezp=22.5,22.5 \
+$ astscript-zeropoint jplus-nc.fits --hdu=INPUT-NO-SKY \
+ --refimgs=sdss1.fits,sdss2.fits \
+ --output=jplus-zeropoint.fits \
+ --refimgszp=22.5,22.5 \
--refimgshdu=0,0 \
--aperarcsec=3
@end example
-Check the output with Gnuastro's @command{astfits} program.
-You can see that there are two extensions in this file.
+The output is a FITS table (because generally, you will give more apertures
and choose the best one based on a higher-level analysis).
+Let's check the output's internal structure with Gnuastro's @command{astfits}
program.
@example
-$ astfits zp/jplus-zeropoint.fits
+$ astfits jplus-zeropoint.fits
-----
0 n/a no-data 0 n/a
-1 TABLE table_binary 1x3 n/a
+1 ZEROPOINTS table_binary 1x3 n/a
2 APER-3 table_binary 321x2 n/a
@end example
-Let's have a look at each extension with Gnuastro's @command{asttable} program:
+You can see that there are two HDUs in this file.
+The HDU names give a hint, so let's have a look at each extension with
Gnuastro's @command{asttable} program:
@example
-$ asttable zp/jplus-zeropoint.fits --hdu=1 -i
+$ asttable jplus-zeropoint.fits --hdu=1 -i
--------
-zp/jplus-zeropoint.fits (hdu: 1)
+jplus-zeropoint.fits (hdu: 1)
------- ----- ---- -------
No.Name Units Type Comment
------- ----- ---- -------
@@ -29731,10 +29840,17 @@ No.Name Units Type Comment
--------
Number of rows: 1
--------
+@end example
-$ asttable zp/jplus-zeropoint.fits --hdu=2 -i
+@noindent
+As you can see, in the first extension, for each of the apertures you
requested (@code{APERTURE}), there is a zero point (@code{ZEROPOINT}) and the
standard deviation of the measurements on the apertures (@code{ZPSTD}).
+In this case, we only requested one aperture, so it only has one row.
+Now, let's have a look at the next extension:
+
+@example
+$ asttable jplus-zeropoint.fits --hdu=2 -i
--------
-zp/jplus-zeropoint.fits (hdu: 2)
+jplus-zeropoint.fits (hdu: 2)
------- ----- ---- -------
No.Name Units Type Comment
------- ----- ---- -------
@@ -29745,50 +29861,112 @@ Number of rows: 321
--------
@end example
-As you can see, in the first extension, there is a zero point
(@code{ZEROPOINT}) 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 respect to the J-PLUS magnitudes that has been used for
estimating the zero point.
-Now that we have obtained the zero point of the J-PLUS image, let's go into
more details by considering other options and improve the result.
+It contains a table of measurements for the aperture with the least scatter.
+In this case, we only gave one aperture, so it is the same.
+If you give multiple apertures, only the one with least scatter will be
present by default.
+In the @code{MAG-REF} column you see the magnitudes within each aperture on
the reference (SDSS) image(s).
+The @code{MAG-DIFF} column contains the difference of the input (J-PLUS) and
reference (SDSS) magnitudes for each aperture (see @ref{Zero point estimation}).
+The two catalogs created by the aperture photometry from the SDSS images are
merged into one so that there are more stars to compare.
+Therefore, no matter how many reference images you provide, there will only be
a single table here.
+If the two SDSS images overlapped, each object in the overlap region would
have two rows (one row for the measurement from one SDSS image, and another
from the measurement from the other).
-The two catalogs created by the aperture photometry from the SDSS image are
merged so that there are more stars to compare.
-If you like to check the temporal files of the intermediate steps, you can use
@option{--keeptmp} option to not remove them.
-By using Gnuastro’s @command{astfits} you can see the content of the output,
then you can extract the table with @command{asttable}.
-Finally you can use your tool to plot the output results, our recommendation
is @code{TOPCAT} by using @command{astscript-fits-view}.
+Now that we have obtained the zero point of the J-PLUS image, let's go a
little deeper into lower-level details of how this script operates.
+This will help you better understand what happened and how to interpret and
improve the outputs when you are confronted with a new image and strange
outputs.
+
+To keep intermediate results the @command{astscript-zeropoint} script keeps
temporary files in a temporary directory and later deletes it (and all the
intermediate products).
+If you like to check the temporary files of the intermediate steps, you can
use @option{--keeptmp} option to not remove them.
+
+Let's take a closer look into the contents of each HDU.
+First, we'll use Gnuastro’s @command{asttable} to see the measured zeropoint
for this apture.
+We are using @option{-Y} to have human-friendly (non-scientific!) numbers
(which are sufficient here) and @option{-O} to also show the metadata of each
column at the start.
+
+@example
+$ asttable jplus-zeropoint.fits -Y -O
+# Column 1: APERTURE [arcsec,f32,] Aperture used.
+# Column 2: ZEROPOINT [mag ,f32,] Zero point (sig-clip median).
+# Column 3: ZPSTD [mag ,f32,] Zero point Standard deviation.
+3.000 26.435 0.057
+@end example
+
+@noindent
+Now, let's have a look at the first 10 rows of the second (@code{APER-3})
extension.
+From the previous check we did above, we see that it contains 321 rows!
+
+@example
+$ asttable jplus-zeropoint.fits -Y -O --hdu=APER-3 --head=10
+# Column 1: MAG-REF [f32,f32,] Magnitude of reference.
+# Column 2: MAG-DIFF [f32,f32,] Magnitude diff with input.
+16.461 30.035
+16.243 28.209
+15.427 26.427
+20.064 26.459
+17.334 26.425
+20.518 26.504
+17.100 26.400
+16.919 26.428
+17.654 26.373
+15.392 26.429
+@end example
+
+But the table above is hard to interpret, so let's plot it.
+To do this, we'll use the same @command{astscript-fits-view} command above
that we used for images.
+It detects if the file has a image or table HDU and will call DS9 or TOPCAT
respectively.
+You can also use any other plotter you like (TOPCAT is not part of Gnuastro),
this script just calls it.
@example
-$ astfits zp/jplus-zeropoint.fits
-$ asttable zp/jplus-zeropoint.fits
-$ astscript-fits-view zp/jplus-zeropoint.fits --hdu=2
+$ astscript-fits-view jplus-zeropoint.fits --hdu=APER-3
@end example
-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 as a function of the SDSS magnitude for a specific aperture
radius which is 3 arcsec, here.
+After @code{TOPCAT} opens, you can select the ``Graphics'' menu and then
``Plain plot''.
+This will show a plot with the SDSS (reference image) magnitude on the
horizontal axis and the difference of magnitudes between the the input and
reference (the zero point) on the vertical axis.
-Ideally, it is expected that differences in magnitudes are around a straight
line with very small fluctuations.
-But in practice, as you can see in the plot, this behavior is seen only for
stars with magnitudes about 16 to 18 mag in reference SDSS catalog.
-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.
+In an ideal world, the zeropoint should be independent of the magnitude of the
different stars that were used.
+Therefore, this plot should be a horizontal line (with some scatter as we go
to fainter stars).
+But as you can see in the plot, in the real world, this expected behavior is
seen only for stars with magnitudes about 16 to 19 in the reference SDSS images.
+The stars that are brighter than 16 are saturated in one (or both)
surveys@footnote{To learn more about saturated pixels and recognition of the
saturated level of the image, please see @ref{Saturated pixels and Segment's
clumps}}.
+Therefore, they do not have the correct magnitude or mag-diff.
+You can check some of these stars visually by using the blinking command above
and zooming into some of the brighter stars in the SDSS images.
-On the other hand, it is natural there are not 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.
+@cindex Depth
+On the other hand, it is natural that we cannot measure accurate magnitudes
for the fainter stars because the noise level (or ``depth'') of each image is
limited.
+As a result, the horizontal line becomes wider (scattered) as we go to the
right (fainter magnitudes on the horizontal axis).
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, for better understanding 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 will see a bad result so that there is not a reasonable range of magnitude
for finding the zero point.
-
-Another key parameter 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.
-On the other hand, with large aperture size, the light of neighboring stars
can affect the photometry by artificially increasing it.
-We should select an aperture radius of the same order than the one used in the
reference image, typically 2 to 3 times the FWHM of the images.
+For this reason, we have the @option{--magnituderange} option in
@command{astscript-zeropoint}.
+
+@cartouche
+@noindent
+@strong{Necessity of sky subtraction:}
+To obtain this horizontal line, it is very important that both your images
have been sky subtracted.
+Please, repeat the last @command{astscript-zeropoint} command above only by
changing the input file to @file{jplus-crop.fits}.
+Then use Gnuastro’s @command{astscript-fits-view} again to draw a plot with
@code{TOPCAT} (also same as above).
+Instead of a horizontal line, you will see @emph{a sloped line} in the
magnitude range above!
+This happens because the sky level acts as a source of constant signal in all
apertures, so the magnitude difference will not be independent of the star's
magnitude, but dependent on it (the measurement on a fainter star will be
dominated by the sky level).
+
+@strong{Remember:} if you see a sloped line instead of a horizontal line, the
input or reference image(s) are not sky subtracted.
+@end cartouche
+
+Another key parameter of this script is the aperture size
(@option{--aperarcsec}) for the aperture photometry of images.
+On one hand, if the selected aperture is too small, you will be at the mercy
of the differing PSFs between your input and reference image(s): part of the
light of the star will be lost in the image with the worse PSF.
+On the other hand, with large aperture size, the light of neighboring objects
(stars/galaxies) can affect the photometry.
+We should select an aperture radius of the same order than the one used in the
reference image, typically 2 to 3 times the PSF FWHM of the images.
For now, let's assume the values 2, 3, 4, 5, and 6 arcsec for the aperture
sizes parameter.
-What the code does is to compare the result for several aperture sizes and
choose the best one based on the minimum standard deviation value, @code{ZPSTD}
parameter.
+The script will compare the result for several aperture sizes and choose the
one with least standard deviation value, @code{ZPSTD} column of the
@code{ZEROPOINTS} HDU.
-Let's re-run the script with this new option (@option{--magnituderange}) and
more values for aperture size as explained above.
-Also, use the useful @option{--keepzpap} option to keep the result of matching
the catalogs done with the selected apertures in the different extensions of
the output file.
+Let's re-run the script with the following changes:
+@itemize
+@item
+Using @option{--magnituderange} to limit the stars used for estimating the
zeropoint.
+@item
+Giving more values for aperture size to find the best for these two images as
explained above.
+@item
+Call @option{--keepzpap} option to keep the result of matching the catalogs
done with the selected apertures in the different extensions of the output file.
+@end itemize
@example
-$ astscript-zeropoint zp/jplus-nc.fits --hdu=INPUT-NO-SKY \
- --refimgs=zp/sdss1.fits,zp/sdss2.fits \
- --output=zp/jplus-zeropoint.fits
- --referencezp=22.5,22.5 \
+$ astscript-zeropoint jplus-nc.fits --hdu=INPUT-NO-SKY \
+ --refimgs=sdss1.fits,sdss2.fits \
+ --output=jplus-zeropoint.fits \
+ --refimgszp=22.5,22.5 \
--aperarcsec=2,3,4,5,6 \
--magnituderange=16,18 \
--refimgshdu=0,0 \
@@ -29798,10 +29976,10 @@ $ astscript-zeropoint zp/jplus-nc.fits
--hdu=INPUT-NO-SKY \
Now, check number of HDU extensions by @command{astfits}.
@example
-$ astfits zp/jplus-zeropoint.fits
+$ astfits jplus-zeropoint.fits
-----
0 n/a no-data 0 n/a
-1 TABLE table_binary 5x3 n/a
+1 ZEROPOINS table_binary 5x3 n/a
2 APER-2 table_binary 319x2 n/a
3 APER-3 table_binary 321x2 n/a
4 APER-4 table_binary 323x2 n/a
@@ -29809,177 +29987,207 @@ $ astfits zp/jplus-zeropoint.fits
6 APER-6 table_binary 325x2 n/a
@end example
-You can see that the output file includes 6 extensions.
-The extension 1 contains the final zero point value and its error.
-It is the best zero point value considered from the different apertures
because it is the one with the lowest standard deviation value.
-The rest of extensions contain the zero point value computed within each
aperture.
+You can see that the output file now has a separate HDU for each aperture
(thanks to @option{--keepzpap}.)
+The @code{ZEROPOINTS} hdu contains the final zero point values for each
aperture and their error.
+The best zero point value belongs to the aperture that has the least scatter
(has the lowest standard deviation).
+The rest of extensions contain the zero point value computed within each
aperture (as discussed above).
Let's check the different tables by plotting all magnitude tables at the same
time with @code{TOPCAT}.
@example
-$ astscript-fits-view zp/jplus-zeropoint.fits
+$ astscript-fits-view jplus-zeropoint.fits
@end example
-After @code{TOPCAT} is opened, first of all select ``Graphics'' and then
choose ``Plain plot''.
-Finally by ``Add a new positional plot control to the stack'' open all the
extensions.
-See the @code{ZPSTD} of zero points for each aperture to estimate an accurate
magnitude range.
+@noindent
+After @code{TOPCAT} has opened take the following steps:
+@enumerate
+@item
+From the ``Graphics'' menu, select ``Plain plot''.
+You will see the last HDU's scatter plot open in a new window (for
@code{APER-6}, with red points).
+The Bottom-left pannel has the logo of a red-blue scatter plot that has
written @code{6:jplus-zeropoint.fits} infront of it (showing that this is the
6th HDU of this file).
+In the bottom-right pannel, you see the names of the columns that are being
displayed.
+@item
+In the ``Layers'' menu, Click on ``Add Position Control''.
+On the bottom-left pannel, you will notice that a new blue-red scatter plot
has appeared but it just says @code{<no table>}.
+In the bottom-right panel, infront of ``Table:'', select any other extension.
+This will plot the same two columns of that extension as blue points.
+Zoom-in to the region of the horizontal line to see/compare the differerent
scatters.
-The minimum of @code{ZPSTD} can represent the best aperture radius for the
selected range of magnitude.
-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.
+Change the HDU given to ``Table:'' and see the distribution of zeropoints for
the different apertures.
+@end enumerate
-To see the final result for the zero point, please, re-run the script with the
new magnitude range.
+The manual/visual operation above is critical if this is your first time with
a new dataset (it shows all kinds of systematic biases (like the Sky issue
above)!
+But once you know your data has no systematic biases, choosing between the
different apertures is not easy visually!
+Let's have a look at the table the @code{ZEROPOINTS} HDU (we don't need to
explicitly call this HDU since it is the first one):
@example
-$ astscript-zeropoint zp/jplus-nc.fits --hdu=INPUT-NO-SKY \
- --refimgs=zp/sdss1.fits,zp/sdss2.fits \
- --output=zp/jplus-zeropoint.fits
- --magnituderange=16.4,17.8 \
- --referencezp=22.5,22.5 \
- --aperarcsec=2,3,4,5,6 \
- --refimgshdu=0,0 \
- --keepzpap
+$ asttable jplus-zeropoint.fits -O -Y
+# Column 1: APERTURE [arcsec,f32,] Aperture used.
+# Column 2: ZEROPOINT [mag ,f32,] Zero point (sig-clip median).
+# Column 3: ZPSTD [mag ,f32,] Zero point Standard deviation.
+2.000 26.405 0.028
+3.000 26.436 0.030
+4.000 26.448 0.035
+5.000 26.458 0.042
+6.000 26.466 0.056
@end example
-As explained above, the @command{astscript-zeropoint} script estimates 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.
-The different parameters like the magnitude range (@code{MAGMIN} and
@code{MAGMAX}), the aperture (@code{ZPAPER}), the zero point and its error
(@code{ZPVALUE} and @code{ZPSTD}), are saved into the header of the output.
-Please see it by the command like below:
+The most accurate zeropoint is the one where @code{ZPSTD} is the smallest.
+In this case, minimum of @code{ZPSTD} is with radii of 2 and 3 arcseconds.
+Run the @command{astscript-fits-view} command above again to open TOPCAT.
+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 (where we have no saturated
stars) and 18.5 mag (fainter than this, the scatter becomes too strong).
+Finally, let's set some more apertures between 2 and 3 arcseconds radius:
@example
-$ astfits zp/jplus-zeropoint.fits --hdu=1 --quiet \
- --keyvalue=ZPAPER,ZPVALUE,ZPSTD,MAGMIN,MAGMAX
-3.000000 26.431959 0.029635 16.400000 17.799999
+$ astscript-zeropoint jplus-nc.fits --hdu=INPUT-NO-SKY \
+ --refimgs=sdss1.fits,sdss2.fits \
+ --output=jplus-zeropoint.fits \
+ --magnituderange=16.4,18.5 \
+ --refimgszp=22.5,22.5 \
+ --aperarcsec=2,2.5,3,3.5,4 \
+ --refimgshdu=0,0 \
+ --keepzpap
+
+$ asttable jplus-zeropoint.fits -Y
+2.000 26.405 0.037
+2.500 26.425 0.033
+3.000 26.436 0.034
+3.500 26.442 0.039
+4.000 26.449 0.044
@end example
-@node Zero point based on the reference catalog, , Zero point based on the
reference image, Photometric calibration of images by zero point
-@subsection Zero point based on the reference catalog
+The aperture with the least scatter is therefore the 2.5 arcsec radius
aperture, giving a zeropoint of 26.425 magnitudes for this image.
+However, you can see that the scatter for the 3 arcsec aperture is also
acceptable.
+Actually, the @code{ZPSTD} for of the 2.5 and 3 arcsec apertures only have a
difference of @mymath{3\%} (@mymath{= (0.034−0.0333)/0.033\times100}).
+So simply choosing the minimum is just a first-order approximation (which is
accurate within @mymath{26.436−26.425=0.011} magnitudes)
-In @ref{Zero point based on the reference image}, we explained how to use the
@command{astscript-zeropoint} for estimating the zero point of one image based
on a reference image.
-Sometimes there is not a reference image and we need to use a reference
catalog.
-Fortunately, @command{astscript-zeropoint} can also use the catalog instead of
the image to find the zero point.
+Note that in aperture photometry, the PSF plays an important role (because the
aperutre is fixed but the two images can have very different PSFs).
+The aperture with the least scatter should also account for the differing PSFs.
+Overall, please, always check the different and intermediate steps to make
sure the parameters are the good so the estimation of the zero point is correct.
-To show this, let's download a catalog of SDSS in the area that overlaps with
the cropped J-PLUS image (used in the previous section, @ref{Zero point based
on the reference image}).
-For more on Gnuastro's Query program, please see @ref{Query}.
-The columns of ID, RA, Dec and magnitude in the SDSS @emph{r} filter are
called by their name in the SDSS catalog.
+If you are happy with the minimum, you don't have to search for the minimum
aperture or its corresponding zeropoint yourself.
+This script has written it in @code{ZPVALUE} keyword of the table.
+With the first command, we also see the name of the file also, (you can use
this on many files for example).
+With the second command, we are only printing the number by adding the
@option{-q} (or @option{--quiet}) option (this is useful in a script where you
want to write the value in a shell variable to use later).
@example
-$ astquery vizier \
- --dataset=sdss12 \
- --overlapwith=zp/jplus-crop.fits \
- --column=objID,RA_ICRS,DE_ICRS,rmag \
- --output=zp/sdss-catalog.fits
+$ astfits jplus-zeropoint.fits --keyvalue=ZPVALUE
+jplus-zeropoint.fits 2.642512e+01
+
+$ astfits jplus-zeropoint.fits --keyvalue=ZPVALUE -q
+2.642512e+01
@end example
-To visualize the position of the SDSS objects over the J-PLUS image, let's use
@command{astscript-ds9-region} (for more details please see @ref{SAO DS9 region
files from table}) and ds9 with two commands below:
+Generally, this script will write the following FITS keywords (all starting
with @code{ZP}) for your future reference in its output:
@example
-$ astscript-ds9-region zp/sdss-catalog.fits \
- --column=RA_ICRS,DE_ICRS \
- --color=red --width=3 \
- --output=zp/sdss.reg
-$ ds9 zp/jplus-nc.fits[INPUT-NO-SKY] -regions load zp/sdss.reg \
- -scale zscale
+$ astfits jplus-zeropoint.fits -h1 | grep ^ZP
+ZPAPER = 2.5 / Best aperture.
+ZPVALUE = 26.42512 / Best zero point.
+ZPSTD = 0.03276644 / Best std. dev. of zeropoint.
+ZPMAGMIN= 16.4 / Min mag for obtaining zeropoint.
+ZPMAGMAX= 18.5 / Max mag for obtaining zeropoint.
@end example
-Now, we are ready to estimate the zero point of the J-PLUS image based on the
SDSS catalog.
-To download the input image and understand how to use the
@command{astscript-zeropoint}, please see @ref{Zero point based on the
reference image}.
-In what follow, only the related options to the reference catalog will be
shown.
+Using the @option{--keyvalue} option of the @ref{Fits} program, you can easily
get multiple of the values in one run (where necessary):
@example
-$ astscript-zeropoint zp/jplus-nc.fits --hdu=INPUT-NO-SKY \
- --refcat=zp/sdss-catalog.fits \
- --refcathdu=1 \
- --magcolumn=rmag \
- --racolumn=RA_ICRS \
- --deccolumn=DE_ICRS \
- --aperarcsec=2,3,4,5,6 \
- --referencezp=22.5 --keepzpap \
- --output=zp/jplus-zeropoint.fits
+$ astfits jplus-zeropoint.fits --hdu=1 --quiet \
+ --keyvalue=ZPAPER,ZPVALUE,ZPSTD
+2.500000e+00 2.642512e+01 3.276644e-02
@end example
-Please see the standard deviation, @code{ZPSTD}, of the zero points for each
aperture from the first extension of the output file.
+@node Zero point tutorial with reference catalog, Invoking
astscript-zeropoint, Zero point tutorial with reference image, Zero point
estimation
+@subsection Zero point tutorial with reference catalog
-@example
-$ asttable zp/jplus-zeropoint.fits -Y -h1
+In @ref{Zero point tutorial with reference image}, we explained how to use the
@command{astscript-zeropoint} for estimating the zero point of one image based
on a reference image.
+Sometimes there is not a reference image and we need to use a reference
catalog.
+Fortunately, @command{astscript-zeropoint} can also use the catalog instead of
the image to find the zero point.
-2.000 26.336 0.066
-3.000 26.413 0.076
-4.000 26.451 0.080
-5.000 26.473 0.092
-6.000 26.491 0.101
-@end example
+To show this, let's download a catalog of SDSS in the area that overlaps with
the cropped J-PLUS image (used in the previous section).
+For more on Gnuastro's Query program, please see @ref{Query}.
+The columns of ID, RA, Dec and magnitude in the SDSS @emph{r} filter are
called by their name in the SDSS catalog.
-The best @code{ZPSTD}s are related to aperture radii of 2 and 3 arcsec.
+@example
+$ astquery vizier \
+ --dataset=sdss12 \
+ --overlapwith=jplus-crop.fits \
+ --column=objID,RA_ICRS,DE_ICRS,rmag \
+ --output=sdss-catalog.fits
+@end example
-At the same time, please open the output file by below command with
@code{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.
+To visualize the position of the SDSS objects over the J-PLUS image, let's use
@command{astscript-ds9-region} (for more details please see @ref{SAO DS9 region
files from table}) with the command below (it will automatically open DS9 and
load the regions it created):
@example
-$ astscript-fits-view zp/jplus-zeropoint.fits
+$ astscript-ds9-region sdss-catalog.fits \
+ --column=RA_ICRS,DE_ICRS \
+ --color=red --width=3 --output=sdss.reg \
+ --command="ds9 jplus-nc.fits[INPUT-NO-SKY] \
+ -scale zscale"
@end example
-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 to estimate an averaged zero point and
remove the most of outliers (for more details please see @ref{Sigma clipping}),
it is good to limit the range of magnitude.
-We can select an interval with lower fluctuations for example around 16.8 to
17.8 mag.
+Now, we are ready to estimate the zero point of the J-PLUS image based on the
SDSS catalog.
+To download the input image and understand how to use the
@command{astscript-zeropoint}, please see @ref{Zero point tutorial with
reference image}.
+
+Many of the options (like the aperture size) and magnitude range are the same
so we will not discuss them further.
+You will notice that the only substantive difference of the command below with
the last command in the previous section is that we are using @option{--refcat}
instead of @option{--refimgs}.
+There are also some cosmetic differences for example a new output name, not
using @option{--refimgszp} since it is only necessary for images) and the
@option{--*column} options which are used to identify the names of the
necessary columns of the input catalog:
@example
-$ astscript-zeropoint zp/jplus-nc.fits --hdu=INPUT-NO-SKY \
- --refcat=zp/sdss-catalog.fits \
- --refcathdu=1 \
- --magcolumn=rmag \
- --racolumn=RA_ICRS \
- --deccolumn=DE_ICRS \
- --aperarcsec=2,3,4,5,6 \
- --magnituderange=16.8,17.8 \
- --referencezp=22.5 --keepzpap \
- --output=zp/jplus-zeropoint.fits
+$ astscript-zeropoint jplus-nc.fits --hdu=INPUT-NO-SKY \
+ --refcat=sdss-catalog.fits \
+ --refcatmag=rmag \
+ --refcatra=RA_ICRS \
+ --refcatdec=DE_ICRS \
+ --output=jplus-zeropoint-cat.fits \
+ --magnituderange=16.4,18.5 \
+ --aperarcsec=2,2.5,3,3.5,4 \
+ --keepzpap
@end example
-The best zero point is in the header of the output file, and it has been
selected because of its minimum @code{ZPSTD} value.
+@noindent
+Let's inspect the output with the command below.
@example
-$ astfits zp/jplus-zeropoint.fits --hdu=1 --quiet \
- --keyvalue=ZPAPER,ZPVALUE,ZPSTD,MAGMIN,MAGMAX
-2.000000 26.336220 0.029594 16.799999 17.799999
+$ asttable jplus-zeropoint-cat.fits -Y
+2.000 26.337 0.034
+2.500 26.386 0.036
+3.000 26.417 0.041
+3.500 26.439 0.043
+4.000 26.455 0.050
@end example
-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, the @code{ZPSTD} for them have no significant difference.
-Note that an aperture similar to the aperture used for the reference catalog
should be used.
-In this sense, the PSF plays an important role.
-All of these effects are included in the assumtion of different apertures and
the selection of the one with the smaller @code{ZPSTD} value.
-Overall, please, always check the different and intermediate steps to make
sure the parameters are the good so the estimation of the zero point is correct.
+As you see, the values and standard deviations are very similar to the results
we got previously in @ref{Zero point tutorial with reference image}.
+The Standard deviations are generally a little higher here because we didn't
do the photometry ourselves, but they are statistically similar.
-Finally, let's delete the zp directory to keep everything clean.
+Before we finish, let's open the two outputs (from a reference image and
reference catalog) with the command below.
+To confirm how they compare, we are showing the result for @code{APER-3}
extension in both (following the TOPCAT plotting recipe in @ref{Zero point
tutorial with reference image}).
@example
-$ rm -rf zp
+$ astscript-fits-view jplus-zeropoint.fits jplus-zeropoint-cat.fits \
+ -hAPER-3
@end example
-@node Invoking astscript-zeropoint, , Photometric calibration of images by
zero point, Zero point estimation
+@node Invoking astscript-zeropoint, , Zero point tutorial with reference
catalog, Zero point estimation
@subsection Invoking astscript-zeropoint
-This installed script will calculate the zeropoint @ref{Brightness flux
magnitude} and @ref{Zero point estimation} to calibrate the image magnitude to
the standard magnitude.
-It will obtained the zeropoint of image based on the image(s) or catalog(s)
which their magnitude are known.
-It allows to the user determine the options disparate options that presented
here.
-This script can be used with the following general template:
+This installed script will calculate the zero point of an input image to
calibrate it.
+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:
@example
-## Based on the reference images zero point of the input image will
- obtained.
+## Using a reference image in four apertures.
$ astscript-zeropoint image.fits --hdu=1 \
--refimgs=ref-img1.fits,ref-img2.fits \
--refimgshdu=1,1 \
- --referencezp=22.5,22.5 \
+ --refimgszp=22.5,22.5 \
--aperarcsec=1.5,2,2.5,3 \
--magnituderange=16,18 \
--output=output.fits
-@end example
-@example
-## Based on the catalog which has magnitude column zero point of the
- image will obtained.
+## Using a reference catalog
$ astscript-zeropoint image.fits --hdu=1 \
--refcat=cat.fits \
--refcathdu=1 \
@@ -29988,66 +30196,183 @@ $ astscript-zeropoint image.fits --hdu=1 \
--output=output.fits
@end example
+To learn more about the core concepts behind the zero point, please see
@ref{Brightness flux magnitude}.
+For a practical review of how to optimally use this script and ways to
interpret its results, we have two tutorials: @ref{Zero point tutorial with
reference image} and @ref{Zero point tutorial with reference catalog}.
+
+To find the zero point of your input image, this script can use a reference
image (that already has a zero point) or a reference catalog (that just has
magnitudes).
+In any case, it is mandatory to identify at least one aperture for aperture
photometry over the image (using @option{--aperarcsec}).
+If reference image(s) is(are) given, it is mandatory to specify its(their)
zero point(s) using the @option{--refimgszp} option (it can take a separate
value for each reference image).
+When a catalog is gien, it should already contain the magntiudes of the object
(you can specify which column to use).
+
+This script will not estimate the zeropoint based on all the objects in the
reference image or catalog.
+It will first query Gaia database and only select objects have a significant
parallax (because Gaia's algorithms sometimes confuse galaxies and stars based
on pure morphology).
+You can bypass this step (which needs internet connection and can only be used
on real data, not simulations) using the @option{--starcat} option described in
@ref{zero point options}.
+This script will then match the catalog of stars (either through Gaia or
@option{--starcat}) with the reference catalog and only use them.
+If the reference is an image, it will simply use the stars catalog to do
aperture photometry.
+
+By default, this script will estimate the number of available threads and run
all independent steps in parallel on those threads.
+To control this behavior (and allow it to only run on a certain number of
threads), you can use the @option{--numthreads} option.
+
+During its operation, this script will build a temporary file in the running
directory that will be deleted once it is finished.
+The @option{--tmpdir} option can be used to manually set the temporary
directory's location at any location in your file system.
+The @option{--keeptmp} option can be used to stop the deletion of that
directory (useful for when you want to debug the script or better understand
what it does).
+
+@menu
+* zero point output:: Format of the output.
+* zero point options:: List and details of options.
+@end menu
+
+@node zero point output, zero point options, Invoking astscript-zeropoint,
Invoking astscript-zeropoint
+@subsubsection @code{astscript-zeropoint} output
+
+The output will be a multi-extension FITS table.
+The first table in the output gives the zero point and its standard deviation
for all the requested apertures.
+This gives you the ability to inspect them and select the best.
+The other table(s) give the exact measurements for each star that was used (if
you use @option{--keepzpap}, it will be for all your apertures, if not, only
for the aperture with the smallest standard deviation).
+For a full tutorial on how to interpret the output of this script, see
@ref{Zero point tutorial with reference image}
+
+If you just want the estimated zero point with the least standard deviation,
this script will write it as a FITS keyword in the first table of the output.
+
+@table @code
+@item ZPAPER
+Read as ``Zero Point APERture''.
+This shows the aperture radius (in arcseconds) that had the smallest standard
deviation in the estimated zero points.
+@item ZPVALUE
+The zero point estimation for the aperture of @code{ZPAPER}.
+@item ZPSTD
+The standard deviation of the zero point (for all the stars used, within the
aperture of @code{ZPAPER}).
+@item ZPMAGMIN
+The minimum (brightest) magnitude used to estimate the zero point.
+@item ZPMAGMAX
+The maximum (faintest) magnitude used to estimate the zero point.
+@end table
+
+@noindent
+A simple way to see these keywords, or read the value of one is shown below.
+For more on viewing and manipulating FITS keywords, see @ref{Keyword
inspection and manipulation}.
+
+@example
+## See all the keywords written by this script (that start with 'ZP')
+$ astfits out.fits -h1 | grep ^ZP
+
+## If you just want the zero point
+$ astfits jplus-zeropoint.fits -h1 --keyvalue=ZPVALUE
+@end example
+
+@node zero point options, , zero point output, Invoking astscript-zeropoint
+@subsubsection @code{astscript-zeropoint} options
-This script takes the following options:
+All the operating phases of the this script can be customized through the
options below.
@table @option
@item -h STR/INT
@itemx --hdu=STR/INT
The HDU/extension of the input image to use.
+@item -o STR
+@itemx --output=STR
+The name of the output file produced by this script.
+See @ref{zero point output} for the format of its contents.
+
+@item -N INT
+@itemx --numthreads=INT
+The number of threads to use.
+By default this script will attempt to find the number of available threads at
run-time and will use them.
+
+@item -a FLT,[FLT]
+@itemx --aperarcsec=FLT,[FLT]
+The radius/radii (in arc seconds) of aperture(s) used in aperture photometry
of the input image.
+This option can take many values (to check different apertures and find the
best for a more accurate zero point estimation).
+If a reference image is used, the same aperture radii will be used for
aperture photometry there.
+
+@item -M FLT,FLT
+@itemx --magnituderange=FLT,FLT
+Range of the magnitude for finding the best aperture and zero point.
+Very bright stars get saturated and fainter stars are affected too much by
noise.
+Therefore, it is important to limit the range of magnitudes used in estimating
the zeropoint.
+A full tutorial is given in @ref{Zero point tutorial with reference image}.
+
+@item -S STR
+@itemx --starcat=STR
+Name of catalog containing the RA and Dec of positions for aperture photomery
in the input image and reference (catalog or image).
+If not given, the Gaia database will be queried for all stars that overlap
with the input image (see @ref{Available databases}).
+
+This option is therefore useful in the following scenarios (among others):
+@itemize
+@item
+No internet connection.
+@item
+Many images having a major overlap in the sky, making it inefficient to query
Gaia for every image separately: you can query the larger area (containing all
the images) once, and directly give the downloaded table to all the separate
runs of this script.
+Especially if the field is wide, the download time can be the slowest part of
this script.
+@item
+In simulations (where you have a pre-defined list of stars).
+@end itemize
+
+Through the @option{--starcathdu}, @option{--starcatra} and
@option{--starcatdec} options described below, you can specify the HDU, RA
column and Dec Column within this file.
+
+The reference image or catalog probably have many objects that are not stars.
+But it is only stars that have the same shape (the PSF) across the
image@footnote{The PSF itself can vary across the field of view; but that is
second-order for this analysis.}.
+Therefore
+
+@item --starcathdu=STR/INT
+The HDU name or number in file given to @option{--starcat} (described above)
that contains the table of RA and Dec positions for aperture photometry.
+If not given, it is assumed that the table is in HDU number 1 (counting from
0).
+
+@item --starcatra=STR/INT
+The column name or number (in the table given to @option{--starcat}) that
contains the Right Ascension.
+
+@item --starcatdec=STR/INT
+The column name or number (in the table given to @option{--starcat}) that
contains the Declination.
+
@item -c STR
@itemx --refcat=STR
-Reference catalog which based on it, the zeropoint of the input image will be
estimated.
-This catalog should be have ra, dec and magnitude of the stars.
+Reference catalog used to estimate the zero point of the input image.
+This option is mutually exclusive with (cannot be given at the same time as)
@option{--refimgs}.
+This catalog should have RA, Dec and Magnitude of the stars (that match with
Gaia or @option{--starcat}).
@item -C STR/INT
@itemx --refcathdu=STR/INT
The HDU/extension of the reference catalog will be calculated.
@item -r STR
-@itemx --racolumn=STR
+@itemx --refcatra=STR
Right Ascention column name of the reference catalog.
@item -d STR
-@itemx --deccolumn=STR
+@itemx --refcatdec=STR
Declination column name of the reference catalog.
@item -m STR
-@itemx --magcolumn=STR
+@itemx --refcatmag=STR
Magnitude column name of the reference catalog.
-@item -R STR,[STR]
-@itemx --refimgs=STR,[STR]
-Reference image or images which based on the zeropoint of the input image will
be estimated.
-
@item -s FLT
@itemx --matchradius=FLT
-Matching radius in arc seconds.
-The searching distance to match sources with the reference catalog.
-By default it is 0.2 arcsec.
+Matching radius of stars (in arc seconds) and reference catalog in arc-seconds.
+By default it is 0.2 arc seconds.
-@item -z FLT,[FLT]
-@itemx --referencezp=FLT,[FLT]
-Zeropoint of the reference image or images.
-The number of this should be the same as the number of referene image(s).
+@item -R STR,[STR]
+@itemx --refimgs=STR,[STR]
+Reference image(s) for estimating the zero point.
+This option can take any number of separate file names, separated by a comma.
+The HDUs of each reference image should be given to the @option{refimgshdu}
option.
+In case the images are in separate HDUs of the same file, you need to repeat
the file name here.
+This option is mutually exclusive with (cannot be given at the same time as)
@option{--refimgs}.
@item -H STR/INT
@itemx --refimgshdu=STR/INT
HDU/Extension name of number of the reference files.
-The number of this should be the same as the number of referene image(s).
-
-@item -a FLT,[FLT]
-@itemx --aperarcsec=FLT,[FLT]
-The size of aperture based on the arc seconds.
+The number of values given to this option should be the same as the number of
reference image(s).
-@item -M FLT,FLT
-@itemx --magnituderange=FLT,FLT
-Range of the magnitude for finding the best aperture and zero point.
+@item -z FLT,[FLT]
+@itemx --refimgszp=FLT,[FLT]
+Zeropoint of the reference image(s).
+The number of values given to this should be the same as the number of names
given to @option{--refimgs}.
@item -K
@itemx --keepzpap
-Keep zeropoint of each aperture in different extension.
+Keep the table of separate zero points found for each star for all apertures.
+By default, this table is only present for the aperture that had the least
standard deviation in the estimated zeropoint.
@item -t
@itemx --tmpdir
@@ -30060,15 +30385,6 @@ However, if you would like to keep the intermediate
files, you can use the @opti
@itemx --keeptmp
Its recommended to not remove the temporary directory (see description of
@option{--keeptmp}).
This option is useful for debugging and checking the outputs of internal steps.
-
-@item -j
-@itemx --jobs
-This option allow to the user do N jobs at same time.
-
-@item -o STR
-@itemx --output=STR
-The output contains the best aperture and the zeropoint.
-
@end table
@@ -30231,16 +30547,16 @@ By default, its value is @code{gaia --dataset=dr3}
(so it connects to the Gaia d
For example, if you want to use VizieR's Gaia DR3 instead (for example due to
a mtainenance on ESA's Gaia servers), you should use @option{--dataset="vizier
--dataset=gaiadr3"}.
It is possible to specify a different dataset from which the catalog is
downloaded.
-In that case, the necessary column names may also differ, so you also have to
set @option{--racolumn}, @option{--deccolumn} and @option{--field}.
+In that case, the necessary column names may also differ, so you also have to
set @option{--refcatra}, @option{--refcatdec} and @option{--field}.
See their description for more.
@item -r STR
-@itemx --racolumn=STR
+@itemx --refcatra=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 default value is assumed to be
@code{ra}.
@item -d STR
-@itemx --deccolumn=STR
+@itemx --refcatdec=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 default value is assumed to be
@code{dec}.
@@ -42716,7 +43032,7 @@ $ ./pgdemoXX
@node GNU Free Doc License, GNU General Public License, Other useful software,
Top
-@appendix GNU Free Doc License
+@appendix GNU Free Doc. License
@cindex GNU Free Documentation License
@include fdl.texi
- [gnuastro-commits] master 069e12f4 24/39: Zeropoint: a bug about the matching of reference and main catalog, (continued)
- [gnuastro-commits] master 069e12f4 24/39: Zeropoint: a bug about the matching of reference and main catalog, Mohammad Akhlaghi, 2023/04/19
- [gnuastro-commits] master c4af3dfc 25/39: Book: tutorial of zero point; completing the catalog reference, Mohammad Akhlaghi, 2023/04/19
- [gnuastro-commits] master 536052fb 35/39: astscript-zeropoint: writting all receipes as in one shell, Mohammad Akhlaghi, 2023/04/19
- [gnuastro-commits] master 96137885 09/39: Zeropoint: keep Mag-vs-Zeropoint for best aperture in output, Mohammad Akhlaghi, 2023/04/19
- [gnuastro-commits] master 151e8bfc 20/39: Book: editing zero point estimation section, Mohammad Akhlaghi, 2023/04/19
- [gnuastro-commits] master 85a5ad67 21/39: zeropoint: using single equal instead of the double for checking, Mohammad Akhlaghi, 2023/04/19
- [gnuastro-commits] master ea82d80a 29/39: Book: Use suggestive instead of imperative word, Mohammad Akhlaghi, 2023/04/19
- [gnuastro-commits] master 4bf867d3 26/39: Book: open imge by 'zscale' scale and options are written as code format, Mohammad Akhlaghi, 2023/04/19
- [gnuastro-commits] master 3cc85d96 34/39: astscript-zeropoint: new option --matchradius added, Mohammad Akhlaghi, 2023/04/19
- [gnuastro-commits] master 83e74d09 38/39: astscript-zeropoint: the name of some options are modified, Mohammad Akhlaghi, 2023/04/19
- [gnuastro-commits] master 21cd71bf 39/39: astscript-zeropoint: edits for merging into master branch,
Mohammad Akhlaghi <=
- [gnuastro-commits] master 0fabd68e 30/39: Zeropoint: add an option for doing many jobs and check overlapping, Mohammad Akhlaghi, 2023/04/19
- [gnuastro-commits] master 0e982706 33/39: astscript-zeropoint: polishing and improving the comments of the scripts, Mohammad Akhlaghi, 2023/04/19
- [gnuastro-commits] master fcf00960 37/39: astscript-zeropoint: Content of temorary file have been removed, Mohammad Akhlaghi, 2023/04/19