diff options
| -rw-r--r-- | img/build-highlighted.png | bin | 0 -> 418129 bytes | |||
| -rw-r--r-- | img/build.png | bin | 0 -> 418613 bytes | |||
| -rw-r--r-- | img/env-highlighted.png | bin | 0 -> 412150 bytes | |||
| -rw-r--r-- | img/env.png | bin | 0 -> 414589 bytes | |||
| -rw-r--r-- | img/inputs-highlighted.png | bin | 0 -> 159316 bytes | |||
| -rw-r--r-- | img/inputs.png | bin | 0 -> 159037 bytes | |||
| -rw-r--r-- | img/version-highlighted.png (renamed from img/software-highlighted.png) | bin | 322450 -> 322450 bytes | |||
| -rw-r--r-- | img/version.png (renamed from img/software.png) | bin | 322258 -> 322258 bytes | |||
| -rw-r--r-- | reproducible-paper.tex | 530 | ||||
| -rw-r--r-- | tex/project-graph.tex | 133 |
10 files changed, 416 insertions, 247 deletions
diff --git a/img/build-highlighted.png b/img/build-highlighted.png Binary files differnew file mode 100644 index 0000000..a1df681 --- /dev/null +++ b/img/build-highlighted.png diff --git a/img/build.png b/img/build.png Binary files differnew file mode 100644 index 0000000..8baefa7 --- /dev/null +++ b/img/build.png diff --git a/img/env-highlighted.png b/img/env-highlighted.png Binary files differnew file mode 100644 index 0000000..1b68e7e --- /dev/null +++ b/img/env-highlighted.png diff --git a/img/env.png b/img/env.png Binary files differnew file mode 100644 index 0000000..d5e9a32 --- /dev/null +++ b/img/env.png diff --git a/img/inputs-highlighted.png b/img/inputs-highlighted.png Binary files differnew file mode 100644 index 0000000..f2a24f4 --- /dev/null +++ b/img/inputs-highlighted.png diff --git a/img/inputs.png b/img/inputs.png Binary files differnew file mode 100644 index 0000000..9ecbbf5 --- /dev/null +++ b/img/inputs.png diff --git a/img/software-highlighted.png b/img/version-highlighted.png Binary files differindex 51c8677..51c8677 100644 --- a/img/software-highlighted.png +++ b/img/version-highlighted.png diff --git a/img/software.png b/img/version.png Binary files differindex 0967475..0967475 100644 --- a/img/software.png +++ b/img/version.png 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} } |
