Notebooks/docopt.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "## docopt ##\n",
    "One of the most infuriating things one can come across when coding is finding that *perfect package* that is supposed to do exactly what you need, but when you go to use it there is **NO documentation**! This is such a pet peeve of mine, that it has become a personal quest to make sure every inch of my code is annotated. This is when a seasoned programmer will ask \"what kind of documentation are we talking about?\"\n",
    "<br><br>\n",
    "See, there are essentially 3-4 different types of documentation. The first is inline comments. These are meant for *you* as a developer to remind yourself why that code exists. These are not really meant for the consumers of your code. \n",
    "<br>\n",
    "The second type of documentation is docstrings. These are the handy little descriptions that you type right after your shebang (`#!`) line or right after a function/class declaration. Docstrings are meant for a number of things, be it a brief summary of the function, descriptions of your arguments, potential errors, and returned/yielded values. Docstrings can also house brief code usage examples that are actually ***testable*** using the `doctest` function on the command line. \n",
    "<br>\n",
    "The third kind of documentation is actual online readable docs in the form of a web page or PDF. While this kind of documentation is **extremely** helpful, it actually doens't require a whole lot of effort because of tools like `Sphinx` which will autogenerate documentation based on how you have written your docstrings. Cool, huh?\n",
    "<br>\n",
    "The last form of documentation is your command line interface (CLI) help prompt (this is the stuff that comes up if you type *`command --help`*). Yes, almost **every** python program starts as CLI. Funny enough, most of the mainstream tools we use tend to have very elaborate help prompts (e.g. EVERY linux binary, samtools, bedtools, etc.) However, as developers, we often overlook this essential first step. This is where **`docopt`** comes into play."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Installation"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "%%bash\n",
    "pip install docopt\n",
    "# or \n",
    "conda install docopt"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, there are two frames of thought when composing your help prompt. One, and the most readily used, is the `argparse`/`click`/`begins` method, which explains each piece of the CLI and does argument handling via verbose script, but with the added benefit that is automatically compiles your help message based on how you have described your variable. An `argparse` example can be seen below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "parser.add_argument(\"-v\", \"--verbose\", help=\"increase output verbosity\", action=\"store_true\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "What this does is line does is makes a `-v` & `--verbose` flag that can be activated from the CLI upon calling the program, and makes the `--verbose` argument True. They even allow you to type in a help description that will show when you type `--help`. But this kind of setup means you have to type every single argument/option just like this, and that isn't counting things like sub-commands, mutually exclusive commands, positional vs keyword arguments, etc. \n",
    "<br><br>\n",
    "However, the other school of thought is to write your help message (as you would like it to look) and a parser will do all the rest of the work for you. This is the `docopt` way.\n",
    "<br><br>\n",
    "Below is a brief example of how to implement `docopt`. There are two things to keep in mind when using `docopt` though, the first is that you **must** use spaces, not `'\\t'` (tabs) to write your help prompt or else the parser will inaccurately parse your CL arguments. The second is that the help prompt must be entered right after you shebang (`#!`) line--as part of your docstring! "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "#!/usr/bin/env python\n",
    "\n",
    "\"\"\"Usage: workingTitle.py [options]\n",
    "\n",
    "Options:\n",
    "    -h, --help      show this help message\n",
    "    --window INT    Length of windows size used in ReadPuller\n",
    "    --control FILE  ReadPuller file containing read counts for control samples\n",
    "    --chip FILE     ReadPuller file containing read counts for ChIP-seq samples\n",
    "    --dnase FILE    ReadPuller file containing read counts for DNase-seq samples\n",
    "    --hicov FILE    ReadPuller file containing read counts for high coverage samples\n",
    "    --gc FILE       TAB-delimited file containing GC content for each window\n",
    "\"\"\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### More complex argument handling available"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "#!/usr/bin/env python\n",
    "\n",
    "\"\"\"Usage: workingTitle.py (-B <bamFile> -b <bedFile)\n",
    "          workingTitle.py [options]\n",
    "\n",
    "-B <bamFile>, --bam <bamFile>  BAM file to be processed\n",
    "-b BEDFILE, --bed BEDFILE  BED region file to be used\n",
    "\n",
    "Options:\n",
    "    -h, --help                   Show this help message\n",
    "    -w <int>, --winSize <int>    Value of window size used\n",
    "    -r <ref.fa>, --ref <ref.fa>  location of reference file\n",
    "\"\"\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here is what these two examples show:\n",
    "1. anything in square brackets ( [ ] ) are optional arguments\n",
    "2. anything in parenthesis are required arguments\n",
    "3. the flag used can be a short (`-h`) or long (`--help`) option if they are so defined\n",
    "4. the arguments can be annotated by either an angle bracket `<>` or as all caps (but be consistent)\n",
    "<br>\n",
    "You can go a bit further by using the pipe ( `|` ) symbol to indicate **OR** type events, like `[-h | --help]` meaning that either of those can be used to call the help function.\n",
    "<br><br>\n",
    "Now, what about using your handy help prompt? See below"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "from docopt import docopt\n",
    "\n",
    "def main():\n",
    "    args = docopt(__doc__)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "That's it! `args` is just a dictionary of your arguments that you can call by flag to retrieve the value stored in it. It is as simple as this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "import pandas as pd\n",
    "bed = args['--bed']\n",
    "bed = pd.read_csv(bed, delim = '\\t', index_col = 'start')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Lastly, since docopt is meant to be used as a help prompt, you don't even need to code anything else for the help message to work. `-h` & `--help` are protected namespaces used for printing the help statement. Using either of those will make the pretty help function you already typed show up to the user. Handy, right?"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}