path: root/paper.tex

%% Copyright (C) 2018-2019 Mohammad Akhlaghi <mohammad@akhlaghi.org>
%% See the end of the file for license conditions.
\documentclass[10pt, twocolumn]{article}

%% This is a convenience variable if you are using PGFPlots to build plots
%% within LaTeX. If you want to import PDF files for figures directly, you
%% can use the standard `\includegraphics' command. See the definition of
%% `\includetikz' in `tex/preamble-pgfplots.tex' for where the files are
%% assumed to be if you use `\includetikz' when `\makepdf' is not defined.
\newcommand{\makepdf}{}

%% When defined (value is irrelevant), `\highlightchanges' will cause text
%% in `\tonote' and `\new' to become colored. This is useful in cases that
%% you need to distribute drafts that is undergoing revision and you want
%% to hightlight to your colleagues which parts are new and which parts are
%% only for discussion.
\newcommand{\highlightchanges}{}

%% Necessary LaTeX preambles to include for relevant functionality. We want
%% to start this file as fast as possible with the actual body of the
%% paper, while keeping modularity in the preambles.
\input{tex/src/preamble-style.tex}
\input{tex/src/preamble-header.tex}
\input{tex/src/preamble-biblatex.tex}
\input{tex/src/preamble-pgfplots.tex}
\input{tex/src/preamble-necessary.tex}










%% Start writing.
\begin{document}

