Computational reproducibility: IPython in the age of data-driven journalism

Computational reproducibility: IPython in the age of data-driven journalism
blog.fperez.org

But what I have not found yet (or discovered for myself) is good guidance on how to document larger blocks of code. If a function is more than a few lines long, I haven't found a satisfactory way to document it.

The first approach I tried was not to respect the atomicity of the function in terms of formatting. That is, I would just write along literately about what the function was doing, right inside the function. The problem is that in both the code and the generated documentation, it becomes very difficult to discern scope visually.

The second approach I tried was to give a brief overview description above the function, then include ordinary comments inside it. That's fine and all, but at that point, you're not gaining much over simple block comments above the function.

The third approach I've tried is to either use an ordered list of steps preceding the function, or to describe the function with numbered footnotes, and then to add corresponding numeric comments in the code. This is the most satisfactory solution I've found yet, and the documentation ends up looking like a programming book. But the locality of reference is just terrible. It's also just terrible for control flow statements. Using an outline format instead of an ordered list can allow for a bit better control flow, but it's still not great.

I keep envisioning a marriage of Light Table with IPython. If this post is any indication of Light Table's prowess, it could very well work with IPython backend: www.chris-granger.com/2012/05/21/the-future-is-specific/

I mourn the lack of language to build these editors. Schema languages only validate document's structure and content. Browser based editors either abstract editing away to wiki like syntax or hide it inside Word processor emulating widgets. Both come with a set of assumptions that makes them hard to customize to suit the needs of the data.

It should be possible to create a declarative editing and visualization language (a Domain Specific Language) that would drive this browser/data structure server combination. You could describe the editing environment for one particular domain (like exploring and visualizing a statistical dataset). This should be data driven, ie. it builds the environment according to chosen dataset. Language should allow macros or modules in suitable languages for additional functionality, like complex validation, animations and transitions. You can export your view of the data, complete with your code and command history.

Tools for data visualization and editing need to look like they are build for this data, for these particular visualizations. And they should be customizable, right there in the same environment so the link between the data and your knowledge of its domain stays in view. I think these tools hold the promise of becoming toolmakers tools, too.

I currently do most of my exploratory work (which is in turn most of my total work) in the IPython Notebook and it will be interesting to see what Light Table can do beyond what the notebook does (for starters, I imagine it will have a more refined approach to Javascript hooks for visualization and the like).

I will point out though that the only thing that gets posted to the browser in the IPython Notebook is an objects __repr__. So, unless you are looking at raw dumps of tens of gigabytes of data, you shouldn't have to worry about browser memory limitations. The IPython backend of the Notebook can handle just about anything that your standard python interpreter can handle. It could even be an EC2 instance or cluster resource (here is one example: http://www.nature.com/ismej/journal/v7/n3/full/ismej2012123a...).