A Mathematica package to interact with CmdStan
Switch branches/tags
Nothing to show
Clone or download

README.org

MathematicaStan

Introduction

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.

News

2017-08-01 Tue

Some doc, see Generated output.csv file and path.

2016-10-20 Thu

Complete refactoring of option management + doc

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

Parallel Sampling (Linux version only)

The command

StanRunSample["bernoulli",4]

uses 4 jobs for HMC sampling.

Getting started

Installation

Creation of the CmdStan.m file (not required)

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.

CmdStan installation

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

CmdStan.m installation

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.

CmdStan.m configuration

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.

Complete examples

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).

Bernoulli.stan

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

horseShoePrior.stan example

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.

soft-k-means.stan example

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.

Package documentation

Complete list of commands

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

Individual function documentation

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.

Selected topics documentation

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

How to modify options

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[]
method.optimize.algorithm.bfgs.tol_grad1e-05
method.optimize.algorithmbfgs
method.optimize.iter100
output.fileoutput_optimize.csv

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.

Generated output.csv file and path

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 variable access and manipulation

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

The involved functions are:

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

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

StanVariableFunc[...];

Parallel sampling (Linux only)

Illustrated in the Bernoulli example.