aboutsummaryrefslogtreecommitdiff
path: root/paper.tex
blob: 24cadf0190b00d0c1a9e07f897f8d6ed248b1000 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
%% 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{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/>.