aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMohammad Akhlaghi <mohammad@akhlaghi.org>2020-07-02 02:17:21 +0100
committerMohammad Akhlaghi <mohammad@akhlaghi.org>2020-07-02 02:17:21 +0100
commit492d6c2ee9cbea5e252b0b4224aa8c1ce9869ad5 (patch)
treefe71b5248861917a82450c053801fb403f1d769e
parente4626966e6786a8f6c4568da249ba47d13cb61f6 (diff)
Using images to start discussion on Git, for IAC science coffeeHEADmaster
Until now, we would immeditely jump from the part on answering the project's questions to Git branches. But this isn't too useful for someone who doesn't know Git! So to start the Git branching discussion, now we first show a small image of the workflow with a "today" printed over it. Then another one with a "tomorrow". In the next slide we abstract them to circles with hashes!
-rw-r--r--Makefile2
-rw-r--r--img/project-flow-small.pngbin0 -> 25337 bytes
-rw-r--r--slides-intro-short.tex168
-rw-r--r--slides-intro.tex30
-rw-r--r--tex/git-branch.tex33
5 files changed, 82 insertions, 151 deletions
diff --git a/Makefile b/Makefile
index ef1bfa3..a9ece23 100644
--- a/Makefile
+++ b/Makefile
@@ -29,7 +29,7 @@ clean: clean-latex
# PDF slides:
-slides=slides-intro.pdf slides-intro-short.pdf
+slides = slides-intro-short.pdf slides-intro.pdf
$(slides): %.pdf: %.tex tex/*.tex
# We'll run pdflatex two times so the page numbers and
# internal links also work.
diff --git a/img/project-flow-small.png b/img/project-flow-small.png
new file mode 100644
index 0000000..010a491
--- /dev/null
+++ b/img/project-flow-small.png
Binary files differ
diff --git a/slides-intro-short.tex b/slides-intro-short.tex
index 3bc3f8f..b7c551a 100644
--- a/slides-intro-short.tex
+++ b/slides-intro-short.tex
@@ -51,7 +51,7 @@
%% Set the date and insitutional logos.
\date{\footnotesize\vspace{0cm}\\
- \href{https://www.rd-alliance.org/rda-global-adoption-week-15-19-june-2020}{RDA Global Adoption week}\\June 18th, 2020\\
+ IAC Scientific Coffee\\July 2nd, 2020\\
\tiny\vspace{3mm}
Most recent slides available in link below (this PDF is built from \href{http://git.maneage.org/slides-intro.git}{Git commit} \gitcommit):\\
\footnotesize\textcolor{blue}{\url{https://maneage.org/pdf/slides-intro-short.pdf}}\\
@@ -95,33 +95,33 @@
\usebackgroundtemplate{ } %% undeclare it
- \begin{frame}{Challenges of the RDA-WDS Publishing Data Workflows WG {\small (DOI:\href{https://doi.org/10.1007/s00799-016-0178-2}{10.1007/s00799-016-0178-2})}}
- Challenges (also relevant to researchers, not just repositories)
- \begin{itemize}
- \item \emph{Bi-directional linking}: how to \alert{link data and publications}.
- \item \emph{\alert{Software management}:} how to manage, preserve, publish and cite software?
- \item \emph{Metrics:} \alert{how often} are data used.
- \item \emph{Incentives to researchers:} how to \alert{communicate benefits} of following good practices \alert{to researchers}.
- \end{itemize}
-
- \begin{center}
- \includegraphics[width=4cm]{img/rda.png}\hspace{1cm}
- \includegraphics[width=4cm]{img/wds.jpg}
- \end{center}
-
- \ifdefined\longformat\pause\fi
-
- ``\emph{We would like to see a workflow that results in all
- \textcolor{blue!30!green}{\bf scholarly objects being connected},
- linked, citable, and persistent to allow researchers to navigate
- smoothly and to \alert{\bf enable reproducible research}. This
- includes \alert{{\bf linkages} between documentation, code, data, and
- journal articles in an integrated environment}. Furthermore,
- in the ideal workflow, all of these objects need to be
- \alert{\bf well documented} to enable other researchers (or
- citizen scientists etc) to reuse the data for new
- discoveries.}''
- \end{frame}
+% \begin{frame}{Challenges of the RDA-WDS Publishing Data Workflows WG {\small (DOI:\href{https://doi.org/10.1007/s00799-016-0178-2}{10.1007/s00799-016-0178-2})}}
+% Challenges (also relevant to researchers, not just repositories)
+% \begin{itemize}
+% \item \emph{Bi-directional linking}: how to \alert{link data and publications}.
+% \item \emph{\alert{Software management}:} how to manage, preserve, publish and cite software?
+% \item \emph{Metrics:} \alert{how often} are data used.
+% \item \emph{Incentives to researchers:} how to \alert{communicate benefits} of following good practices \alert{to researchers}.
+% \end{itemize}
+
+% \begin{center}
+% \includegraphics[width=4cm]{img/rda.png}\hspace{1cm}
+% \includegraphics[width=4cm]{img/wds.jpg}
+% \end{center}
+
+% \ifdefined\longformat\pause\fi
+
+% ``\emph{We would like to see a workflow that results in all
+% \textcolor{blue!30!green}{\bf scholarly objects being connected},
+% linked, citable, and persistent to allow researchers to navigate
+% smoothly and to \alert{\bf enable reproducible research}. This
+% includes \alert{{\bf linkages} between documentation, code, data, and
+% journal articles in an integrated environment}. Furthermore,
+% in the ideal workflow, all of these objects need to be
+% \alert{\bf well documented} to enable other researchers (or
+% citizen scientists etc) to reuse the data for new
+% discoveries.}''
+% \end{frame}
\newcommand{\allopacity}{1}
\ifdefined\longformat
@@ -752,6 +752,10 @@
\ifdefined\longformat
\begin{frame}{New projects branch from Maneage} \include{tex/git-branch} \end{frame}
+ \newcommand{\tomorrow}{1}
+ \begin{frame}{New projects branch from Maneage} \include{tex/git-branch} \end{frame}
+ \newcommand{\abstractify}{1}
+ \begin{frame}{New projects branch from Maneage} \include{tex/git-branch} \end{frame}
\newcommand{\projinit}{}
\begin{frame}{New projects branch from Maneage} \include{tex/git-branch} \end{frame}
\newcommand{\projwork}{}
@@ -834,22 +838,6 @@
- \begin{frame}[t]{General outline of using Maneage (for example \href{https://arxiv.org/abs/2006.03018}{arXiv:2006.03018})}
- \vspace{1cm}
- \texttt{\$ git clone https://gitlab.com/makhlaghi/maneage-paper{ }{ }{ }{ }\textcolor{gray}{\# Import the project.}}\\
-
- \ifdefined\longformat\pause\fi
- \vspace{1.5cm}
- \texttt{\$ ./project configure { }{ }{ }{ }{ }{ }{ }{ }\textcolor{gray}{\# You will specify the build directory on your system,}}\\
- \texttt{{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }\textcolor{gray}{\# and it will build all software (about 1.5 hours).}}
-
- \ifdefined\longformat\pause\fi
- \vspace{1.5cm}
- \texttt{\$ ./project make { }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }\textcolor{gray}{\# Does all the analysis and makes final PDF.}}\\
- \end{frame}
-
-
-
\ifdefined\longformat
\begin{frame}{Project source and its execution}
\begin{tcolorbox}
@@ -867,6 +855,26 @@
+
+
+ \begin{frame}[t]{Executing a Maneaged project (for example \href{https://arxiv.org/abs/2006.03018}{arXiv:2006.03018})}
+ \vspace{1cm}
+ \texttt{\$ git clone https://gitlab.com/makhlaghi/maneage-paper{ }{ }{ }{ }\textcolor{gray}{\# Import the project.}}\\
+
+ \ifdefined\longformat\pause\fi
+ \vspace{1.5cm}
+ \texttt{\$ ./project configure { }{ }{ }{ }{ }{ }{ }{ }\textcolor{gray}{\# You will specify the build directory on your system,}}\\
+ \texttt{{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }\textcolor{gray}{\# and it will build all software (about 1.5 hours).}}
+
+ \ifdefined\longformat\pause\fi
+ \vspace{1.5cm}
+ \texttt{\$ ./project make { }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }\textcolor{gray}{\# Does all the analysis and makes final PDF.}}\\
+ \end{frame}
+
+
+
+
+
\begin{frame}{Future prospects...}
\large Adoption of reproducibility by many researchers will enable
the following:
@@ -944,76 +952,4 @@
\textcolor{blue}{\footnotesize\url{https://gitlab.com/maneage/project/-/blob/maneage/README-hacking.md}}
\end{tcolorbox}
\end{frame}
-
-
-\ifdefined\longformat
-\begin{frame}{Existing technologies (Independent environment)}
- \begin{itemize}
- \setlength\itemsep{7mm}
- \item \textbf{Virtual machines:}
- \begin{itemize}
- \setlength\itemsep{3mm}
- \item Contain the \alert{full operating system}, are thus very large ($\times$Gigabytes).
- \item In \emph{binary} format (decoding a built VM's environment is extremely hard and inaccurate).
- \end{itemize}
- \item \textbf{Containers:} (For example Docker or Singularity)
- \begin{itemize}
- \setlength\itemsep{3mm}
- \item Similar to virtual machines, but \alert{without low-level kernel} (use host's kernel).
- \item \alert{Will fail} as soon as kernel is no longer supported\\(for example Docker currently only supports Linux kernel 3.10 and above \alert{from 2013}).
- \item Good solutions for software engineers (that need to \emph{reproduce a bug's environment today}).
- \item Docker is modular, needs root previlages (not available in HPCs), Dockerfiles allow incompleteness\\(especially in the common scenario of using the operating system's package manager, see next slide)
- \item Singularity is monolithic and thus can be very large.
- \item In \alert{binary} format (similar to VMs, especially when OS package managers are used).
- \end{itemize}
- \end{itemize}
-
- \vspace{3mm}
-In summary, they only \alert{store a built} environment (they are outputs, not good for archiving).
-\end{frame}
-
-
-
-
-\begin{frame}{Existing technologies (Package managers)}
-
- \begin{itemize}
- \item \textbf{Operating system package managers:}
- \begin{itemize}
- \setlength\itemsep{2mm}
- \item For example \texttt{apt} or \texttt{yum} for Debian-based and RedHat-based GNU/Linux operating systems\\(the most common way to install software).
- \item Tightly intertwined with the operating system's components\\(arbitrary control of software versions is not easily possible).
- \item Older software (for example +5 years) is usually removed.
- \end{itemize}
- \item \textbf{Conda/Anaconda:}
- \begin{itemize}
- \setlength\itemsep{2mm}
- \item Conda has build instructions for software and their dependencies.
- \item But it doesn't go down to the C library or the lower-level components of operating system.
- \item It is written in Python (can't be used later when current Python is depreciated).
- \item Authors of Uhse+2019\footnote{\url{http://dx.doi.org/10.1002/cppb.20097}} report\footnote{\url{https://github.com/conda-forge/conda-forge.github.io/issues/787}} that their Conda environment breaks roughly every 3 months\\(Conda environments need to be updated to be used later! Breaking reproducibility).
- \end{itemize}
- \item \textbf{Nix, or GNU Guix:}
- \begin{itemize}
- \setlength\itemsep{2mm}
- \item Deliver perfectly reproducible builds (bit-wise reproducibility of software), needs root access.
- \item Doesn't \emph{require} documentation of dependencies.
- \end{itemize}
- \item \textbf{Spack:} Similar to Nix/Guix but written in Python.
- \end{itemize}
-\end{frame}
-
-\begin{frame}{Existing technologies (workflow tools)}
- \begin{itemize}
- \setlength\itemsep{4mm}
- \item \textbf{Binder:} (\url{https://mybinder.org}) Docker+Conda.
- \item \textbf{Galaxy:} (\url{https://galaxyproject.org}) A web-based user interface, primarily designed for genomics. The GUI make it hard to automate, and has too many dependencies. Very similar to GenePattern (2008 to 2017): with +40,000 users and $\sim4000$ jobs running per week, but cut due to funding.
- \item \textbf{Sciunit:} (\url{https://sciunit.run}) Parses program binaries to try to infer their dependencies and copy them.
- \item \textbf{Popper:} (\url{https://falsifiable.us}), HCL (previously used by GitHub Actions) + Conda + Docker.
- \item \textbf{WholeTale:} (\url{https://wholetale.org}) Jupyter + Conda + Docker.
- \item \textbf{Image Processing On Line (IPOL) journal:} The best example of publishing algorithms/methods I have seen, only useful for very basic/low-level software.
- \end{itemize}
- \alert{Summary}: except for IPOL, most solutions surveyed have far too many dependencies to be usable \alert{beyond the immediate future}.
-\end{frame}
-\fi
\end{document}
diff --git a/slides-intro.tex b/slides-intro.tex
index 3ffedf9..c070764 100644
--- a/slides-intro.tex
+++ b/slides-intro.tex
@@ -1185,7 +1185,10 @@ for computational reproducibility]
-
+ \begin{frame}{New projects branch from Maneage} \include{tex/git-branch} \end{frame}
+ \newcommand{\tomorrow}{1}
+ \begin{frame}{New projects branch from Maneage} \include{tex/git-branch} \end{frame}
+ \newcommand{\abstractify}{1}
\begin{frame}{New projects branch from Maneage} \include{tex/git-branch} \end{frame}
\newcommand{\projinit}{}
\begin{frame}{New projects branch from Maneage} \include{tex/git-branch} \end{frame}
@@ -1364,31 +1367,6 @@ for computational reproducibility]
- \begin{frame}{Workshop on Maneage at IAC: \alert{first week of April} (March 30th to April 3rd)}
-
- We are organizing a workshop to help interested \alert{early career researchers} adopt Maneage.
-
- \vspace{5mm}
- \begin{columns}
- \column{0.25\linewidth}
- \centering
- \includegraphics[width=\linewidth]{img/rda-europe.png}
- \column{0.5\linewidth}
- \centering
- \includegraphics[width=\linewidth]{img/workshop-shutterstock.png}\\
- {\tiny Image from \href{https://www.shutterstock.com/es/image-vector/managers-workshop-training-manager-skills-brainstorming-1334996078}{shutterstock.com}}
-
- \column{0.25\linewidth}
- \includegraphics[width=0.7\linewidth]{img/iac.png}
- \end{columns}
-
- \vspace{7mm}
- Please contact \alert{akhlaghi@iac.es} to join (Space is very limited: it is hands-on).
- \end{frame}
-
-
-
-
\begin{frame}{Existing technologies (Independent environment)}
\begin{itemize}
\setlength\itemsep{7mm}
diff --git a/tex/git-branch.tex b/tex/git-branch.tex
index ad5b2c9..79b7e24 100644
--- a/tex/git-branch.tex
+++ b/tex/git-branch.tex
@@ -18,6 +18,7 @@
\begin{tikzpicture}
\draw [white] (0,0) -- (0,7.4);
+ \draw [white] (-1cm,0) -- (5,0);
%% Template branch.
\ifdefined\tofuture
@@ -26,7 +27,9 @@
\ifdefined\tempevolve
\draw[->, line width=2mm] (0,0) -- (0,5.5);
\else
- \draw[->, line width=2mm] (0,0) -- (0,2.3);
+ \ifdefined\abstractify
+ \draw[->, line width=2mm] (0,0) -- (0,2.3);
+ \fi
\fi
\fi
@@ -57,12 +60,22 @@
%% otherwise the black lines are going to be over the commit
%% circles.
- %% Template commits.
- \draw[anchor=north] (0,0) node {\textbf{Maneage}};
- \draw [fill=green!80!blue, opacity=0.5] (0,0.55cm) circle [radius=2.1mm];
- \draw[anchor=east] (-5pt,0.55cm) node {\tiny\texttt{ad2c476}};
- \draw [fill=green!80!blue, opacity=0.5] (0,1.55cm) circle [radius=2.1mm];
- \draw[anchor=east] (-5pt,1.55cm) node {\tiny\texttt{706c644}};
+ %% Maneage commits.
+ \ifdefined\abstractify
+ \draw[anchor=north] (0,0) node {\textbf{Maneage}};
+ \draw [fill=green!80!blue, opacity=0.5] (0,0.55cm) circle [radius=2.1mm];
+ \draw[anchor=east] (-5pt,0.55cm) node {\tiny\texttt{ad2c476}};
+ \draw [fill=green!80!blue, opacity=0.5] (0,1.55cm) circle [radius=2.1mm];
+ \draw[anchor=east] (-5pt,1.55cm) node {\tiny\texttt{706c644}};
+ \else
+ \node [inner sep=0pt] at (0,0.55cm) {\includegraphics[width=1.5cm]{img/project-flow-small.png}};
+ \draw[anchor=center] (0,0.55cm) node {\bf Today};
+ \ifdefined\tomorrow
+ \node [inner sep=0pt] at (0,1.55cm) {\includegraphics[width=1.5cm]{img/project-flow-small.png}};
+ \draw[anchor=center] (0,1.55cm) node {\bf Tomorrow};
+ \else
+ \fi
+ \fi
\ifdefined\tempevolve
\draw [fill=green!80!blue, opacity=0.5] (0,2.55cm) circle [radius=2.1mm];
\draw[anchor=east] (-5pt,2.55cm) node {\tiny\texttt{fa2ac10}};
@@ -119,7 +132,11 @@
\vspace{-1cm}
\begin{itemize}
\setlength\itemsep{0.2cm}
- \item Template's history is recorded in Git.
+ \ifdefined\abstractify
+ \item Each point of project's history is recorded with Git.
+ \else
+ \item The project (answers to questions above) will evolve.
+ \fi
\ifdefined\projinit
\item New project: a branch from the template.\\
Recall that \alert{every commit} contains the following: