Aug 27, 2020 | Daniel Lee
I’ve created a prototype that’s meant to be easier to use than CmdStan. If you’re a CmdStan user, I’d appreciate some feedback on what works and what doesn’t. Please comment here, on discourse, on twitter, or however you can find me.
The license for the prototype is 3-clause BSD (just like CmdStan).
Quick example: setting delta and max_depth
Here’s how to set delta to 0.9 and max_depth to 14.
Prototype:
> examples/bernoulli/bernoulli sample --delta 0.9 --max_depth 14 \
--data_file examples/bernoulli/bernoulli.data.R
Compare this to CmdStan v2.24.0:
> examples/bernoulli/bernoulli sample adapt delta=0.9 \
algorithm=hmc engine=nuts max_depth=14 \
data file=examples/bernoulli/bernoulli.data.R
What really makes the prototype easier to use is that the order of the options doesn’t matter. “--max_depth 14” could come first or last. In CmdStan, in order to set max_depth, you must keep these things together: “algorithm=hmc engine=nuts max_depth=14”.
Installation
The prototype is currently on a branch of CmdStan, feature/cli11. Since this is on a branch of CmdStan, there isn’t a single tarball that includes everything. (If there’s enough demand for it, I can package one up.)
Download using Git
These are instructions to get the source code using Git.
> git clone https://github.com/stan-dev/cmdstan cmdstan-cli11
> cd cmdstan-cli11
> git checkout feature/cli11
> git submodule update --init --recursive # this gets the Stan and Stan Math submodules
That’s it. That will get the prototype and grab all the related dependencies.
Build
Building the first Stan program will set up everything for you.
> make examples/bernoulli/bernoulli
Installation Complete
You can now build other executables with the prototype command line interface.
Usage
The usage of the protoype is similar to CmdStan v2.24.0. There are a few notable differences:
The first keyword after the executable name is the subcommand, with the exception of --help and --version flags.
Options are specified using dashes: -- for the long form and - for the short form.
Option order does not matter.
Values can come after the option name with a space or an equal sign.
The output files look exactly as if it were generated by CmdStan.
Synopsis
The executable is generated in the same way as with the existing CmdStan. To compile the examples/bernoulli/bernoulli.stan Stan program, we’d start with:
> make examples/bernoulli/bernoulli
Once that’s compiled, to run the program, it’d look like:
> examples/beroulli/bernoulli <subcommand> [<options>]
The subcommands are:
sample. Bayesian inference with Markov Chain Monte Carlo (aliases: s, mcmc)
optimize. Point estimation (aliases: o, optimise)
variational. Variational inference (aliases: v, advi)
diagnose. Model diagnostics (aliases: d, test)
generate_quantities. Generate quantities of interest (aliases: g, gq)
To get more information about any of the subcommands, add the --help flag after the subcommand.
Examples
Here are just some examples that show the usage of the prototype compared with CmdStan.
Sampling
Prototype (each line accomplishes the same thing):
> examples/bernoulli/bernoulli sample --data_file examples/bernoulli/bernoulli.data.R
> examples/bernoulli/bernoulli sample --data_file=examples/bernoulli/bernoulli.data.R
> examples/bernoulli/bernoulli sample -d examples/bernoulli/bernoulli.data.R
> examples/bernoulli/bernoulli mcmc -d examples/bernoulli/bernoulli.data.R
> examples/bernoulli/bernoulli s -d examples/bernoulli/bernoulli.data.R
CmdStan v2.24.0:
> examples/bernoulli/bernoulli sample data file=examples/bernoulli/bernoulli.data.R
Sampling with fixed seed and diagnostic file
Prototype:
> examples/bernoulli/bernoulli sample --data_file examples/bernoulli/bernoulli.data.R \
--seed 20200827 --diagnostic_file=diagnostic.csv
CmdStan v2.24.0:
> examples/bernoulli/bernoulli sample data file=examples/bernoulli/bernoulli.data.R \
random seed=20200827 output diagnostic_file=diagnostic.csv
In the prototype, there’s no order dependence of the options (after the subcommand), so you can move the order around. In CmdStan, keywords are often nested. For example, this would fail:
> examples/bernoulli/bernoulli sample data file=examples/bernoulli/bernoulli.data.R \
random seed=20200827 diagnostic_file=diagnostic.csv output
Motivation
CmdStan has been part of Stan since before v1.0; it was the first interface that turned a Stan program into something that could generate MCMC draws, predating RStan and PyStan. It was designed to be easy to use from the command line, easy to maintain, and easy to extend.
With CmdStan v2.0, these goals weren’t prioritized. This prototype gets closer to those original goals. It intentionally does not stray too far from the existing CmdStan arguments.
As a user, this it’s a lot easier for me to use. If you do find it easier, please let me know. If it’s still too clunky, that’s good to know too.
From a developer perspective, the prototype is soooo much simpler than CmdStan. It makes it easy to extend and add features that we just couldn’t introduce.
Note: this was a one-person effort (from design to implementation). There is definitely room for improvement.
Next Steps
The immediate next step is to get feedback. If you try it out and end up using it, please let me know! It’ll determine what happens next.
Long term, we (including you) need to determine what to do with the prototype. Logistically, it’ll be hard to replace CmdStan with this because of backwards compatibility. That leads to a few options:
If no one else uses it, then I’ll just maintain the branch on CmdStan.
If people really like it, then we can name it and either find a place for it in the stan-dev organization (if there’s a lot of community support) or I can maintain it.
Create Relevant Content
Writing a blog is a great way to position yourself as an authority in your field and captivate your readers’ attention. Do you want to improve your site’s SEO ranking? Consider topics that focus on relevant keywords and relate back to your website or business. You can also add hashtags (#vacation #dream #summer) throughout your posts to reach more people, and help visitors search for relevant content.
Blogging gives your site a voice, so let your business’ personality shine through. Choose a great image to feature in your post or add a video for extra engagement. Are you ready to get started? Simply create a new post now.