path: root/paper.tex

%% Copyright (C) 2018-2019 Mohammad Akhlaghi.
%% 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}

%% Abstract, keywords and reproduction pipeline notice.
\includeabstract{

  You have completed the reproduction pipeline and are ready to configure
  and implement it for your own research. This template reproduction
  pipeline and document contains almost all the elements that you will need
  in a research project containing the downloading of raw data, processing
  it, including them in plots and report, including this abstract, figures
  and bibliography. If you use this pipeline in your work, don't forget to
  add a notice to clearly let the readers know that your work is
  reproducible. If this pipeline proves useful in your research, please
  cite \citet{ai15}.

  \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 with reproduction pipeline
  \pipelineversion{}
  (\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 reproduction pipeline! You can now follow
the checklist in the \texttt{README.md} file to customize this pipeline 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 outputs of the
programs as part of the reproduction pipeline and import them into \LaTeX{}
as macros through the \texttt{tex/pipeline/macros/pipeline.tex} file
(created after running the pipeline). See the several examples within the
pipeline for a demonstration. For some recent real-world examples, the
reproduction pipelines 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 reproduction
pipeline. 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 pipeline 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
reproduction pipeline, so until then, we would be grateful if you could
cite the first paper that used the first version of this pipeline:
\citet{ai15}.

After publication, don't forget to upload all the necessary data, software
source code and the reproduction pipeline 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 reproduction pipeline was developed in
  parallel with Gnuastro, so it benefited from the same grants. If you
  don't use any of these packages in the final/customized pipeline, please
  remove them. }

This research was partly done using GNU Astronomy Utilities (Gnuastro,
ascl.net/1801.009), and reproduction pipeline \pipelineversion. Work on
Gnuastro and the reproduction pipeline 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/pipeline/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/>.