%% Copyright (C) 2018-2023 Mohammad Akhlaghi <mohammad@akhlaghi.org>
%% See the end of the file for license conditions.
\documentclass[preprint2, times, twocolappendix]{aastex631}

%% (OPTIONAL) CONVENIENCE VARIABLE: Only relevant when you use Maneage's
%% '\includetikz' macro to build plots/figures within LaTeX using TikZ or
%% PGFPlots. If so, when the Figure files (PDFs) are already built, you can
%% avoid TikZ or PGFPlots completely by commenting/removing the definition
%% of '\makepdf' below. This is useful when you don't want to slow-down a
%% LaTeX-only build of the project (for example this happens when you run
%% './project make dist'). See the definition of '\includetikz' in
%% 'tex/preamble-pgfplots.tex' for more.
\newcommand{\makepdf}{}

%% VALUES FROM ANALYSIS (NUMBERS AND STRINGS): this file is automatically
%% generated at the end of the processing and includes LaTeX macros
%% (defined with '\newcommand') for various processing outputs to be used
%% within the paper.
\input{tex/build/macros/project.tex}

%% MANEAGE-ONLY PREAMBLE: this file contains LaTeX constructs that are
%% provided by Maneage (for example enabling or disabling of highlighting
%% from the './project' script). They are not style-related.
\input{tex/src/preamble-maneage.tex}

%% PROJECT-SPECIFIC PREAMBLE: This is where you can include any LaTeX
%% setting for customizing your project.
\input{tex/src/preamble-project.tex}










%% Start creating the paper.
\begin{document}

%% Title
\title{\projecttitle}






