MathematicaStan is a package to interact with CmdStan from Mathematica. It is developed under Linux and is compatible with Mathematica v8.0.

It works under Windows but you have to be careful about the way you enter paths:

• under Linux:

StanSetDirectory["YOUR_PATH/cmdstan"];

• under Windows:

StanSetDirectory["C:\\Users\\USER_NAME\\Documents\\R\\cmdstan-2.12.0"; 

Author & contact: picaud.vincent at gmail.com

Windows version: many thanks to Jeff Patterson for his valuable contribution.

A new version of the package is available in the v2 git branch. As soon as this new version is sufficiently tested, it will replace this one (which is archived in the v1 git branch).

See the How to modify options section (end of this page).

The command

StanRunSample["bernoulli",4]

uses 4 jobs for HMC sampling.

You can skip this step, a CmdStan.m file is already present in this directory.

Otherwise you have to know that the CmdStan.m file is automatically created from the CmdStan.org file using Emacs + org-mode. To generate the CmdStan.m, open the CmdStan.org file with Emacs and type c-c c-v t to create the CmdStan.m file.

First you must install CmdStan. Once this is done you get a directory containing stuff like:

bin  examples  LICENSE  make  makefile  README.md  runCmdStanTests.py  src  stan  test-all.sh

In my case, CmdStan is installed there:

~/GitHub/cmdstan

For Windows users it is possibly something like:

C:\\Users\\USER_NAME\\Documents\\R\\cmdstan-2.12.0

Download the package CmdStan.m and open it with Mathematica. The simplest way to install the package is to go to the Mathematica File->Install Menu, then follow the instructions.

There are two possibilities:

• You define where CmdStan is installed for each Mathematica session:

Needs["CmdStan`"];

(* Uncomment me for Linux *)
StanSetDirectory["YOUR_PATH/cmdstan"]; 

(* Uncomment me for Windows *)
(* StanSetdirectory["C:\\Users\\USER_NAME\\Documents\\R\\cmdstan-2.12.0"]; *)

• You define once for all, the stanDir variable in the package code source. Your CmdStan.m package, after installation, is generally stored there (at least under Linux):

~/.Mathematica/Applications/CmdStan.m

edit it and modify the line:

(* You can modify me (initial configuration) *)
stanDir="~/GitHub/cmdstan"; 

(* or for Windows *)
(* stanDir="C:\\Users\\USER_NAME\\Documents\\R\\cmdstan-2.12.0"; *)

according to your configuration.

For the moment use cases are illustrated by 3 examples. For these examples the Mathematica notebooks and the associated pdf files are available. Note that the pdf file are better viewed with an external software like evince or okular… for a reason I ignore, the GitHub version is not good (type “download” to open the pdf with your external pdf viewer).

We use the Examples/Bernoulli/bernoulli.stan example. You can find the Mathematica notebook bernoulli.nb or directly view the associated bernoulli.pdf file.

This example is a partial reproduction of the blog post Epistemology of the corral: regression and variable selection with Stan and the Horseshoe prior. Also see Bayesian survival analysis with horseshoe priors—in Stan!

You can find the Mathematica notebook horseShoePrior.nb or directly view the associated horseShoePrior.pdf file.

This use case is based on the soft-k-means example.

You can find the Mathematica notebook soft-k-means.nb or directly view the associated soft-k-means.pdf file.

The complete list of commands is:

Needs["CmdStan`"];
?CmdStan`*

RDumpExport
StanCodeExport
StanCompile
StanDirectory
StanFindVariableColumn
StanFindVariableIndex
StanGetOptionOptimize
StanGetOptionSample
StanGetOptionVariational
StanImport
StanImportComment
StanImportData
StanImportHeader
StanOptionOptimize
StanOptionSample
StanOptionVariational
StanRemoveOptionOptimize
StanRemoveOptionSample
StanRemoveOptionVariational
StanResetOptionOptimize
StanResetOptionSample
StanResetOptionVariational
StanRunOptimize
StanRunSample
StanRunVariational
StanSetDirectory
StanSetOptionOptimize
StanSetOptionSample
StanSetOptionVariational
StanVariable
StanVariableBoxPlot
StanVariableColumn
StanVariableFunc
StanVariableToImport

To get extra information about a peculiar function you can proceed as usual:

Needs["CmdStan`"];
?RDumpExport

RDumpExport[fileNameDataR_?StringQ,listOfNameValue_]

Creates a file and dump data in RDump format.

Note:
 - input data "listOfNameValue" is of the form 
   {{"MatrixName",{{...}}},{"ScalarName",5.6},{"VectorName",{..}},...}
 - if "fileName" has no extension, ".data.R" is automatically added.

Waiting for a more complete documentation, this section provides some specialized information.

The options are organized in a hierarchical way and you must provide this information when you want to modify option values. Options organization are described in the CmdStan user guide (“Command-Line Options” section).

In MathemeticaStan you have 3 predefined option lists that you can print using:

StanOptionOptimize[]
StanOptionSample[]
StanOptionVariational[]

Initial value is an empty list.

If you want to modify option for the Optimize method you must explictly provide the hierarchical information:

StanSetOptionOptimize["output.file","output_optimize.csv"];  
StanSetOptionOptimize["method.optimize.iter", 100]; 
StanSetOptionOptimize["method.optimize.algorithm", "bfgs"];
StanSetOptionOptimize["method.optimize.algorithm.bfgs.tol_grad", 10.^-5];

You can now view the option list:

StanOptionOptimize[]

Note that it is possible to overwrite option value

StanSetOptionOptimize["method.optimize.iter", 2016]; 

or to remove a peculiar option (given its exact name or a pattern).

StanRemoveOptionOptimize["method.optimize.iter"]; (* remove "method.optimize.iter" option *)
StanRemoveOptionOptimize["method*"]; (* remove ALL method* options *)

You can also remove all defined options by:

StanResetOptionOptimize[]

These option manipulations are illustrated in the Bernoulli example.

CAVEAT: by default the generated output.csv file is created into the current directory

Directory[]

If you want to modify this output directory you have two choices:

• Change the current directory of your Mathematica session:

SetDirectory["NewPathForOutputCSV/"]

• Modify the “output.file” option (see How to modify options)

StanSetOptionOptimize["output.file","NewPathForOutputCSV/output_optimize.csv"];  

Output importation and information extractions are illustrated in the soft-k-means example.

The involved functions are:

StanFindVariableColumn[...];
StanFindVariableIndex[...];

StanVariable[...]
StanVariableColumn[...];

StanVariableFunc[...];

Illustrated in the Bernoulli example.