*! version 1.2.4 03mar2021

Title

stan -- Use Stan software for Bayesian modeling: translate a Stan model to C++, compile to an executable file, sample from the posteriors using this, and display summaries.

Note! Since Stata version 16.0, Stan can be accessed via Python integration. Stan developers recommend this for speed and stability. StataStan (the -stan- command) is not maintained for Stata 16.0 and later versions.

Syntax

stan
varlist
[if] [in]
[, options]

Main
cmdstandir(path) location of the CmdStan directory

datafile(filename) destination text file for data on their way to Stan

modelfile(filename) .stan file containing the Stan model, or location of text file into which the model will be written

inline read the .stan model from a comment block insid ethe do-file

thisfile(filename) the name (and path, if required) of the current do-file, if inline has been specified (see Remarks)

rerun if specified, uses the existing executable file with the same name as modelfile (in Windows, it will have .exe extension). This should exist in the working directory. Be aware it will be copied into the cmdstandir (see below), overwriting any existing file of that name.

initsfile(filename) text file in R / S-plus format containing initial values

diagnose run Stan's diagnostics

outputfile(filename) destination text file for Stan outputs

chainfile(filename) destination for Stan chains in CSV format

mode run Stan's optimization to find posterior modes

modesfile(filename) destination text file for Stan estimation of modes

winlogfile(filename) temporary file to hold Windows output (see windowsmonitor)

seed random number generator seed for Stan

chains(integer) number of chains of draws from the posterior distribution; if possible, these will be run in parallel on multiple CPU cores

warmup(integer) number of warmup iterations

iter(integer) number of iterations to retain after warmup

thin(integer) thinning of iterations: retain one out of every thin

skipmissing remove missing data observation-wise before sending to Stan

matrices(string) list of matrices to send to Stan, or "all" to send all current matrices

globals(string) list of globals to send to Stan, or "all" to send all current global macros

keepfiles keep all files produced along the way; if not specified, the model file, C++ file, executable file, chains file and (if produced) modes file will be retained

stepsize(integer) HMC stepsize, default 1 (see Stan manual)

stepsizejitter(integer) HMC stepsize jitter, default 0 (see Stan manual)

nopywarn do not display the warning text about using Python in Stata 16+

by and fweights are not allowed.

Description

stan is the Stata interface to the open-source Bayesian software Stan, which works by translating a simple model language to C++ and compiling that.
Stan utilises Hamiltonian Monte Carlo through the No U-Turn Sampler (NUTS) to provide much faster and more stable sampling than could be achieved with the Metropolis-Hastings algorithm or the Gibbs sampler (these are the methods implemented in BUGS, JAGS and Stata commands like bayesmh and the bayes prefix).
In keeping with other Stan interfaces, it is known as StataStan when regarded as a package along with windowsmonitor. Additional stan_* commands are planned, which will populate specific models, like typing bayes logistic and the like in Stata 15 and up. The most recent updates can be found at github.com/stan-dev/statastan
In essence, it is a wrapper for the CmdStan command-line interface. Data and results are passed between Stata and Stan via text files.

To use stan, you will need to have CmdStan installed from http://mc-stan.org/interfaces/cmdstan.html where you will also find instructions on installation and checking that you can compile C++ programs.
The Stan programming manual and quick-start guide is at http://mc-stan.org/documentation/

If you are using stan on a Windows computer, you will need to install windowsmonitor too.

The variables listed in varlist will be sent to Stan, along with any global macros and matrices that are named in the relevant options.
If the option skipmissing is included, missing data will be excluded observation-wise, which means that each variable becomes a vector containing only the non-missing values.
This is potentially useful as a way of sending vectors of different lengths to Stan, but should be used with great caution if the current data contain missing values.

Options

Main

datafile name (and path if desired) of the text file to contain the data (variables, globals and matrices) in R / S-plus format (default is statastan_data.R in the working directory)

modelfile name (and path if desired) of the text file to contain the .stan model code (default is statastan_model.stan in the working directory)

inline indicates that Stata should read the Stan model from a comment block inside the current do-file, scanning lines until it finds a comment block that begins "data {"

thisfile name (and path if required) of the current do-file; in combination with inline, this will read the do-file using file read; if it is omitted but inline is specified, Stata will examine the temporary directory (type display c(tmpdir) to find this) for the latest file beginning ST or STD, depending on your operating system, which should contain the code that Stata is attempting to do.

initsfile text file containing initial values to send to Stan; in most cases, these do not have to be specified as convergence is faster and more likely than under Metropolis-Hastings or Gibbs

