path: root/paper.tex

%% Copyright (C) 2018-2020 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}

%% Title and author information. For a more fine-grained control of the
%% headers including author name, or paper info, see
%% `tex/src/preamble-header.tex'. Note that if you plan to use a journal's
%% LaTeX style file, you will probably not need to set them, and can also
%% replace this "Title and author information" section with the journal's
%% preferred format.
%
%% NOTE ON TITLE: The title of the project should also be printed as
%% metadata in all output files. So it is defined with other core project
%% metadata in 'reproduce/analysis/config/metadata.conf'. That value is
%% then written in the '\projectitle' LaTeX macro and directly used
%% here. So please set your project's title in that Makefile with other
%% basic information.
\title{\large \uppercase{\projecttitle}}
\author[1]{Your name}
\author[2]{Coauthor one}
\author[1,3]{Coauthor two}
\affil[1]{The first affiliation in the list.; \url{your@email.address}}
\affil[2]{Another affilation can be put here.}
\affil[3]{And generally as many affiliations as you like.
\par \emph{Received YYYY MM DD; accepted YYYY MM DD; published YYYY MM DD}}
\date{}










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

%% Project abstract and keywords.
\includeabstract{

  Welcome to Maneage (\emph{Man}aging data lin\emph{eage}) and reproducible
  papers/projects, for a review of the basics of this system, please see
  \citet{akhlaghi20}. You are now ready to configure Maneage and implement
  your own research in this framework. Maneage contains almost all the
  elements that you will need in a research project, and adding any missing
  parts is very easy once you become familiar with it. For example it
  already has steps to downloading of raw data and necessary software
  (while verifying them with their checksums), building the software, and
  processing the data with the software in a highly-controlled
  environment. But Maneage is not just for the analysis of your project,
  you will also write your paper in it (by replacing this text in
  \texttt{paper.tex}): including this abstract, figures and
  bibliography. If you design your project with Maneage's infra-structure,
  don't forget to add a notice and clearly let the readers know that your
  work is reproducible, we should spread the word and show the world how
  useful reproducible research is for the sciences, also don't forget to
  cite and acknowledge it so we can continue developing it. This PDF was
  made with Maneage, commit \projectversion{}.

  \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 Maneage
  (\url{https://maneage.org}).  }

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





%% Start of main body.
\section{Congratulations!}
Congratulations on running the raw template project! You can now follow the
``Customization checklist'' in the \texttt{README-hacking.md} file,
customize this template and start your exciting research project over
it. You can always merge Maneage back into your project to improve its
infra-structure and leaving your own project intact. If you haven't already
read \citet{akhlaghi20}, please do so before continuing, it isn't long
(just 7 pages).

While you are writing your paper, just don't forget to \emph{not} use
numbers or fixed strings (for example database urls like \url{\wfpctwourl})
directly within your \LaTeX{} source. Put them in configuration files and
after using them in the analysis, pass them into the \LaTeX{} source
through macros in the same subMakefile that used them. For some already
published examples, please see
\citet{akhlaghi20}\footnote{\url{https://gitlab.com/makhlaghi/maneage-paper}},
\citet{infantesainz20}\footnote{\url{https://gitlab.com/infantesainz/sdss-extended-psfs-paper}}
and
\citet{akhlaghi19}\footnote{\url{https://gitlab.com/makhlaghi/iau-symposium-355}}. 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.

Once your project is ready for publication, there is also a ``Publication
checklist'' in \texttt{README-hacking.md} that will guide you in the steps
to do for making your project as FAIR as possible (Findable, Accessibile,
Interoperable, and Reusable).

The default \LaTeX{} structure within Maneage also has two \LaTeX{} macros
for easy marking of 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}.} Please try commenting
the line that defines \texttt{highlightchanges} in \texttt{paper.tex} (by
adding a `\texttt{\%}' at the start of the line or simply deleting the
line). You will then notice that the line that was marked as \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).

Figure \ref{squared} 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{squared} is available under
the \texttt{tex/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-squared}{width=\linewidth}

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

Figure \ref{image-histogram} is another demonstration of showing images
(datasets) using PGFPlots. It shows a small crop of an image from the
Wide-Field Planetary Camera 2 (that was installed on the Hubble Space
Telescope from 1993 to 2009). As another more realistic demonstration of
reporting results with Maneage, here we report that the mean pixel value in
that image is $\deletemewfpctwomean$ and the median is
$\deletemewfpctwomedian$. The skewness in the histogram of Figure
\ref{image-histogram}(b) explains this difference between the mean and
median. The dataset is visualized here as a black and white image using the
\textsf{Convert\-Type} program of GNU Astronomy Utilities (Gnuastro).  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, just to create the plots. There are high-level
libraries like Matplotlib which also generate plots. However, the problem
is that they require \emph{many} dependencies, for example see Figure 1 of
\citet{alliez19}. Installing these dependencies from source, is not easy
and will harm the reproducibility of your paper in the future.

Furthermore, since {\small PGFP}lots builds the plots within \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}}.

\begin{figure}[t]
  \includetikz{delete-me-image-histogram}{width=\linewidth}

  \captionof{figure}{\label{image-histogram} (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. One
convention we have adopted until now is to put the Git checkum of the
project as the last word of the abstract, for example see
\citet{akhlaghi19}, \citet{infantesainz20} and \citet{akhlaghi20}

Finally, don't forget to cite \citet{akhlaghi20} and acknowledge the
funders mentioned below. Otherwise we won't be able to continue working on
Maneage. Also, just as another reminder, before publication, don't forget
to follow the ``Publication checklist'' of \texttt{README-hacking.md}.
%% End of main body.





\section{Acknowledgements}
\new{Please include the following two paragraphs in the Acknowledgement
  section of your paper. Maneage 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.  The
reproducible paper template was also supported by European Union’s Horizon
2020 (H2020) research and innovation programme via the RDA EU 4.0 project
(ref. GA no. 777388).

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

%% Start appendix.
\appendix

%% Mention all used software in an appendix.
\section{Software acknowledgement}
\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/>.