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}

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

%% (OPTIONAL) CONVENIENCE VARIABLE: Only relevant when
%% 'tex/src/preamble-necessary.tex' is included (in particular the small
%% patch relating to '\highlightchanges'). In there, Maneage defines two
%% macros: `\tonote' and `\new'. When '\highlightchanges' is defined (value
%% is irrelevant), the text in those two macros becomes colored (in the
%% former, the text becomes dark red, in the latter it becomes dark
%% green). When not defined, text in the former isn't printed in the output
%% at all, and text in the latter becomes the same color as the rest of the
%% text. This is useful in cases that you need to distribute drafts and you
%% want to hightlight the new parts and add notes in the middle of the text
%% only for discussion, and build a clean PDF without any such highlights
%% without modifying the text.
\newcommand{\highlightchanges}{}

%% VALUES FROM ANALYSIS (NUMBERS AND STRINGS): these are automatically
%% generated by the analysis phase of the project. The files loaded by
%% 'project.tex' only contain macro definitions (with '\newcommand') and
%% nothing else. So they won't interfere with any LaTeX style and can be
%% safely used in any pre-defined style.
\input{tex/build/macros/project.tex}

%% CUSTOM PREAMBLES FOR DEMO: You can remove them if you are using a
%% specific journal style, or don't need features like BibLaTeX (advanced
%% bibliography management) or PGFPlots (for drawing plots within LaTeX
%% directly from tables of data). If you don't need them, you can also
%% delete their files from your branch to keep the 'tex/src' directory on
%% your branch clean.
\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}

%% PROJECT TITLE: The project title should also be printed as metadata in
%% all output files. To avoid inconsistancy caused by manually typing it,
%% the title is defined with other core project metadata in
%% 'reproduce/analysis/config/metadata.conf'. That value is then written in
%% the '\projectitle' LaTeX macro by
%% 'reproduce/analysis/make/initialize.mk' and is directly used here. So
%% please set your project's title in 'metadata.conf' (ideally with other
%% basic project information) and re-run the project to have your new
%% title. If you later use a different LaTeX style, please use the same
%% '\projectitle' in it (after importing 'tex/build/macros/project.tex'
%% like above), don't type it by hand.
\title{\large \uppercase{\projecttitle}}

%% 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 set the authors in a different way,
%% feel free to change them here, this part is not related to the analysis.
\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{maneage}. 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{maneage}, 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{maneage}\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{maneage}

Finally, don't forget to cite \citet{maneage} 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{Acknowledgments}
\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 project was developed in the reproducible framework of Maneage
\citep[\emph{Man}aging data lin\emph{eage},][over commit
  \maneageversion]{maneage}. Maneage has been funded partially by the
following grants: Japanese Ministry of Education, Culture, Sports, Science,
and Technology (MEXT) PhD scholarship to M. Akhlaghi and its Grant-in-Aid
for Scientific Research (21244012, 24253003). The European Research Council
(ERC) advanced grant 339659-MUSICOS. The European Union (EU) Horizon 2020
(H2020) research and innovation programmes No 777388 under RDA EU 4.0
project, and Marie Sk\l{}odowska-Curie grant agreement No 721463 to the
SUNDIAL ITN. The State Research Agency (AEI) of the Spanish Ministry of
Science, Innovation and Universities (MCIU) and the European Regional
Development Fund (ERDF) under the grant AYA2016-76219-P. The IAC project
P/300724, financed by the MCIU, through the Canary Islands Department of
Economy, Knowledge and Employment.

%% 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/>.