diagnose after sampling, run Stan's diagnostics and display the results

outputfile name (and path if required) for a text file to receive the outputs from Stan (default is output.csv in the working directory)

chainfile name (and path if required) for a CSV formatted file to hold the individual values from iterations of the Stan sampling; this can be read back into Stata by specifying the load option (default is statastan_chains.csv in the working directory)

mode use Stan's optimize function to find the modes of the posterior distributions by the L-BFGS algorithm; the default shows the means and medians

modesfile name (and path if required) of a text file to hold output from Stan optimization if the mode option has been specified (default is modes.csv in the working directory)

winlogfile name (and path if required) of a text file to hold output from Windows, so it can be displayed in almost-real-time using windowsmonitor (default is winlog.txt in the working directory)

seed integer random number generator seed to pass to Stan (it is not used in Stata)

warmup number of iterations to discard before storing chains; default is 1000

iter number of iterations to retain after warmup; default is 1000

thin to reduce autocorrelation and the need to store excessively long chains, save only every nth sample

skipmissing remove missing values from varlist observation-wise before sending to Stan; use with caution

matrices list of matrix names to send to Stan, or "all" to send all

globals list of matrix names to send to Stan, or "all" to send all

Remarks

StataStan is maintained and collaboratively developed at https://github.com/stan-dev/statastan where you can find the latest versions
and reports of issues that need to be fixed - and you can suggest improvements.
The Stan developers are listed at http://mc-stan.org/team

There are four ways of passing the model to Stan. Opinions differ on whether it is preferable to have the model in a separate .stan file, or inside the do-file. These are shown in the examples below.

Examples

// Bernoulli example:

// make your data
clear
set obs 10
gen y=0
replace y=1 in 2
replace y=1 in 10
count
global N=r(N)

// replace with your cmdstan folder's path
global cmdstandir "/root/cmdstan/cmdstan-2.6.2"

// here we present four different ways of combining the Stan model with your do-file

//##############################################
// Version 1: write a separate model file

/* call Stan, providing the modelfile option - no need to do anything else but you must
keep the .do and .stan files together for posterity */
stan y, modelfile("bernoulli.stan") cmd("$cmdstandir") globals("N")

//###########################################

/* Version 2: specify the model inline in a comment block, naming THIS do-file in the
thisfile option (the John Thompson method, adopted from his commands for interfacing with BUGS) */

// here's the model:
/*
data {
int<lower=0> N;
int<lower=0,upper=1> y[N];
}
parameters {
real<lower=0,upper=1> theta;
}
model {
theta ~ beta(1,1);
for (n in 1:N)
y[n] ~ bernoulli(theta);
}
*/

// call Stan with the inline and thisfile options.
// modelfile now tells it where to save your model
stan y, inline thisfile("/root/git/statastan/stan-example.do") ///
modelfile("inline-bernoulli.stan") ///
cmd("$cmdstandir") globals("N") load mode

//###############################################################

/* Version 3: use the comment block, but don't provide thisfile - Stata
will go looking for it in c(tmpdir), which saves you typing in the
do-file name and path, but might not work sometimes if c(tmpdir) is crowded,
or especialy if you have more than one instance of Stata running */

// here's the model:
/*
data {
int<lower=0> N;
int<lower=0,upper=1> y[N];
}}
parameters {
real<lower=0,upper=1> theta;
}
model {
theta ~ beta(1,1);
for (n in 1:N)
y[n] ~ bernoulli(theta);
}
*/

stan y, inline modelfile("inline-bernoulli.stan") ///
cmd("$cmdstandir") globals("N") load mode

//###############################################################

/* Version 4: specify the model inline, so it is written to the
text file of your choosing but everything is controlled from the do-file
(the Charles Opondo method) */

// make the data
clear
set obs 10
gen y=0
replace y=1 in 2
replace y=1 in 10
count
global N=r(N)

// write the model from Stata into a plain text file
tempname writemodel
file open `writemodel' using "mystanmodel.stan", write replace
#delimit ;
foreach line in
"data { "
" int<lower=0> N; "
" int<lower=0,upper=1> y[N];"
"} "
"parameters {"
" real<lower=0,upper=1> theta;"
"} "
"model {"
" theta ~ beta(1,1);"
" for (n in 1:N) "
" y[n] ~ bernoulli(theta);"
"}"
{;
#delimit cr
file write `writemodel' "`line'" _n
}
file close `writemodel'

// call Stan
stan y, modelfile("mystanmodel.stan") cmd("$cmdstandir") globals("N") load mode