September 22, 2017

Using markstat for Literate Programming in Stata

I’ve been a long-time fan of literate programming for data science, primarily in the form of Jupyter Notebooks. However, sometimes I prefer Stata over Python for data analysis.

Stata 15 introduced dynamic Markdown documents via the dyndoc command, which I’ve been meaning to try out. However, the syntax is pretty cumbersome:

We will use the auto dataset. It includes variable price:
~~~~
<<dd_do>>
webuse auto, clear
summarize price
<</dd_do>>
~~~~
The mean of price is 6165. We will also ...

Specifically the XML-esque <<dd_do>> tags to delimit Stata commands make my fingers – and eyes – bleed.

When searching around for examples of Stata’s dyndoc command, I ran across this page comparing dyndoc to something called markstat. Lo and behold, this is somewhat similar to the output of my literate Python with pweave and Atom setup, minus the inline execution of code.

I generally use Sublime Text 3 with the excellent Stata Enhanced plugin to edit my Stata code. I run it line-by-line using the cmd-enter keyboard shortcut to send the current line in Sublime over to Stata.

I was able to edit my Sublime Text keybindings to enable this cmd-enter behavior when editing a Markdown file using the MarkdownEditing plugin like so:

  {
    "keys": ["super+enter"],
    "command": "run_macro_file",
    "args": {"file": "Packages/Stata Enhanced/stata-send-command-move-next-line.sublime-macro"},
    "context":
      [
        { "key": "selector", "operator": "equal", "operand": "text.html.markdown" }
      ]
  }

(The downside: if you fat-finger cmd-enter with a non-Stata command line, it will still try to send that to Stata. In practice, this is not a problem for me.)

Sublime Text will allow you to select Markdown code blocks with cmd-shift-enter, so this makes it very easy to run a bunch of lines of code at once. Here’s what this looks like in action. Note that I run all these Stata commands with keyboard shortcuts – I never need to touch the mouse.

 

When I’m ready to generate a .html file from the Markdown, I simply run markstat using path/to/markdown.stmd and get output that looks like this:

 

Here’s the source Markdown file and output HTML file if you’re curious.

The setup for markstat is a bit involved, but the author provides good instructions.

Comments? Please send me a message.

Subscribe via RSS or email.