aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--img/build-highlighted.pngbin0 -> 418129 bytes
-rw-r--r--img/build.pngbin0 -> 418613 bytes
-rw-r--r--img/env-highlighted.pngbin0 -> 412150 bytes
-rw-r--r--img/env.pngbin0 -> 414589 bytes
-rw-r--r--img/inputs-highlighted.pngbin0 -> 159316 bytes
-rw-r--r--img/inputs.pngbin0 -> 159037 bytes
-rw-r--r--img/version-highlighted.png (renamed from img/software-highlighted.png)bin322450 -> 322450 bytes
-rw-r--r--img/version.png (renamed from img/software.png)bin322258 -> 322258 bytes
-rw-r--r--reproducible-paper.tex530
-rw-r--r--tex/project-graph.tex133
10 files changed, 416 insertions, 247 deletions
diff --git a/img/build-highlighted.png b/img/build-highlighted.png
new file mode 100644
index 0000000..a1df681
--- /dev/null
+++ b/img/build-highlighted.png
Binary files differ
diff --git a/img/build.png b/img/build.png
new file mode 100644
index 0000000..8baefa7
--- /dev/null
+++ b/img/build.png
Binary files differ
diff --git a/img/env-highlighted.png b/img/env-highlighted.png
new file mode 100644
index 0000000..1b68e7e
--- /dev/null
+++ b/img/env-highlighted.png
Binary files differ
diff --git a/img/env.png b/img/env.png
new file mode 100644
index 0000000..d5e9a32
--- /dev/null
+++ b/img/env.png
Binary files differ
diff --git a/img/inputs-highlighted.png b/img/inputs-highlighted.png
new file mode 100644
index 0000000..f2a24f4
--- /dev/null
+++ b/img/inputs-highlighted.png
Binary files differ
diff --git a/img/inputs.png b/img/inputs.png
new file mode 100644
index 0000000..9ecbbf5
--- /dev/null
+++ b/img/inputs.png
Binary files differ
diff --git a/img/software-highlighted.png b/img/version-highlighted.png
index 51c8677..51c8677 100644
--- a/img/software-highlighted.png
+++ b/img/version-highlighted.png
Binary files differ
diff --git a/img/software.png b/img/version.png
index 0967475..0967475 100644
--- a/img/software.png
+++ b/img/version.png
Binary files differ
diff --git a/reproducible-paper.tex b/reproducible-paper.tex
index d9f7d52..b0603de 100644
--- a/reproducible-paper.tex
+++ b/reproducible-paper.tex
@@ -1,4 +1,4 @@
-\documentclass[9pt]{beamer}
+\documentclass[9pt,usenames,dvipsnames]{beamer}
%% Beamer settings.
%\setbeamertemplate{footline}[frame number]
@@ -24,7 +24,7 @@
}
%% Set the date and insitutional logos.
-\date{\scriptsize \href{https://www.astro.rug.nl/~sundial/MidtermMeeting.html}{SUNDIAL Midterm meeting}, June 5th, 2019\\ Ghent, Belgium}
+\date{\scriptsize \href{https://eas.unige.ch/EWASS2019/session.jsp?id=SS34}{EWASS 2019, Special Session 34}, June 25th, 2019\\ Lyon, France}
%% For a wider writing width.
\newcommand\Wider[2][3em]{%
@@ -93,26 +93,6 @@
-% \begin{frame}{Necessity of (exactly) reproducible research}
-% \begin{itemize}
-% \setlength\itemsep{0.7cm}
-% \item To be considered \alert{scientific}, any result has to be
-% reproducible.
-% \item The tsunami of data, fast internet, and high processing
-% power have made it very easy to \alert{promptly arrive at a
-% result}.
-% \item But these factors have also greatly increased the
-% \alert{complexity} of an analysis. Making it impossible to
-% exactly describe all steps in a traditional published paper.
-% \item Most scientific papers thus \alert{ignore some ``details''}
-% (as they interpret it).
-% \item But due to the complexity, even a small deviation from the
-% exact result, can be due to many different parts of the
-% analysis. Hence, its \alert{critical to exactly reproduce} a
-% result.
-% \end{itemize}
-% \end{frame}
-
\begin{frame}{Reproducibility crisis in the sciences/astronomy}
\begin{tcolorbox}[title=Snakes on a Spaceship -- An Overview of Python in Heliophysics]
\small ``...\alert{inadequate analysis descriptions} and loss of
@@ -145,8 +125,13 @@
+ %% Initially in full opacity:
+ \newcommand{\allopacity}{1}
+
+
- \newcommand{\nodeopacity}{1}
+
+ %% Step-by-step slides.
\begin{frame}{General outline of a project} \include{tex/project-graph} \end{frame}
\newcommand{\paperinit}{}
\begin{frame}{General outline of a project} \include{tex/project-graph} \end{frame}
@@ -162,6 +147,19 @@
\begin{frame}{General outline of a project} \include{tex/project-graph} \end{frame}
\newcommand{\confenv}{}
\begin{frame}{General outline of a project} \include{tex/project-graph} \end{frame}
+ \begin{frame}{Example: Matplotlib (a Python visualization library) build dependencies}
+ \Wider[5em]{
+ \vspace{5mm}
+ \includegraphics[width=\linewidth]{img/matplotlib.pdf}
+
+ \vspace{7mm}\tiny From ``Attributing and Referencing (Research)
+ Software: Best Practices and Outlook from Inria'' (Alliez et
+ al. 2019,
+ \textcolor{blue}{\href{https://hal.archives-ouvertes.fr/hal-02135891}{hal-02135891}})
+ }
+ \end{frame}
+ \newcommand{\containers}{}
+ \begin{frame}{General outline of a project} \include{tex/project-graph} \end{frame}
\newcommand{\db}{}
\begin{frame}{General outline of a project} \include{tex/project-graph} \end{frame}
\newcommand{\calib}{}
@@ -189,9 +187,11 @@
\newcommand{\paperfinal}{}
\begin{frame}{General outline of a project} \include{tex/project-graph} \end{frame}
- %% Don't show the happy scientist any more.
- \let\paperfinal\undefined
+ %% Don't show the happy scientist or the existing containers box.
\let\paperinit\undefined
+ \let\allopacity\undefined
+ \let\paperfinal\undefined
+ \let\containers\undefined
@@ -208,10 +208,10 @@
\vspace{0.2cm}
\begin{tcolorbox}
- \small Data analysis [...] is a human behaviour. Researchers
- who hunt hard enough will turn up a result that fits
- statistical criteria, but their \alert{discovery} will
- probably be a \alert{false positive}.
+ \small Data analysis [...] is a \alert{human
+ behaviour}. Researchers who hunt hard enough will turn up a
+ result that fits statistical criteria, but their
+ \alert{discovery} will probably be a \alert{false positive}.
\hfill Five ways to fix statistics, Nature, 551, Nov 2017.
\end{tcolorbox}
@@ -245,111 +245,10 @@
- \renewcommand{\nodeopacity}{0.3}
- \begin{frame}{General outline of a project} \include{tex/project-graph} \end{frame}
-
-
-
-
-
- \begin{frame}{Values in final report/paper}
- All necessary analysis/processing \alert{input} and \alert{output}
- values are written into the final report as \LaTeX{} macros. Shown
- here is a portion of the \textsf{NoiseChisel} paper and its source
- (\textcolor{blue}{\small\href{https://arxiv.org/abs/1505.01664}{arXiv:1505.01664}}).
-
- \vspace{1.2cm}
- \includegraphics[width=\linewidth]{img/reproducible-latex.png}
- \end{frame}
-
- \begin{frame}{Values in final report/paper}
- All necessary analysis/processing \alert{input} and \alert{output}
- values are written into the final report as \LaTeX{} macros. Shown
- here is a portion of the \textsf{NoiseChisel} paper and its source
- (\textcolor{blue}{\small\href{https://arxiv.org/abs/1505.01664}{arXiv:1505.01664}}).
-
- \vspace{1.2cm}
- \includegraphics[width=\linewidth]{img/reproducible-latex-highlighted.png}
- \end{frame}
-
- \begin{frame}{Values come from a single file}
- All the \LaTeX{} macros (processing inputs and outputs) come from
- a \alert{single file}. This file is the \alert{final product} of
- the analysis steps.
-
- \begin{center}
- \includegraphics[width=0.8\linewidth]{img/reproducible-macros.png}
- \end{center}
- \end{frame}
-
-
-
- \begin{frame}{Values come from a single file}
- All the \LaTeX{} macros (processing inputs and outputs) come from
- a \alert{single file}. This file is the \alert{final product} of
- the analysis steps.
-
- \begin{center}
- \includegraphics[width=0.8\linewidth]{img/reproducible-macros-highlighted.png}
- \end{center}
- \end{frame}
-
-
- \begin{frame}{Values written during analysis}
- Various steps of the analysis write the macro values as soon as
- they are calculated internally.
-
- \begin{center}
- \includegraphics[width=0.8\linewidth]{img/reproducible-write-macro.png}
- \end{center}
- \end{frame}
-
-
- \begin{frame}{Values written during analysis}
- Various steps of the analysis write the macro values as soon as
- they are calculated internally.
-
- \begin{center}
- \includegraphics[width=0.8\linewidth]{img/reproducible-write-macro-highlight.png}
- \end{center}
- \end{frame}
-
-
- \begin{frame}{Reproducible science: Template is managed through a Makefile}
- \small
- \begin{columns}
- \column{5.5cm}
-
- All steps (downloading and analysis) is managed by Makefiles
- (example from
- \textcolor{blue}{\small\href{https://doi.org/10.5281/zenodo.1164774}{zenodo.1164774}}):
-
- \begin{itemize}
- \setlength\itemsep{0.2cm}
- \item Unlike a script which always starts from the top, a
- Makefile \alert{starts from the end} and steps that don't
- change will be left untouched (not remade).
- \item A single \emph{rule} can \alert{manage any number of
- files}. See the examples here where \textsf{NoiseChisel} and
- \textsf{MakeCatalog} are run separately on \alert{$\sim20$
- files} (different filters/fields) with a single rule.
- \item Make can identify independent steps internally and do them
- in \alert{parallel}.
- \item Make was \alert{designed for complex problems} with
- thousands of files (all major Unix-like components), so it is
- highly evolved and efficient.
- \item Make is a very \alert{simple} and \alert{small} language,
- thus easy to learn with great and free documentation (for
- example
- \textcolor{blue}{\href{https://www.gnu.org/software/make/manual/}{GNU
- Make's manual}}, usable to learn all implementations).
- \end{itemize}
-
- \column{5.5cm}
- \includegraphics[width=\linewidth]{img/reproducible-makefile.png}
- \end{columns}
- \end{frame}
+ \newcommand{\focusonpackages}{}
+ \begin{frame}{General outline of a project} \include{tex/project-graph} \end{frame}
+ \let\focusonpackages\undefined
@@ -368,17 +267,15 @@
reproducibility.
\end{tcolorbox}
+ \vspace{1cm}
+
\begin{itemize}
\setlength\itemsep{0.4cm}
\item \emph{Containers} or \emph{Virtual Machines} are a
- \alert{binary black box}: just contain the environment, not
- how to set it up, or its history. They are also an overhead.
+ \alert{binary black box}.
\item This template \alert{installs fixed versions} of all
- necessary research software and their dependencies, down to
- the command-line shell, C compiler, POSIX tools and Python
- interpreter. It just avoids very low-level OS elements like
- the kernel or linker.
+ necessary research software and their dependencies.
\item Installs similar environment on \alert{GNU/Linux}, or
\alert{macOS} systems.
@@ -388,7 +285,7 @@
\end{itemize}
\column{5.5cm}
- \includegraphics[width=\linewidth]{img/software.png}
+ \includegraphics[width=\linewidth]{img/version.png}
\end{columns}
\end{frame}
@@ -409,17 +306,15 @@
reproducibility.
\end{tcolorbox}
+ \vspace{1cm}
+
\begin{itemize}
\setlength\itemsep{0.4cm}
\item \emph{Containers} or \emph{Virtual Machines} are a
- \alert{binary black box}: just contain the environment, not
- how to set it up, or its history. They are also an overhead.
+ \alert{binary black box}.
\item This template \alert{installs fixed versions} of all
- necessary research software and their dependencies, down to
- the command-line shell, C compiler, POSIX tools and Python
- interpreter. It just avoids very low-level OS elements like
- the kernel or linker.
+ necessary research software and their dependencies.
\item Installs similar environment on \alert{GNU/Linux}, or
\alert{macOS} systems.
@@ -429,61 +324,105 @@
\end{itemize}
\column{5.5cm}
- \includegraphics[width=\linewidth]{img/software-highlighted.png}
+ \includegraphics[width=\linewidth]{img/version-highlighted.png}
\end{columns}
\end{frame}
- \newcommand{\redbdir}{\textcolor{green!80!black}{/TEMPLATE/BUILD/DIRECTORY/software/installed/lib}}
- \begin{frame}{Dependencies are cleanly managed}
- \begin{itemize}
- \item All the software are configured and built to use the
- \alert{template's own builds}: indepenent of host system
- (\textcolor{green!80!black}{in green}).
- \item Template even builds a fixed GNU C Compiler (\alert{GCC}).
- \item Only extremely low-level dependencies (for example C library
- and Kernel) not built.
- \begin{itemize}
- \item GNU C library will also be added later (\alert{in red}).
- \end{itemize}
- \end{itemize}
+
+ \begin{frame}{Controlled environment and build instructions}
+ \small
+ \begin{columns}
+ \column{5.5cm}
+ \includegraphics[width=\linewidth]{img/env.png}
+ \column{5.5cm}
+ \includegraphics[width=\linewidth]{img/build.png}
+ \end{columns}
+ \end{frame}
+
+ \begin{frame}{Controlled environment and build instructions}
+ \small
+ \begin{columns}
+ \column{5.5cm}
+ \includegraphics[width=\linewidth]{img/env-highlighted.png}
+ \column{5.5cm}
+ \includegraphics[width=\linewidth]{img/build-highlighted.png}
+ \end{columns}
+ \end{frame}
+
+
+
+
+
+ \newcommand{\redbdir}{\textcolor{green!80!black}{/PROJECT/PATH/software/installed/lib}}
+ \begin{frame}{All dependencies (except C library and linker) built in project\\
+ Linked libraries to NoiseChisel executable on GNU/Linux}
\vspace{0.5cm}
\tiny\texttt{
\$ ldd .local/bin/astnoisechisel\\
- \hspace{0.5cm}libgit2.so.26 => \redbdir/libgit2.so.26 (0x00007febb5232000)\\
- \hspace{0.5cm}libtiff.so.5 => \redbdir/libtiff.so.5 (0x00007febb51b8000)\\
- \hspace{0.5cm}liblzma.so.5 => \redbdir/liblzma.so.5 (0x00007febb5190000)\\
- \hspace{0.5cm}libjpeg.so.9 => \redbdir/libjpeg.so.9 (0x00007febb5153000)\\
- \hspace{0.5cm}z.so.1 => \redbdir/libz.so.1 (0x00007febb5136000)\\
- \hspace{0.5cm}wcs.so.6 => \redbdir/libwcs.so.6 (0x00007febb4fcc000)\\
- \hspace{0.5cm}cfitsio.so.8 => \redbdir/libcfitsio.so.8 (0x00007febb4caf000)\\
- \hspace{0.5cm}curl.so.4 => \redbdir/libcurl.so.4 (0x00007febb4c35000)\\
- \hspace{0.5cm}ssl.so.1.1 => \redbdir/libssl.so.1.1 (0x00007febb4b9b000)\\
- \hspace{0.5cm}crypto.so.1.1 => \redbdir/libcrypto.so.1.1 (0x00007febb48b5000)\\
- \hspace{0.5cm}gsl.so.23 => \redbdir/libgsl.so.23 (0x00007febb4626000)\\
- \hspace{0.5cm}gslcblas.so.0 => \redbdir/libgslcblas.so.0 (0x00007febb45e2000)\\
- \hspace{0.5cm}gnuastro.so.8 => \redbdir/libgnuastro.so.8 (0x00007febb419e000)\\
- \hspace{0.5cm}bz2.so.1.0 => \redbdir/libbz2.so.1.0 (0x00007febb3e20000)\\
- \hspace{0.5cm}\alert{m.so.6} => /usr/lib/libm.so.6 (0x00007febb4025000)\\
- \hspace{0.5cm}\alert{pthread.so.0} => /usr/lib/libpthread.so.0 (0x00007febb4004000)\\
- \hspace{0.5cm}\alert{c.so.6} => /usr/lib/libc.so.6 (0x00007febb3e3f000)\\
- \hspace{0.5cm}rt.so.1 => /usr/lib/librt.so.1 (0x00007febb3e35000)\\
- \hspace{0.5cm}dl.so.2 => /usr/lib/libdl.so.2 (0x00007febb3e1b000)\\
- \hspace{0.5cm}linux-vdso.so.1 (0x00007ffcf2497000)\\
- \hspace{0.5cm}/lib64/ld-linux-x86-64.so.2 => /usr/lib64/ld-linux-x86-64.so.2 (0x00007febb53c6000)
+ \hspace{0.5cm}linux-vdso.so.1 (0x00007fffdcbf7000)\\
+ \hspace{0.5cm}libgnuastro.so.7 => \redbdir/libgnuastro.so.7 (0x00007f6745f39000)\\
+ \hspace{0.5cm}libgit2.so.26 => \redbdir/libgit2.so.26 (0x00007f6745df1000)\\
+ \hspace{0.5cm}libtiff.so.5 => \redbdir/libtiff.so.5 (0x00007f6745d77000)\\
+ \hspace{0.5cm}liblzma.so.5 => \redbdir/liblzma.so.5 (0x00007f6745d4f000)\\
+ \hspace{0.5cm}libjpeg.so.9 => \redbdir/libjpeg.so.9 (0x00007f6745d12000)\\
+ \hspace{0.5cm}libwcs.so.6 => \redbdir/libwcs.so.6 (0x00007f6745ba8000)\\
+ \hspace{0.5cm}libcfitsio.so.8 => \redbdir/libcfitsio.so.8 (0x00007f674588b000)\\
+ \hspace{0.5cm}libcurl.so.4 => \redbdir/libcurl.so.4 (0x00007f6745811000)\\
+ \hspace{0.5cm}libssl.so.1.1 => \redbdir/libssl.so.1.1 (0x00007f6745777000)\\
+ \hspace{0.5cm}libcrypto.so.1.1 => \redbdir/libcrypto.so.1.1 (0x00007f6745491000)\\
+ \hspace{0.5cm}libz.so.1 => \redbdir/libz.so.1 (0x00007f6745474000)\\
+ \hspace{0.5cm}libgsl.so.23 => \redbdir/libgsl.so.23 (0x00007f67451e3000)\\
+ \hspace{0.5cm}libgslcblas.so.0 => \redbdir/libgslcblas.so.0 (0x00007f67451a1000)\\
+ \hspace{0.5cm}libbz2.so.1.0 => \redbdir/libbz2.so.1.0 (0x00007f6744e23000)\\
+ \hspace{0.5cm}\alert{libpthread.so.0} => /usr/lib/libpthread.so.0 (0x00007f6745006000)\\
+ \hspace{0.5cm}\alert{libm.so.6} => /usr/lib/libm.so.6 (0x00007f6745027000)\\
+ \hspace{0.5cm}\alert{libc.so.6} => /usr/lib/libc.so.6 (0x00007f6744e43000)\\
+ \hspace{0.5cm}libdl.so.2 => /usr/lib/libdl.so.2 (0x00007f6744e1e000)\\
+ \hspace{0.5cm}librt.so.1 => /usr/lib/librt.so.1 (0x00007f6744e36000)\\
+ \hspace{0.5cm}/lib64/ld-linux-x86-64.so.2 => /usr/lib64/ld-linux-x86-64.so.2 (0x00007f67463c7000)
+ }
+ \end{frame}
+
+
+ \begin{frame}{All dependencies (except C library and linker) built in project\\
+ Linked libraries to NoiseChisel executable on macOS}
+ \vspace{0.5cm}
+ \tiny\texttt{
+ \$ otool -L .local/bin/astnoisechisel\\
+ \hspace{0.5cm}.local/bin/astnoisechisel:\\
+ \hspace{0.5cm}\redbdir/libgnuastro.7.dylib (compatibility ver 8.0.0, current ver 8.0.0)\\
+ \hspace{0.5cm}\redbdir/libgit2.26.dylib (compatibility ver 26.0.0, current ver 0.26.0)\\
+ \hspace{0.5cm}\redbdir/libtiff.5.dylib (compatibility ver 10.0.0, current ver 10.0.0)\\
+ \hspace{0.5cm}\redbdir/liblzma.5.dylib (compatibility ver 8.0.0, current ver 8.4.0)\\
+ \hspace{0.5cm}\redbdir/libjpeg.9.dylib (compatibility ver 12.0.0, current ver 12.0.0)\\
+ \hspace{0.5cm}\redbdir/libwcs.6.2.dylib (compatibility ver 6.0.0, current ver 6.2.0)\\
+ \hspace{0.5cm}\redbdir/libcfitsio.8.dylib (compatibility ver 8.0.0, current ver 8.3.47)\\
+ \hspace{0.5cm}\redbdir/libcurl.4.dylib (compatibility ver 10.0.0, current ver 10.0.0)\\
+ \hspace{0.5cm}\redbdir/libssl.1.1.dylib (compatibility ver 1.1.0, current ver 1.1.0)\\
+ \hspace{0.5cm}\redbdir/libcrypto.1.1.dylib (compatibility ver 1.1.0, current ver 1.1.0)\\
+ \hspace{0.5cm}\redbdir/libz.1.dylib (compatibility ver 1.0.0, current ver 1.2.11)\\
+ \hspace{0.5cm}\redbdir/libgsl.23.dylib (compatibility ver 25.0.0, current ver 25.0.0)\\
+ \hspace{0.5cm}\redbdir/libgslcblas.0.dylib (compatibility ver 1.0.0, current ver 1.0.0)\\
+ \hspace{0.5cm}/usr/lib/libSystem.B.dylib (compatibility ver 1.0.0, current ver 1252.50.4)
}
\end{frame}
+
\begin{frame}{Advantages of this build system}
\begin{columns}
\column{7cm}
\begin{itemize}
- \setlength\itemsep{1cm}
+ \setlength\itemsep{0.7cm}
+ \item Project runs in fixed/controlled environment: custom build
+ of \alert{Bash}, GNU Coreutils (\alert{\texttt{ls}},
+ \alert{\texttt{cp}}, \alert{\texttt{mkdir}} and etc),
+ \alert{AWK}, or \alert{SED}, \alert{\LaTeX}, etc.
\item No need for \alert{root}/administrator \alert{permissions}
(on servers or super computers).
\item Whole system is built \alert{automatically} on any
@@ -511,44 +450,195 @@
-% \begin{frame}{Reproducing the result and report/paper}
-% The two \alert{simple} and \alert{familiar} commands below are
-% enough to exactly reproduce the results at any time.
-%
-% \begin{itemize}
-% \item[] \texttt{\$ ./configure}
-% \item[] \texttt{\$ make}
-% \end{itemize}
-%
-% With \texttt{./configure}, you specify the local directories to
-% use. All necessary \alert{software} are then \alert{downloaded}
-% and installed there (independent of your OS or other projects).
-%
-% \vspace{0.3cm} With \texttt{make}, input \alert{data} from online
-% archives (databases) are \alert{downloaded}, if not locally
-% available, the processing is done, and the \LaTeX{} paper is built
-% as a PDF (e.g., see
-% \textcolor{blue}{\small\href{https://doi.org/10.5281/zenodo.1164774}{zenodo.1164774}}
-% or
-% \textcolor{blue}{\small\href{https://gitlab.com/makhlaghi/reproducible-paper-output/raw/master/paper.pdf}{template's
-% output}}).
-%
-% \vspace{0.3cm} Enabling version control (e.g., with \alert{Git})
-% encourages testing different ideas while not harming the
-% initial/base result (thus encouraging \alert{creativity} and
-% brainstorming during the project).
-%
-% \vspace{0.3cm} After publication, \alert{readers} can
-% \alert{change} the input configurations and the numbers and
-% figures of the reproduced paper will respectively change. This
-% encourages creativity and brainstorming after the project as well
-% as sharing of (the hardly gained) experiences with the whole
-% community.
-% \end{frame}
-
-
-
- \renewcommand{\nodeopacity}{1}
+
+
+
+
+
+ %% Hardware/data
+ \newcommand{\focusonhardware}{}
+ \begin{frame}{General outline of a project} \include{tex/project-graph} \end{frame}
+ \let\focusonhardware\undefined
+
+ \begin{frame}{Input data source and integrity is documented and checked}
+ \small
+ \begin{columns}
+ \column{5.5cm}
+ Stored information about each input file:
+ \begin{itemize}
+ \item \alert{PID} (where available).
+ \item Download \alert{URL}.
+ \item \alert{MD5}-sum to check integrity.
+ \end{itemize}
+
+ \vspace{1cm} All inputs are downloaded from the given PID/URL.
+
+ \vspace{1cm} Their MD5-sum is checked to make sure the download
+ was done properly or the file is the same (hasn't changed on the
+ server/source).
+
+ \column{5.5cm}
+ \includegraphics[width=\linewidth]{img/inputs.png}
+ \end{columns}
+ \end{frame}
+
+ \begin{frame}{Input data source and integrity is documented and checked}
+ \small
+ \begin{columns}
+ \column{5.5cm}
+ Stored information about each input file:
+ \begin{itemize}
+ \item \alert{PID} (where available).
+ \item Download \alert{URL}.
+ \item \alert{MD5}-sum to check integrity.
+ \end{itemize}
+
+ \vspace{1cm} All inputs are downloaded from the given PID/URL.
+
+ \vspace{1cm} Their MD5-sum is checked to make sure the download
+ was done properly or the file is the same (hasn't changed on the
+ server/source).
+
+ \column{5.5cm}
+ \includegraphics[width=\linewidth]{img/inputs-highlighted.png}
+ \end{columns}
+ \end{frame}
+
+
+
+
+
+
+
+
+
+
+ %% Analysis
+ \newcommand{\focusonrun}{}
+ \begin{frame}{General outline of a project} \include{tex/project-graph} \end{frame}
+ \let\focusonrun\undefined
+
+
+
+
+
+ \begin{frame}{Reproducible science: Template is managed through a Makefile}
+ \small
+ \begin{columns}
+ \column{5.5cm}
+
+ All steps (downloading and analysis) is managed by Makefiles
+ (example from
+ \textcolor{blue}{\small\href{https://doi.org/10.5281/zenodo.1164774}{zenodo.1164774}}):
+
+ \begin{itemize}
+ \setlength\itemsep{0.3cm}
+ \item Unlike a script which always starts from the top, a
+ Makefile \alert{starts from the end} and steps that don't
+ change will be left untouched (not remade).
+ \item A single \emph{rule} can \alert{manage any number of
+ files}.
+ \item Make can identify independent steps internally and do them
+ in \alert{parallel}.
+ \item Make was \alert{designed for complex problems} with
+ thousands of files (all major Unix-like components), so it is
+ highly evolved and efficient.
+ \item Make is a very \alert{simple} and \alert{small} language,
+ thus easy to learn with great and free documentation (for
+ example
+ \textcolor{blue}{\href{https://www.gnu.org/software/make/manual/}{GNU
+ Make's manual}}).
+ \end{itemize}
+
+ \column{5.5cm}
+ \includegraphics[width=\linewidth]{img/reproducible-makefile.png}
+ \end{columns}
+ \end{frame}
+
+
+
+
+
+
+
+ \newcommand{\focusonpaper}{}
+ \begin{frame}{General outline of a project} \include{tex/project-graph} \end{frame}
+ \let\focusonpaper\undefined
+
+ \begin{frame}{Values in final report/paper}
+ All necessary analysis/processing \alert{input} and \alert{output}
+ values are written into the final report as \LaTeX{} macros. Shown
+ here is a portion of the \textsf{NoiseChisel} paper and its source
+ (\textcolor{blue}{\small\href{https://arxiv.org/abs/1505.01664}{arXiv:1505.01664}}).
+
+ \vspace{1.2cm}
+ \includegraphics[width=\linewidth]{img/reproducible-latex.png}
+ \end{frame}
+
+ \begin{frame}{Values in final report/paper}
+ All necessary analysis/processing \alert{input} and \alert{output}
+ values are written into the final report as \LaTeX{} macros. Shown
+ here is a portion of the \textsf{NoiseChisel} paper and its source
+ (\textcolor{blue}{\small\href{https://arxiv.org/abs/1505.01664}{arXiv:1505.01664}}).
+
+ \vspace{1.2cm}
+ \includegraphics[width=\linewidth]{img/reproducible-latex-highlighted.png}
+ \end{frame}
+
+
+
+ \begin{frame}{Values come from a single file}
+ All the \LaTeX{} macros (processing inputs and outputs) come from
+ a \alert{single file}. This file is the \alert{final product} of
+ the analysis steps.
+
+ \begin{center}
+ \includegraphics[width=0.8\linewidth]{img/reproducible-macros.png}
+ \end{center}
+ \end{frame}
+
+
+
+ \begin{frame}{Values come from a single file}
+ All the \LaTeX{} macros (processing inputs and outputs) come from
+ a \alert{single file}. This file is the \alert{final product} of
+ the analysis steps.
+
+ \begin{center}
+ \includegraphics[width=0.8\linewidth]{img/reproducible-macros-highlighted.png}
+ \end{center}
+ \end{frame}
+
+
+ \begin{frame}{Values written during analysis}
+ Various steps of the analysis write the macro values as soon as
+ they are calculated internally.
+
+ \begin{center}
+ \includegraphics[width=0.8\linewidth]{img/reproducible-write-macro.png}
+ \end{center}
+ \end{frame}
+
+
+ \begin{frame}{Values written during analysis}
+ Various steps of the analysis write the macro values as soon as
+ they are calculated internally.
+
+ \begin{center}
+ \includegraphics[width=0.8\linewidth]{img/reproducible-write-macro-highlight.png}
+ \end{center}
+ \end{frame}
+
+
+
+
+
+
+
+
+
+
+ \newcommand{\allopacity}{1}
\begin{frame}{Everything in plain text (machine and human readable)}
\include{tex/project-graph} \end{frame}
\newcommand{\gitlogo}{}
diff --git a/tex/project-graph.tex b/tex/project-graph.tex
index 566a9e7..2a0dc66 100644
--- a/tex/project-graph.tex
+++ b/tex/project-graph.tex
@@ -11,6 +11,15 @@
\draw [white] (0,-4.2) -- (0,4.2);
\draw [white] (-0.5,0) -- (12,0);
+ %% Box showing containers.
+ \ifdefined\containers
+ \filldraw[YellowOrange!20!white, rounded corners=2mm] (-0.1,0.3) rectangle (5.6,3.8);
+ \draw (-0.1,3.6) node [anchor=west] {\scriptsize Existing solutions:};
+ \draw (0.1,3.3) node [anchor=west] {\scriptsize Virtual machines};
+ \draw (0.1,3.0) node [anchor=west] {\scriptsize Containers (e.g., Docker)};
+ \draw (0.1,2.7) node [anchor=west] {\scriptsize OSs (e.g., Nix, GNU Guix)};
+ \fi
+
\graph[grow right sep, simple] {
{ [nodes={yshift=7mm}]
soft/Software [gbox] -> build/Build [bbox],
@@ -39,71 +48,141 @@
\fi
%% Software...
- \ifdefined\sver
- \node (sver) [rbox, above=of soft, yshift=-8mm, opacity=\nodeopacity] {What version?};
- \fi
- \ifdefined\srep
- \node (srep) [rbox, above=of sver, yshift=-8mm, opacity=\nodeopacity] {Repository?};
+ \let\ppopacity\undefined
+ \ifdefined\allopacity \newcommand{\ppopacity}{1}
+ \else \ifdefined\focusonpackages
+ \newcommand{\ppopacity}{1}
+ \else
+ \newcommand{\ppopacity}{0.3}
+ \fi
\fi
- %% Hardware...
- \ifdefined\db
- \node (db) [rbox, below=of hard, yshift=+8mm, opacity=\nodeopacity] {Data base?};
- \fi
- \ifdefined\calib
- \node (calib) [rbox, below=of db, yshift=+8mm, opacity=\nodeopacity] {Calibration/version?};
+ \ifdefined\sver
+ \node (sver)
+ [rbox, above=of soft, yshift=-8mm, opacity=\ppopacity]
+ {What version?};
\fi
- \ifdefined\corr
- \node (corr) [rbox, below=of calib, yshift=+8mm, opacity=\nodeopacity] {Integrity?};
+ \ifdefined\srep
+ \node (srep)
+ [rbox, above=of sver, yshift=-8mm, opacity=\ppopacity]
+ {Repository?};
\fi
%% Build
\ifdefined\dver
- \node (dver) [rbox, above=of build, yshift=-8mm, opacity=\nodeopacity] {Dependencies?};
+ \node (dver)
+ [rbox, above=of build, yshift=-8mm, opacity=\ppopacity]
+ {Dependencies?};
\fi
\ifdefined\ddver
- \node (ddver) [rbox, above=of dver, yshift=-8mm, opacity=\nodeopacity] {Dep. versions?};
+ \node (ddver)
+ [rbox, above=of dver, yshift=-8mm, opacity=\ppopacity]
+ {Dep. versions?};
\fi
\ifdefined\confopt
- \node (confopt) [rbox, above=of ddver, yshift=-8mm, opacity=\nodeopacity] {Config options?};
+ \node (confopt)
+ [rbox, above=of ddver, yshift=-8mm, opacity=\ppopacity]
+ {Config options?};
\fi
\ifdefined\confenv
- \node (confenv) [rbox, above=of confopt, yshift=-8mm, opacity=\nodeopacity] {Config environment?};
+ \node (confenv)
+ [rbox, above=of confopt, yshift=-8mm, opacity=\ppopacity]
+ {Config environment?};
+ \fi
+
+ %% Hardware/data
+ \let\ppopacity\undefined
+ \ifdefined\allopacity \newcommand{\ppopacity}{1}
+ \else \ifdefined\focusonhardware
+ \newcommand{\ppopacity}{1}
+ \else
+ \newcommand{\ppopacity}{0.3}
+ \fi
+ \fi
+ \ifdefined\db
+ \node (db)
+ [rbox, below=of hard, yshift=+8mm, opacity=\ppopacity]
+ {Data base, or PID?};
+ \fi
+ \ifdefined\calib
+ \node (calib)
+ [rbox, below=of db, yshift=+8mm, opacity=\ppopacity]
+ {Calibration/version?};
+ \fi
+ \ifdefined\corr
+ \node (corr)
+ [rbox, below=of calib, yshift=+8mm, opacity=\ppopacity]
+ {Integrity?};
\fi
%% Run software ...
+ \let\ppopacity\undefined
+ \ifdefined\allopacity \newcommand{\ppopacity}{1}
+ \else \ifdefined\focusonrun
+ \newcommand{\ppopacity}{1}
+ \else
+ \newcommand{\ppopacity}{0.3}
+ \fi
+ \fi
\ifdefined\runord
- \node (runord) [rbox, above=of srun, yshift=-8mm, opacity=\nodeopacity] {What order?};
+ \node (runord)
+ [rbox, above=of srun, yshift=-8mm, opacity=\ppopacity]
+ {What order?};
\fi
\ifdefined\runopt
- \node (runopt) [rbox, above=of runord, yshift=-8mm, opacity=\nodeopacity] {Runtime options?};
+ \node (runopt)
+ [rbox, above=of runord, yshift=-8mm, opacity=\ppopacity]
+ {Runtime options?};
\fi
\ifdefined\humanerr
- \node (humanerr) [rbox, above=of runopt, yshift=-8mm, opacity=\nodeopacity] {Human error?};
+ \node (humanerr)
+ [rbox, above=of runopt, yshift=-8mm, opacity=\ppopacity]
+ {Human error?};
\fi
\ifdefined\depupdate
- \node (depupdate) [rbox, below=of srun, yshift=+8mm, opacity=\nodeopacity] {Environment update?};
+ \node (depupdate)
+ [rbox, below=of srun, yshift=+8mm, opacity=\ppopacity]
+ {Environment update?};
\fi
\ifdefined\coauth
- \node (coaut) [rbox, below=of depupdate, yshift=+8mm, opacity=\nodeopacity] {In sync with coauthors?};
+ \node (coaut)
+ [rbox, below=of depupdate, yshift=+8mm, opacity=\ppopacity]
+ {In sync with coauthors?};
\fi
%% Paper ...
+ \let\ppopacity\undefined
+ \ifdefined\allopacity \newcommand{\ppopacity}{1}
+ \else \ifdefined\focusonpaper
+ \newcommand{\ppopacity}{1}
+ \else
+ \newcommand{\ppopacity}{0.3}
+ \fi
+ \fi
\ifdefined\varsinpaper
- \node (varsinpaper) [rbox, above=of paper, xshift=-1mm, yshift=-8mm, opacity=1] {Sync with analysis?};
+ \node (varsinpaper)
+ [rbox, above=of paper, xshift=-1mm, yshift=-8mm, opacity=\ppopacity]
+ {Sync with analysis?};
\fi
\ifdefined\recordinfo
- \node (recordinfo) [rbox, above=of varsinpaper, yshift=-8mm, opacity=\nodeopacity] {Report this info?};
+ \node (recordinfo)
+ [rbox, above=of varsinpaper, yshift=-8mm, opacity=\ppopacity]
+ {Report this info?};
\fi
\ifdefined\softcite
- \node (softcite) [rbox, above=of recordinfo, yshift=-8mm, opacity=\nodeopacity] {Cited software?};
+ \node (softcite)
+ [rbox, above=of recordinfo, yshift=-8mm, opacity=\ppopacity]
+ {Cited software?};
\fi
\ifdefined\prevchange
- \node (prevchange) [rbox, above=of softcite, yshift=-8mm, opacity=\nodeopacity] {History recorded?};
+ \node (prevchange)
+ [rbox, above=of softcite, yshift=-8mm, opacity=\ppopacity]
+ {History recorded?};
\fi
\ifdefined\gitlogo
- \node [inner sep=0pt, opacity=0.5] at (5.5,0) {\includegraphics[width=10cm]{img/git.png}};
+ \node [inner sep=0pt, opacity=0.5] at (5.5,0)
+ {\includegraphics[width=10cm]{img/git.png}};
\fi
\end{tikzpicture}
}