%% Project abstract and keywords.
\includeabstract{

  You have completed the reproducible paper template and are ready to
  configure and implement it for your own research. This template contains
  almost all the elements that you will need in a research project
  containing the downloading of raw data and necessary software, building
  the software, and processing the data with the software in a
  highly-controlled environment. It then allows including the results in
  plots and producing the final report, including this abstract, figures
  and bibliography. If you design your project with this template's
  infra-structure in your work, don't forget to add a notice and clearly
  let the readers know that your work is reproducible. If this template
  proves useful in your research, please cite \citet{gnuastro}.

  \vspace{0.25cm}

  \textsl{Keywords}: Add some keywords for your research here.

  \textsl{Reproducible paper}: All quantitave results (numbers and plots)
  in this paper are exactly reproducible (version \projectversion{},
  \url{https://gitlab.com/makhlaghi/reproducible-paper}).}

%% To add the first page's headers.
\thispagestyle{firststyle}





%% Start of the main body of text.
\section{Congratulations!}
Congratulations on running the raw template project! You can now follow the
checklist in the \texttt{README.md} file to customize this template to your
exciting research project.

Just don't forget to \emph{never} use numbers or fixed strings (for example
database urls like \url{\wfpctwourl}) directly within your \LaTeX{}
source. Read them directly from your configuration files, or processing
outputs, and import them into \LaTeX{} as macros through the
\texttt{tex/build/macros/project.tex} file (created after running the
project). See the several existing examples within the template for a
demonstration. For some recent real-world examples, the reproducible
project sources for Sections 4 and 7.3 of \citet{bacon17} are available at
\href{https://doi.org/10.5281/zenodo.1164774}{zenodo.1164774}\footnote{\url{https://gitlab.com/makhlaghi/muse-udf-origin-only-hst-magnitudes}},
or
\href{https://doi.org/10.5281/zenodo.1163746}{zenodo.1163746}\footnote{\url{https://gitlab.com/makhlaghi/muse-udf-photometry-astrometry}}. Working
in this way, will let you focus clearly on your science and not have to
worry about fixing this or that number/name in the text.

Figure \ref{delete-me} shows a simple plot as a demonstration of creating
plots within \LaTeX{} (using the {\small PGFP}lots package). The minimum
value in this distribution is $\deletememin$, and $\deletememax$ is the
maximum. Take a look into the \LaTeX{} source and you'll see these numbers
are actually macros that were calculated from the same dataset (they will
change if the dataset, or function that produced it, changes).

The individual {\small PDF} file of Figure \ref{delete-me} is available
under the \texttt{tex/build/tikz/} directory of your build directory. You
can use this PDF file in other contexts (for example in slides showing your
progress or after publishing the work). If you want to directly use the
{\small PDF} file in the figure without having to let {\small T}i{\small
  KZ} decide if it should be remade or not, you can also comment the
\texttt{makepdf} macro at the top of this \LaTeX{} source file.

\begin{figure}[t]
  \includetikz{delete-me}

  \captionof{figure}{\label{delete-me} A very basic $X^2$ plot for
    demonstration.}
\end{figure}

Figure \ref{delete-me-demo} is another demonstration of showing images
(datasets) using PGFPlots. It shows a small crop of an image from the
Wide-Field Planetary Camera 2, on board the Hubble Space Telescope from
1993 to 2009. This cropped image is one of the sample FITS files from the
FITS file standard
webpage\footnote{\url{https://fits.gsfc.nasa.gov/fits_samples.html}}. Just
as another basic reporting of measurements on this dataset within the paper
without using numbers in the \LaTeX{} source, the mean is
$\deletemewfpctwomean$ and the median is $\deletemewfpctwomedian$. The
skewness in the histogram of Figure \ref{delete-me-demo}(b) explains this
difference between the mean and median. The dataset was prepared for
demonstration here with Gnuastro's \textsf{Convert\-Type} program and the
histogram and basic statstics were generated with Gnuastro's
\textsf{Statistics} program.

{\small PGFP}lots\footnote{\url{https://ctan.org/pkg/pgfplots}} is a great
tool to build the plots within \LaTeX{} and removes the necessity to add
further dependencies (to create the plots) to your project. There are
high-level language libraries like Matplotlib which also generate
plots. However, the problem is that they require many dependencies (Python,
Numpy and etc). Installing these dependencies from source, is not easy and
will harm the reproducibility of your paper. Note that after several years,
the binary files of these high-level libraries, that you easily install
today, will no longer be available in common repositories. Therefore
building the libraries from source is the only option to reproduce your
results.

Furthermore, since {\small PGFP}lots is built by \LaTeX{} it respects all
the properties of your text (for example line width and fonts and
etc). Therefore the final plot blends in your paper much more nicely. It
also has a wonderful
manual\footnote{\url{http://mirrors.ctan.org/graphics/pgf/contrib/pgfplots/doc/pgfplots.pdf}}.

This template also defines two \LaTeX{} macros that allow you to mark text
within your document as \emph{new} and \emph{notes}. For example, \new{this
  text has been marked as \texttt{new}.} \tonote{While this one is marked
  as \texttt{tonote}.} If you comment the line (by adding a `\texttt{\%}'
at the start of the line or simply deleting the line) that defines
\texttt{highlightchanges}, then the one that was marked \texttt{new} will
become black (totally blend in with the rest of the text) and the one
marked \texttt{tonote} will not be in the final PDF. You can thus use
\texttt{highlightchanges} to easily make copies of your research for
existing coauthors (who are just interested in the new parts or notes) and
new co-authors (who don't want to be distracted by these issues in their
first time reading).

\begin{figure}[t]
  \includetikz{delete-me-demo}

  \captionof{figure}{\label{delete-me-demo} (a) An example image of the
    Wide-Field Planetary Camera 2, on board the Hubble Space Telescope from
    1993 to 2009. This is one of the sample images from the FITS standard
    webpage, kept as examples for this file format. (b) Histogram of pixel
    values in (a).}
\end{figure}



\section{Notice and citations}
To encourage other scientists to publish similarly reproducible papers,
please add a notice close to the start of your paper or in the end of the
abstract clearly mentioning that your work is fully reproducible.

For the time being, we haven't written a specific paper only for this
template. Until then, we would be grateful if you could cite the first
paper that used the early versions of this template: \citet{gnuastro}.

After publication, don't forget to upload all the necessary data, software
source code and the project's source to a long-lasting host like Zenodo
(\url{https://zenodo.org}).





\section{Acknowledgements}
\new{Please include the following two paragraphs in the Acknowledgement
  section of your paper. This reproducible paper template was developed in
  parallel with Gnuastro, so it benefited from the same grants. If you
  don't use Gnuastro in your final/customized project, please remove it
  from the paragraph below, only mentioning the reproducible paper
  template.}

This research was partly done using GNU Astronomy Utilities (Gnuastro,
ascl.net/1801.009), and the reproducible paper template
\projectversion. Work on Gnuastro and the reproducible paper template 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, European Union’s Horizon 2020 research
and innovation programme under Marie Sklodowska-Curie grant agreement No
721463 to the SUNDIAL ITN, and from the Spanish Ministry of Economy and
Competitiveness (MINECO) under grant number AYA2016-76219-P.

\input{tex/build/macros/dependencies.tex}

%% Tell BibLaTeX to put the bibliography list here.
\printbibliography

%% Finish LaTeX
\end{document}

%% This file is part of the reproducible paper template
%%   https://gitlab.com/makhlaghi/reproducible-paper
%
%% This template 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 template 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 Template.  If not, see <https://www.gnu.org/licenses/>.