# Lab Notebooks for Computational Science

Many grants require an official record be kept of day-to-day research activities. For experimental research groups, this is often accomplished with a bound paper notebook in which the experimental details, troubles, and possibly a few key results can be written (or sometimes even printed off and taped in).

Some electronic lab notebook options exist, which may be better suited to work done entirely on the computer (or maybe not!), but these are still less common. Plain text files may not satisfy the requirement of immutable entries. Furthermore, some institutions and groups with a tradition of experimental work may not take to an electronic format at all.

What methods have you tried to keep an official log of your computational research activities?

• Why can't you use the same approach used in experimental laboratories? Sep 1 '20 at 16:39
• That's absolutely an option. Just curious what people's experience was. Electronic versions are tempting because recording file locations or input file settings would be easier (and less error-prone, I think) in a digital format rather than writing things out longhand.
– s47
Sep 1 '20 at 16:43
• GitHub. It’s great for version tracking as well as tracking progress toward research goals. It also enables you to share and collaborate on projects, while also maintaining management controls.
– Paul
Sep 2 '20 at 0:50
• Have you considered using PowerPoint or an open-source equivalent? Its multimedia capabilities make it very useful for computational work since you can copy/paste graphs/plots, console output, typeset math, etc. in addition to bullet points summarizing your work that day. Its contents can also be easily adapted for demonstrating your work to others. Of course, you should also, as discussed above, preserve things like input files and revision hashes.
– smh
Sep 4 '20 at 11:03
• I added provenance as a tag to this question. Sep 4 '20 at 20:36

## 1 Answer

As Paul mentioned in his comment, git and public hosting sites like Github and Gitlab are invaluable for keeping track of the development history of computational projects. A few concrete examples of where I've found that history useful:

• US federal grants require you to fill out yearly progress reports and I can never remember exactly what I did, but I can always look through the commit history.
• Finding exactly where bugs have crept into the code I write, sometimes manually and sometimes automatically with git bisect.
• I like to remind the students I work with that it's ok to make mistakes, the important part is being circumspect in testing, so I go through the commit history of projects I've worked on to show them some of my more idiotic mistakes.

You also mentioned electronic notebooks; I'm guessing you're already familiar with Jupyter notebooks then. I use these a lot for computational experiments, especially when I'm messing around with new methods that I don't quite understand yet. Usually the experimental notebooks would get lost on my hard drive somewhere. What I've started doing lately is keeping these notebooks in a git repository and publishing them online using the static site generator nikola, which can generate posts from Jupyter notebooks. Along with the code I also add explanations of the mathematics with references to other useful sources. This is helpful for future me to remember exactly what I was doing and to be able to show things to colleagues and students. Both github and gitlab offer free static site hosting. You can use continuous integration tools to automatically execute notebooks (so you can keep them in their much smaller purely textual pre-execution form in version control) and build a website with them. The same tools are also helpful in hosting documentation for software projects.

Your usage / mileage my vary, just speaking from personal experience here.

• Thanks so much! I've never heard of nikola before. Jupyter notebooks do seem like a good solution for local calculations and data analysis, but what do you do for larger jobs run on a remote cluster? I guess those could be recorded after they finish, during the data analysis, and maybe include a link to the local folder containing their input files.
– s47
Sep 3 '20 at 22:55
• I don't have a great answer for how this can work with computational experiments that require HPC. There's a project called ipyparallel that might help (I haven't used it). In principle you could have the actual computing done in a separate script and analyze the results in a notebook. But it's definitely not as educational as having both in one artifact that you can then render into a readable document. Sep 3 '20 at 23:52