%% 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}

%% Authors
\author[0000-0003-1710-6613]{Mohammad Akhlaghi}
\affiliation{Centro de Estudios de Física del Cosmos de Aragón (CEFCA), Plaza San Juan 1, 44001, Teruel, Spain; \href{mailto:mohammad@akhlaghi.org}{mohammad@akhlaghi.org}}

%% Abstract
\begin{abstract}
  \noindent
  The pointing pattern is an integral part of designing one's observation strategy for a certain scientific goal.
  But accounting for the particular science case or instrument artifacts (like distortion, vignetting or large areas of bad pixels) can make it hard to predict how the exposure map of the final stack will be.
  To help address this problem, Gnuastro 0.21 includes a new executable program called \texttt{astscript-pointing-simulate} that is fully described in the Gnuastro manual and comes with a complete tutorial.
  The figures of this research note are reproducible with Maneage, on the Git commit \projectversion.
\end{abstract}

%% Keywords (from https://astrothesaurus.org)
\keywords{Astronomical methods (1043), Field of view (534), Direct imaging (387), Astronomical techniques (1684), Astronomy software (1855)}










%% Start of main body.
\section{Introduction}\label{sec:intro}
\noindent
Astronomical images are often composed of many single exposures.
After completing the observations, when the science topic does not depend on the time of observation, we stack those single exposures into one deep \emph{stacked} image (also known as \emph{coadd}).
Designing the strategy to take those single exposures is therefore a very important aspect of planning an astronomical observation.

Each exposure has a \emph{pointing} (the location on the sky that it was targeting).
Subsequent exposures are usually taken with different pointings.
When the next pointing is very near (a small fraction of the field of view) to the previous one, it is known as a \emph{dither} (literally/generally meaning trembling or vibration).
But when the distance between subsequent pointings is large (and issues like re-focusing become necessary), the pointing is known as an \emph{offset}.
These terms are sometimes used interchangably by some.

When we only have dithers, most of the central part of the final stack has a fixed depth.
Only a thin border becomes shallower (conveying a sense of vibration!).
For example see Figures 3 and 4 of \citet{xdf} which show the exposures that went into the XDF survey.
These types of images (where each pixel contains the number of exposures, or time, that were used in it) are known as exposure maps.
However, it can happen that only offsets are used.
For example see Figure 1 of \citet{lights}, which shows the exposure map for the LIGHTS survey.

\begin{figure*}[t]
  \includetikz{fig-pointing-demo}{width=\linewidth}

  \caption{\label{fig-pointing-demo}
    Sample outputs from the tutorial on designing a pointing pattern in the manual of Gnuastro 0.21.
    Left: the exposure map of a ``+''-shaped pointing (offset) pattern with 5 exposures.
    Center: The stack of pure noise after applying the same pointing list as the left image.
    Right: Exposure map of same dither pattern as the left image, but with trimming of the outer pixels in each exposure (this usually happens due to vignetting).
    The color map used shows the largest values as white/red and the smallest values as black/blue.
  }
\end{figure*}

The dithering pattern therefore is strongly defined by the science case (high-level purpose of the observation) and your telescope's field of view.
For example in the HUDF, CANDELS and other proposals (that constitute the XDF), the scientific target was high redshift (distant) galaxies.
When counting the pixels that they cover in relation to the number of pixels in each exposure, these targets are very small objects.
Such that within that small footprint (of just 1 arcminute!) we have thousands of such small objects (which may also be stars or nearby galaxies of similar observed size to the high redshift galaxies).
Therefore for the scientific goal of the XDF, the very small dithers were sufficient to avoid instrument artifacts.

However, the LIGHTS survey is focused on the halos of large nearby galaxies (that can be more than 10 arcminutes wide); thus covering a large fraction of the field of view of the Large Binocular Telescope that was used.
In order to do robust calibration of the images (for example to estimate the flat field pattern, or the sky background level) it was necessary to have offsets.
This enabled the galaxy and its halo to cover very different pixels from one exposure to the next.

In other cases, the pointings include both offsets and dithers (around each offset).
To find the ideal dither pattern for the particular scientific goal, it therefore helps to be able to simulate various strategies.
In the next section, an installed script is introduced for this purpose (to simulate the exposure map of a series of pointings) in GNU Astronomy Utilities \citep[Gnuastro][]{gnuastro} version\footnote{This paper is published shortly before the release of Gnuastro 0.21.
If Gnuastro 0.21 is not yet available, please use the latest test (alpha) release.} 0.21 and later.

\section{Simulating the exposure map}
Within Gnuastro, the executable in charge of simulating the exposure map of a given list of pointings is called \texttt{astscript\--pointing\--simulate}.
As with all Gnuastro features, it has a complete documentation in Gnuastro's manual\footnote{\url{https://www.gnu.org/software/gnuastro/manual}} which is available in many formats (on the command-line, as web pages, PDF and etc).
A complete and dedicated tutorial is also available within the tutorials chapter\footnote{\url{https://www.gnu.org/software/gnuastro/manual/html_node/Tutorials.html}} of the manual.

Three of the images produced in the tutorial (as of version 0.21) are displayed in Figure \ref{fig-pointing-demo}.
The left image shows the exposure map that is produced from a five-point, ``+''-shaped set of pointings on the sky, with one pointing in the center and four on the outer extents.
The middle image uses one of the \emph{hooks} that are available within the script to produce a noisy image and not an exposure map.
This hook can also be used to insert simulated/real objects.
The right image shows how another hook can be used to account for trimming of the outer edges (which sometimes do not get exposed enough due to vignetting).
This hook can also be used to insert any random area of bad pixels or to simulate persistence in near infra-red detectors (these can be large).

For its processing, this script needs two input files: 1) a table containing the RA and Dec of each pointing, 2) a FITS image from the camera that the dither pattern is meant for.
The image has to contain the celestial world coordinate system \citep[WCS, see][]{wcscelestial} headers.
Having a WCS is very important, especially for cameras with a wide field of view, because distortions can become visible/significant.

The tutorial and dedicated manual for this script are available in the Gnuastro manual and will always be up to date with the running version; therefore for the practical details, we encourage readers to follow the Gnuastro manual.
The future changes in the script that break with this research note will be clearly designated in a ``changes after publication'' subsection of the section describing this script.

\section{Acknowledgement}
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{\url{\projectgitrepo}} and is archived on SoftwareHeritage for longevity.

The analysis of this research note was done using GNU Astronomy Utilities (Gnuastro, ascl.net/1801.009) version \gnuastroversion. 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.

I also acknowledge the financial support provided by the Governments of Spain and Arag\'on through their general budgets and the Fondo de Inversiones de Teruel, and the Spanish Ministry of Science and Innovation (MCIN/AEI/10.13039/501100011033 y FEDER, Una manera de hacer Europa) with grant PID2021-124918NA-C43.

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

%% Start appendix.
\appendix
\section{Software acknowledgement}
\label{appendix:software}
\input{tex/build/macros/dependencies.tex}


%% Finish LaTeX
\end{document}

%% This file is part of Maneage (https://maneage.org).
%
%% This file 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.
%
%% This file 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 file.  If not, see <http://www.gnu.org/licenses/>.