\author[0000-0002-6672-1199]{Sepideh Eskandarlou}
\affiliation{Centro de Estudios de F\'isica del Cosmos de Arag\'on (CEFCA), Plaza San Juan 1, 44001 Teruel, Spain}

\correspondingauthor{Sepideh Eskandarlou}
\email{sepideh.eskandarlou@gmail.com}

\author[0000-0003-1710-6613]{Mohammad Akhlaghi}
\affiliation{Centro de Estudios de F\'isica del Cosmos de Arag\'on (CEFCA), Plaza San Juan 1, 44001 Teruel, Spain}

\author[0000-0002-6220-7133]{Ra\'ul Infante-sainz}
\affiliation{Centro de Estudios de F\'isica del Cosmos de Arag\'on (CEFCA), Plaza San Juan 1, 44001 Teruel, Spain}

\author[0000-0002-5075-1764]{Elham Saremi}
\affiliation{Instituto de Astrof\'isica de Canarias, Calle V\'ia L\'actea s/n, 38205 La Laguna, Spain}
\affiliation{Departamento de Astrof\'isica, Universidad de La Laguna, 38205 La Laguna, Spain}
\affiliation{School of Physics \& Astronomy, University of Southampton, Highfield Campus, Southampton SO17 1BJ, UK}

\author[0000-0001-9000-5507]{Samane Raji}
\affiliation{Dept. of Theoretical and Atomic Physics, and Optics, University of Valladolid, Spain}

\author[0009-0004-5054-5946]{Zahra Sharbaf}
\affiliation{Instituto de Astrof\'isica de Canarias, Calle V\'ia L\'actea s/n, 38205 La Laguna, Spain}
\affiliation{Departamento de Astrof\'isica, Universidad de La Laguna, 38205 La Laguna, Spain}

\author[0009-0001-2377-272X]{Giulia Golini}
\affiliation{Instituto de Astrof\'isica de Canarias, Calle V\'ia L\'actea s/n, 38205 La Laguna, Spain}
\affiliation{Departamento de Astrof\'isica, Universidad de La Laguna, 38205 La Laguna, Spain}

\author[0000-0002-6467-8078]{Zohre Ghaffari}
\affiliation{Instituto de Astrof\'isica de Canarias, Calle V\'ia L\'actea s/n, 38205 La Laguna, Spain}
\affiliation{Departamento de Astrof\'isica, Universidad de La Laguna, 38205 La Laguna, Spain}
\affiliation{INAF-Osservatorio Astronomico di Trieste, via G.B. Tiepolo, 11-I-34143 Trieste, Italy}

\author[0000-0003-1643-0024]{Johan H. Knapen}
\affiliation{Instituto de Astrof\'isica de Canarias, Calle V\'ia L\'actea s/n, 38205 La Laguna, Spain}
\affiliation{Departamento de Astrof\'isica, Universidad de La Laguna, 38205 La Laguna, Spain}





%% Abstract
\begin{abstract}
  \noindent
Calibration of pixel values is a fundamental step for accurate measurements in astronomical imaging.
In astronomical jargon this is known as estimating zero point magnitude.
Here, we introduce a newly added script in GNU Astronomy Utilities (Gnuastro) version 0.20 for the zero point magnitude estimation, named: \texttt{astscript-zeropoint}.
The script offers numerous features, such as the flexibility to use either image(s) or a catalog as the reference dataset.
Additionally, steps are parallelized to enhance efficiency for big data.
Thanks to Gnuastro's minimal dependencies, the script is both flexible and portable.
The figures of this research note are reproducible with Maneage, on the Git commit \projectversion.
\end{abstract}

%% Keywords (from https://astrothesaurus.org)
\keywords{Flux calibration (544), Astronomy software (1855), Open source software (1866), Astronomical techniques (1684)}









%% Start of main body.
\section{Introduction}\label{sec:intro}
\noindent
Scientific measurements of astronomical sources are not possible without reduction and calibration of the raw data.
In astronomical imaging, the calibration of pixel values is done through the \emph{zero point} magnitude which allows the conversion of the pixel value units to physical (for example SI or CGS) units.
It encodes all the instrument-specific and observational factors into a single number.
Therefore, after accounting for the zeropoint, measurements like flux, brightness, and other parameters can be compared with other measurements from different telescopes and instruments.
This allows the use of the data for higher-level analysis, for instance, measuring the galaxy's stellar masses or spectral energy distribution fitting.

In this research note, we introduce a new script in charge of computing the zero point magnitude of astronomical images with the executable name of `\texttt{astscript-zeropoint}'.
It performs this by aperture photometry of stars in the image and comparing them with already calibrated datasets: image(s) or a catalog.
This script was introduced into GNU Astronomy Utilities, or Gnuastro\footnote{\url{https://www.gnu.org/software/gnuastro}} \citep{gnuastro2015,gnuastro2019} since version 0.20.
Earlier versions of this script have been used by other research projects such as \citet{trujillo2021} and \citet{martinez2021}.



\section{Computing the zero point magnitude}\label{sec:computezp}

The `\texttt{astscript-zeropoint}' script requires reference image(s) or a catalog that should be calibrated and overlap with the image on the sky.
This reference data is used as the basis to compare the aperture photometry conducted by the script.
The basic steps performed internally by the script are:

\begin{itemize}
 \item Query the Gaia \citep{gaia2016} catalog to obtain accurate coordinates of stars in an input image.
 \item Perform aperture photometry considering different aperture sizes.
 \item For each aperture and each star, compute the difference in magnitude with respect to the reference magnitude of that star ($\delta_{a,s}$).
Setting the input zero point magnitude to zero.
\item Compute the zero point magnitude for each aperture ($z_a$) from the sigma-clipped median of the $\delta_{a,s}$ distribution for all stars.
  This can be either from the full sample, or optionally, in a specified magnitude range (to avoid the noisy faint stars and bright saturated stars).
 \item The final zero point magnitude is the $z_a$ with smallest scatter (sigma-clipped standard deviation, $\sigma$, of the $\delta_{a,s}$ distribution).
\end{itemize}

Depending on the reference data (images or a catalog), the execution of the script is slightly different: the former requires generation of a catalog through aperture photometry.
A tutorial on the usage of both scenarios is available in the Tutorials chapter\footnote{\url{https://www.gnu.org/software/gnuastro/manual/html_node/Tutorials.html}} of the manual.
The tutorial includes examples in both scenarios (of using references images or a catalog).

\begin{figure*}[!t]
  \begin{center}
  \includetikz{fig-zp}{width=\linewidth}
  \caption{\label{fig:refimg} Difference in magnitude (using apertures of radius {\figapermin}$^{\prime\prime}$ and {\figapermax}$^{\prime\prime}$) as a function of the reference magnitude for stars in the input image.
    The horizontal range of this plot shows the zero point magnitude and its scatter.
    In both cases SDSS DR12 is used as a reference: the left panel uses an SDSS image and right uses on the SDSS catalog overlapping with our input image.
    In right panel (from a catalog), stars brighter than the 15th magnitude are present because the SDSS pipeline attempts to find the magnitude of saturated stars (which is not done in the left panel).
    The blue and yellow filled circles have a smaller dispersion ($\sigma$ in legend).
    The zero point magnitudes are obtained based on the horizontal component of the blue and yellow filled circles with lower $\sigma$ (within the magnitude range that is shown with the red vertical lines).
    The underlying data for creating the left and right panels are available in \href{http://doi.org/10.5281/zenodo.10256845}{zenodo:10256845} (files with the \texttt{.txt} suffix).}
  \end{center}
\end{figure*}


Figure \ref{fig:refimg} shows the difference in magnitude of apertures as a function of the reference magnitude (calulcated from apertures in images and taken directly from the catalog) with lowest and highest $\sigma$.
The input image is from J-PLUS \citep{cenarro19}.
The ultimate zero point magnitude comes from the aperture with least scatter in the magnitude range between {\figmagmin} to {\figmagmax} for this particular example.
For instance in the examples of Figure \ref{fig:refimg} the apertures with radius {\figbestaper} arc-seconds have smallest $\sigma$ with zeropoint of {\zptwoimg} and {\zptwocat} using reference images and catalog respectively.
The break at brighter magnitudes (between magnitudes {\figmagsplittwominsdss} to {\figmagsplittwomaxsdss}) that we see in the reference catalog plot is created because SDSS models the central parts of saturated stars in its catalog.
More details and complete information on all run-time options of this script can be found under the ``Invoking astscript-zeropoint'' section\footnote{\url{https://www.gnu.org/software/gnuastro/manual/html\_node/Invoking-astscript\_002dzeropoint.html}} of Gnuastro's manual.

\section{Acknowledgement}
We gratefully acknowledge Ignacio Trujillo for discussions that improved the script.

The workflow of this research note was developed in the reproducible framework of Maneage \citep[\emph{Man}aging data lin\emph{eage},][latest Maneage commit \maneageversion{}, from \maneagedate]{maneage}.
This note is created from the Git commit {\projectversion} that is hosted on Codeberg\footnote{In the \texttt{zeropoint} branch of \url{\projectgitrepo}} and is archived on SoftwareHeritage\footnote{\href{https://archive.softwareheritage.org/swh:1:dir:ba1db3aacab2f24cba4beb85566aa446803c6748;origin=https://codeberg.org/gnuastro/papers;visit=swh:1:snp:83d202bb7a4f0a436bb1f2efe304b564812cee8a;anchor=swh:1:rev:18d12b01abcc89e8d1e500a95c3574ccf19fd941}{swh:1:dir:ba1db3aacab2f24cba4beb85566aa446803c6748} Software Heritage identifiers (SWHIDs) can be used with resolvers like \texttt{http://n2t.net/} (e.g., \texttt{http://n2t.net/swh:1:...}). Clicking on the SWHIDs will provide more “context” for same content} for longevity.

The analysis of this research note was done using Gnuastro (ascl.net/1801.009) version \gnuastroversion. Work on Gnuastro has been funded by the Japanese Ministry MEXT scholarship and its Grant-in-Aids 21244012 and 24253003, ERC 339659-MUSICOS, the Spanish grants AYA2016-76219-P and PID2021-124918NA-C43 as well as the NextGenerationEU ICTS-MRR-2021-03-CEFCA.



%% Bibliography
\bibliography{references}{}
\bibliographystyle{aasjournal}

%% Finish LaTeX
\end{document}