Stanhl — Stan Syntax Highlighting in knitr

I needed a simple hack to highlight Stan syntax in
knitr files for a course I’m
taking — stanhl is that hack.
It’s quick and dirty (e.g. this took me thirty minutes to write), but I thought
I’d share before polishing it.

Requirements

You need http://pygments.org installed. The following should work:

$ pygmentize -V
Pygments version 1.6, (c) 2006-2013 by Georg Brandl.

If you don’t have Pygments installed, just install with the
Python Package Index:

$ pip install Pygments

Installation

Using the terrific devtools package, you
can install stanhl with:

install_github('vsbuffalo/stanhl')

If you don’t have devtools installed, use install.packages('devtools') first.

Using stanhl in LaTeX (Rnw) files

There are two steps:

1. Include the following in your LaTeX header:

    \usepackage{fancyvrb}
    \usepackage{color}
   
    <<echo=FALSE,results='asis'>>=
    library(stanhl)
    stanhl_latex()
    @
   

2. Write your Stan model, store it to a variable (e.g. to call with
   stan(model_code=x, ...), and then use:

    <<echo=FALSE,results='asis'>>=
    m <- "
    data {
      // stan stuff
    }
    model {
      // more stan stuff
    }
    "
    stanhl(m)
   
    @
   

Then, in another block call stan(), do other stuff, etc.

Using stanhl in RMarkdown files

I haven’t extensively tested Markdown support (swamped for the next few weeks),
but stanhl_html() should work as a replacement for stanhl_latex(). If it
doesn’t, feel free to submit a pull request. Below is the basic idea.

The header:

```{r,echo=FALSE,results='asis'}
library(stanhl)
stanhl_html()
```

The meat and potatoes (or tofu and eggplant):

```{r,echo=FALSE,results='asis'}
m <- "
data {
  int<lower=0> N;
  vector[N] weight;
  vector[N] diam1;
  vector[N] diam2;
  vector[N] canopy_height;
}
transformed data {
  vector[N] log_weight;
  vector[N] log_canopy_volume;
  log_weight        <- log(weight);
  log_canopy_volume <- log(diam1 .* diam2 .* canopy_height);
}
parameters {
  vector[2] beta;
  real<lower=0> sigma;
}
model {
  log_weight ~ normal(beta[1] + beta[2] * log_canopy_volume, sigma);
}
"
stanhl(m)

```

Highlighting Stan Models from File

You can also highlight a model directly from a .stan file:

mesquite_file <- system.file("inst", "extdata", "mesquite_volume.stan",
                             package="stanhl")
stanhl_file(mesquite_file)

# Then run your Stan model directly from file with something like:
# fit <- stan(mesquite_file, data=mesquite_data)

Styles

You can change Pygments style used in syntax
highlighting with:

 > stanhl_styles() # get available style list (depends on Pygments plugins)
 [1] "monokai"  "manni"    "rrt"      "perldoc"  "borland"  "colorful"
 [7] "default"  "murphy"   "vs"       "trac"     "tango"    "fruity"
[13] "autumn"   "bw"       "emacs"    "vim"      "pastie"   "friendly"
[19] "native"
> stanhl_opts$set(style="emacs")

See the vignette for these styles rendered.

Todo

I interfaced Pygments with R to create syntax highlighting for Stan, but
afterwards thought it might be useful to have a more general R-Pygments
interface. This interface is now the
pygmentr package; I am debating
whether to merge these two together, or just keep stanhl separate. For now,
there are some Stan-specific features I want, e.g. including Stan models from
file, so this package is worth it.