document Common.ml

[timodonnell]

I'm not quite sure where to file this ticket, could also go in internal-tools perhaps.

I'm finding it difficult to get my head around biokepi. Lots of this is me learning ocaml at the same time, so please bear with me.

Examples like: https://github.com/hammerlab/biokepi/blob/c823e3fb1cee3227930e703c9ed23c63a16a3578/src/app/main.ml and https://github.com/hammerlab/internal-tools/blob/master/ksinai/seb.ml are unfortunately not doing it for me. I think I need a more documented example.

How am in practice meant to use biokepi? Is the idea that I would set environment variables like BIOKEPI_DATASET_NAME as described in the biokepi README and then run a tool as it describes? Or is the idea that I write scripts like https://github.com/hammerlab/internal-tools/blob/master/ksinai/rna-alignment.ml and hard-code my dataset paths? I realize the answer is probably "you can do whatever you want, this is just a library", but I think it'd be useful for us to come up a recommended style for using this library, and a tutorial for beginners like me to get started working in that way, at least for our work in hammer lab.

I'm finding the stuff in Common.ml pretty confusing. Would be really useful to have docs on things like:

• what's the basic idea behind the KEDSL extension to ketrew's EDSL? The only comment I can find on it is "The idea is carry around a type parameter to have arbitrary products.", which I don't understand.
  • what is the purpose of workflow_node and how does it differ from a ketrew target? Which should I use? If I'm supposed to use workflow_node, how do I specify its dependencies?
• What's a Dataset and why is that in internal-tools/ksinai instead of biokepi?

I'm also having a tough time understanding the Ketrew EDSL here: https://github.com/hammerlab/ketrew/blob/master/src/lib/ketrew_edsl.mli (or API docs in http://seb.mondet.org/software/ketrew/doc.1.0.0/api/Ketrew_edsl.html). For example, looking at target, I'm not clear what the active parameter means, and what I should set it to.

Thanks in advance for putting up with my ignorance: -)