#+OPTIONS: toc:nil todo:nil pri:nil tags:nil ^:nil tex:t #+TITLE: MathematicaStan v2.2 #+SUBTITLE: A Mathematica (v11+) package to interact with CmdStan #+AUTHOR: Picaud Vincent

[[https://zenodo.org/doi/10.5281/zenodo.10810144][file:https://zenodo.org/badge/66637604.svg]]

Table of contents :TOC_3:noexport:

[[#introduction][Introduction]]
- [[#news][News]]
  - [[#2024-08-13][2024-08-13]]
  - [[#2020-12-21][2020-12-21]]
  - [[#2019-06-28][2019-06-28]]
[[#installation][Installation]]
- [[#the-stan-cmdstan-shell-interface][The Stan CmdStan shell interface]]
- [[#the-mathematica-cmdstan-package][The Mathematica CmdStan package]]
- [[#first-run][First run]]
[[#tutorial-1-linear-regression][Tutorial 1, linear regression]]
- [[#introduction-1][Introduction]]
- [[#stan-code][Stan code]]
- [[#code-compilation][Code compilation]]
- [[#simulated-data][Simulated data]]
- [[#create-the-datar-data-file][Create the =data.R= data file]]
- [[#run-stan-likelihood-maximization][Run Stan, likelihood maximization]]
- [[#load-the-csv-result-file][Load the CSV result file]]
- [[#run-stan-variational-bayes][Run Stan, Variational Bayes]]
- [[#more-about-option-management][More about Option management]]
  - [[#overwriting-default-values][Overwriting default values]]
  - [[#reading-customized-values][Reading customized values]]
  - [[#erasing-customized-option-values][Erasing customized option values]]
[[#tutorial-2-linear-regression-with-more-than-one-predictor][Tutorial 2, linear regression with more than one predictor]]
- [[#parameter-arrays][Parameter arrays]]
- [[#simulated-data-1][Simulated data]]
- [[#exporting-data][Exporting data]]
- [[#run-stan-hmc-sampling][Run Stan, HMC sampling]]
- [[#load-the-csv-result-file-1][Load the CSV result file]]
[[#unit-tests][Unit tests]]

Introduction

MathematicaStan is a package to interact with [[http://mc-stan.org/interfaces/cmdstan][CmdStan]] from Mathematica.

It is developed under Linux and is compatible with Mathematica v11+

It should work under MacOS and also under Windows.

Author & contact: picaud.vincent at gmail.com

** News

*** 2024-08-13

New MathematicaStan version 2.2!

Package test with last CmdStan v2.35.0, Mathematica 11.2, Linux

Add some screenshots to the install procedure section
CmdStan syntax changes have been included : |----------------------------+-----------------------------------| | old | current | |----------------------------+-----------------------------------| | <- | = | | increment_log_prob(...) | target += ... | | int<lower=0,upper=1> y[N]; | array[N] int<lower=0, upper=1> y; | |----------------------------+-----------------------------------|
Check that unit tests and examples work.

*** 2020-12-21

New MathematicaStan version 2.1!

This version has been fixed and should now run under Windows.

I would like to thank Ali Ghaderi who had the patience to help me to debug the Windows version (I do not have access to this OS). Nothing would have been possible without him. All possibly remaining bugs are mine.

As a remainder also note that one should not use path/filename with spaces (=Make= really does not like that). This consign is also true under Linux or MacOS. See [[https://stackoverflow.com/questions/9838384/can-gnu-make-handle-filenames-with-spaces][SO:can-gnu-make-handle-filenames-with-spaces]] by example.

*** 2019-06-28

New MathematicaStan version 2.0!

This version uses Mathematica v11 and has been completely refactored

Caveat: breaking changes!

Note: the "old" MathematicaStan version based on Mathematica v8.0 is now archived in the [[https://github.com/stan-dev/MathematicaStan/tree/v1][v1 git branch]].

Installation

** The Stan CmdStan shell interface

First you must install [[http://mc-stan.org/interfaces/cmdstan][CmdStan]]. Once this is done you get a directory containing stuff like:

#+BEGIN_EXAMPLE bin doc examples Jenkinsfile LICENSE make makefile README.md runCmdStanTests.py src stan test-all.sh #+END_EXAMPLE

With my configuration CmdStan is installed in: #+BEGIN_EXAMPLE ~/ExternalSoftware/cmdstan-2.35.0 #+END_EXAMPLE

For Windows users it is possibly something like: #+BEGIN_EXAMPLE C:\Users\USER_NAME\Documents\R\cmdstan-?.??.? #+END_EXAMPLE

** The Mathematica CmdStan package

To install the Mathematica CmdStan package:

open the =CmdStan.m= file with Mathematica.
install it using the Mathematica Notebook File->Install menu.

Fill in the pop-up windows as follows: [[file:figures/install.png]]

** First run

The first time the package is imported #+BEGIN_SRC mathematica :eval never <<CmdStan` #+END_SRC you will get an error message: #+BEGIN_EXAMPLE CmdStan::cmdStanDirectoryNotDefined: CmdStan directory does not exist, use SetCmdStanDirectory[dir] to define it (with something like SetCmdStanDirectory["~/ExternalSoftware/cmdstan-2.35.0"]) #+END_EXAMPLE

This is normal as we must define the Stan StanCmd shell interface root directory.

With my configuration this is: #+BEGIN_SRC matheematica :eval never SetCmdStanDirectory["~/ExternalSoftware/cmdstan-2.35.0"] #+END_SRC

For Windows user this is certainly something like: #+BEGIN_SRC matheematica :eval never SetCmdStanDirectory["C:\Users\USER_NAME\Documents\R\cmdstan-?.??.?"] #+END_SRC

[[file:figures/Install_SetDir.png]]

Note: this location is recorded in the =$CmdStanConfigurationFile= file and you will not have to redefine it every time you import the CmdStan package.

Tutorial 1, linear regression

** Introduction

You can use the file =tutorial.wls= or manually follow the instruction below.

Import the package as usual

#+BEGIN_SRC mathematica :eval never <<CmdStan` #+END_SRC

This package defines these functions (and symbols):

#+BEGIN_SRC mathematica :eval never ?CmdStan`* #+END_SRC

For this tutorial we use a simple [[https://mc-stan.org/docs/2_19/stan-users-guide/linear-regression.html][linear regression]] example and we will work in a temporary location:

#+BEGIN_SRC mathematica :eval never SetDirectory[$TemporaryDirectory] #+END_SRC #+BEGIN_EXAMPLE /tmp #+END_EXAMPLE

** Stan code

Define the Stan code #+BEGIN_SRC mathematica :eval never stanCode = "data { int<lower = 0> N; vector[N] x; vector[N] y; } parameters { real alpha; real beta; real<lower = 0> sigma; } model { y ~normal(alpha + beta * x, sigma); }"; #+END_SRC

and export it

#+BEGIN_SRC mathematica :eval never stanCodeFile = ExportStanCode["linear_regression.stan", stanCode] #+END_SRC #+BEGIN_EXAMPLE /tmp/linear_regression.stan #+END_EXAMPLE

** Code compilation

Stan code compilation is performed by #+BEGIN_SRC mathematica :eval never stanExeFile = CompileStanCode[stanCodeFile] (* Attention: this takes some time *) #+END_SRC

With my configuration I get #+BEGIN_EXAMPLE make: Entering directory '/home/picaud/ExternalSoftware/cmdstan-2.35.0'

--- Translating Stan model to C++ code --- bin/stanc --o=/tmp/linear_regression.hpp /tmp/linear_regression.stan Model name=linear_regression_model Input file=/tmp/linear_regression.stan Output file=/tmp/linear_regression.hpp g++ -std=c++1y -pthread -Wno-sign-compare -O3 -I src -I stan/src -I stan/lib/stan_math/ -I stan/lib/stan_math/lib/eigen_3.3.3 -I stan/lib/stan_math/lib/boost_1.69.0 -I stan/lib/stan_math/lib/sundials_4.1.0/include -DBOOST_RESULT_OF_USE_TR1 -DBOOST_NO_DECLTYPE -DBOOST_DISABLE_ASSERTS -DBOOST_PHOENIX_NO_VARIADIC_EXPRESSION -c -MT /tmp/linear_regression.o -MT /tmp/linear_regression -include /tmp/linear_regression.hpp -include src/cmdstan/main.cpp -MM -E -MG -MP -MF /tmp/linear_regression.d /tmp/linear_regression.hpp

--- Linking C++ model --- g++ -std=c++1y -pthread -Wno-sign-compare -O3 -I src -I stan/src -I stan/lib/stan_math/ -I stan/lib/stan_math/lib/eigen_3.3.3 -I stan/lib/stan_math/lib/boost_1.69.0 -I stan/lib/stan_math/lib/sundials_4.1.0/include -DBOOST_RESULT_OF_USE_TR1 -DBOOST_NO_DECLTYPE -DBOOST_DISABLE_ASSERTS -DBOOST_PHOENIX_NO_VARIADIC_EXPRESSION -include /tmp/linear_regression.hpp src/cmdstan/main.cpp stan/lib/stan_math/lib/sundials_4.1.0/lib/libsundials_nvecserial.a stan/lib/stan_math/lib/sundials_4.1.0/lib/libsundials_cvodes.a stan/lib/stan_math/lib/sundials_4.1.0/lib/libsundials_idas.a -o /tmp/linear_regression make: Leaving directory '/home/picaud/ExternalSoftware/cmdstan-2.35.0' #+END_EXAMPLE

Note: if you do not want to have information printed you can use the =StanVerbose= option:

#+BEGIN_SRC mathematica :eval never stanExeFile = CompileStanCode[stanCodeFile, StanVerbose -> False] #+END_SRC

** Simulated data

Let's simulate some data: #+BEGIN_SRC mathematica :eval never σ = 3; α = 1; β = 2; n = 20; X = Range[n]; Y = α + βX + RandomVariate[NormalDistribution[0, σ], n]; Show[Plot[α + βx, {x, Min[X], Max[X]}], ListPlot[Transpose@{X, Y}, PlotStyle -> Red]] #+END_SRC

[[file:figures/linRegData.png][file:./figures/linRegData.png]]

** Create the =data.R= data file

The data are stored in a =Association= and then exported thanks to the =ExportStanData= function.

#+BEGIN_SRC mathematica :eval never stanData = <|"N" -> n, "x" ->

MathematicaStan

Install / Use

README