Saturday, February 28, 2015

Coding Responsibly Part II: Keeping a Notebook

Myth Buster Adam Savage on lab notebooks. <Source>
In my last post I started writing about the next step a coding student can take after learning the basics. This next step is of course learning not just to code, but to code responsibly. Last time I talked about using version control to keep track of code changes as you work through a project. For this next post, I want to take the conversation further by discussing lab notebooks for coding projects. I am going to go over a good program to use for electronic notebook keeping (Microsoft OneNote), and will review some tips to make the process a little smoother. As always, I'll end with some information for further reading.

For us research scientists, lab notebooks are an incredibly important aspect of our everyday work life. Lab notebooks are often bound paper notebooks (see figure below) that scientists use to write protocols, make calculations, record results and interpretations, and other important information. The notebook is important because it provides a central place for all of the findings a scientist has made. It is also important legally, because it keeps a chronological record of findings that can be used in situations such as determining intellectual property. For bench scientists, these notebooks are a great tool, but the bound notebooks can be a little impractical for computational scientists and bioinformaticians.

Here enters the electronic lab notebook. Just like it's analog sibling, the electronic notebook is simply a way to record scientific notes and findings in an electronic environment. This is a great resource for computationally heavy researchers like bioinformaticians because it allows for easy recording of electronic figures, snippets of code, and other notes. As you would probably expect, there are many different programs for electronic notebooks.

There are good and bad electronic lab notebook programs out there, but the one I have liked so far is Microsoft OneNote. OneNote is a great, free program built entirely for effective note taking. I have been using it as my electronic lab notebook for last couple of months now, and I have found it to be very effective. If you do a lot of computational work, I would suggest you check it out, but before you head to the app store, I want to offer a little insight into useful ways I use the program.

An example of an analog lab notebook. <Source>
I think the most difficult part for me as I started to use an electronic notebook was figuring out how to organize the notebook itself. I started by making a new notebook for every project, with tabs for the project categories and the pages for specific parts of the project. This might work for some people, but for me this quickly became a mess. I started losing track of what information was where, what parts needed to be updated, etc. This experience became an organizational headache. It was at least only a headache until I started organizing the notebook chronologically, like the analog notebooks I had kept in the past. This way I could make a new lab notebook for each year, a new notebook tab each month, and a page for every day. On each day page, I like to keep a summary of my day near the top, outlining key words and ideas that make it easy to find things (the search function is also helpful for finding things). Because I also do bench work, I still keep analog notebook records like notes and protocols, but I always transcribe them into my electronic notebook at the end of the day.

It is easy to copy and paste figures and other documents into your OneNote notebook, and it keeps moving fast when you add a bunch of image information. This is nice, but the program really shines when you start adding code references to your notebook. While adding code to OneNote directly is a bit underwhelming (they don't offer a lot for syntax highlighting, etc), it is easy to include links to specific commit locations within your GitHub code repositories. This is actually awesome because it allows for quick and easy referencing of your version controlled code, and you can have it right next to your data so you always know how you got that nice figure.

Other than this, it's up to you to check it out, play with different organization techniques, and see what works best for you. OneNote is free in the App Store for Mac, and is easy to get for your Windows PC as well. If you think I missed something, or if you have any tips you would like to contribute, please feel free to leave a comment below. And of course, happy coding friends!

Works Cited & Further Reading

Perkel, J. (2011). Coding your way out of a problem Nature Methods, 8 (7), 541-543 DOI: 10.1038/nmeth.1631

OneNote Lab Notebooks

1 comment: