To use Stan from the command line or C++, first follow the appropriate platform-specific installation guide.
Building Stan itself works the same way across platforms.
To build Stan, first open the Terminal application. Then change directories to the directory in which Stan is installed (i.e., the directory containing the file named makefile).
% cd <stan-home>
Then make the library with
% make bin/libstan.a
and then make the model parser and code generator with
% make bin/stanc
Warning: The make program may take 10+ minutes and consume 2+GB of memory to build libstan and stanc. Compiler warnings, including uname: not found, may be safely ignored.
Building libstan.a and bin/stanc need only be done once.
The rest of this quick start guide explains how to code and run a very simple Bayesian model.
The following simple model is availabe in the source distribution located at <stan-home> as
data {
int<lower=0> N;
int<lower=0,upper=1> y[N];
}
parameters {
real<lower=0,upper=1> theta;
}
model {
for (n in 1:N)
y[n] ~ bernoulli(theta);
}
The model assumes the binary observed data y[1],...,y[N] are i.i.d. with Bernoulli chance-of-success theta. There is an implicit uniform prior on theta arising from the constraint in its definition in the parameters block restricting it to values between 0 and 1 (inclusive).
A data set of N=10 observations is availabe as
N <- 10 y <- c(0,1,0,0,0,0,0,0,0,1)
A single call to make will generate the C++ code for a model with a name ending in .stan and compile it for execution. This call will also compile the library libstan.a and the parser/code generator stanc.
First, change directories to where Stan was unpacked.
% cd <stan-home>
Then issue the command
% make src/models/basic_estimators/bernoulli
The C++ generated for the model and its compiled executable form will be placed in the same directory as the model.
The model can be executed from the directory in which it resides.
% cd src/models/basic_estimators
To execute the model under Linux or Mac, use
% ./bernoulli --data=bernoulli.Rdata
The ./ prefix before the executable is only required when executing a model from the directory in which it resides.
For the Windows DOS terminal, the ./ prefix is not needed, resulting in the command
% bernoulli --data=bernoulli.Rdata
Whether the command is run in Windows, Linux, or on the Mac, the output is the same. The parameters are echoed to the standard output, which shows up on the terminal as
STAN SAMPLING COMMAND data = bernoulli.Rdata init = random initialization init tries = 1 samples = samples.csv append_samples = 0 save_warmup = 0 seed = 1845979644 (randomly generated) chain_id = 1 (default) iter = 2000 warmup = 1000 thin = 1 (default) equal_step_sizes = 0 leapfrog_steps = -1 max_treedepth = 10 epsilon = -1 epsilon_pm = 0 delta = 0.5 gamma = 0.05
Then the sampler counts up the iterations in place, reporting percentage completed, ending with
Iteration: 2000 / 2000 [100%] (Sampling)
Each execution of the model results in a single Markov chain of samples stored in a file in comma-separated value (CSV) format. The default name of the output file is samples.csv.
The first part of the output file just repeats the parameters as comments.
# Samples Generated by Stan # # stan_version_major=1 # stan_version_minor=0 # stan_version_patch=0 # data=bernoulli.Rdata # init=random initialization # append_samples=0 # save_warmup=0 # seed=1845979644 # chain_id=1 # iter=2000 # warmup=1000 # thin=1 # equal_step_sizes=0 # leapfrog_steps=-1 # max_treedepth=10 # epsilon=-1 # epsilon_pm=0 # delta=0.5 # gamma=0.05
This is then followed by a header indicating the names of the values sampled, in this case
lp__,treedepth__,stepsize__,theta
with the first three names corresponding to log probability function value at the sample, the depth of tree evaluated by the NUTS sampler, and the step size. The single model parameter theta is stored in the fourth column.
Next up is the result of adaptation, reported as comments, here
# step size=1.43707 # parameter step size multipliers: # 1
This report says that NUTS step-size adaptation during warmup settled on a step size of 1.43707. The next two lines indicate the multipliers for scaling individual parameters, here just a single multiplier, 1, corresponding to the single parameter theta.
The rest of the file contains lines corresponding to the samples from each iteration.
-7.07769,1,1.43707,0.158674 -7.07769,1,1.43707,0.158674 -7.37289,1,1.43707,0.130089 -7.09254,1,1.43707,0.361906 -7.09254,1,1.43707,0.361906 -7.09254,1,1.43707,0.361906 -6.96213,1,1.43707,0.337061 -6.96213,1,1.43707,0.337061 -6.77689,1,1.43707,0.220795 -6.77689,1,1.43707,0.220795 -6.77689,1,1.43707,0.220795 -6.87869,1,1.43707,0.189999 -6.87869,1,1.43707,0.189999 -6.74837,1,1.43707,0.246732 -7.39894,1,1.43707,0.128071 ... -6.85235,1,1.43707,0.195994 -6.85235,1,1.43707,0.195994 -6.81491,1,1.43707,0.20624 -6.81491,1,1.43707,0.20624 -6.81491,1,1.43707,0.20624 -6.81491,1,1.43707,0.20624 -6.81491,1,1.43707,0.20624
There are repeated entries due to the Metropolis accept step in the NUTS algorithm.
The command-line options for running a model are detailed in the reference manual. They can also be printed on the command line in Linux and on the Mac with
./bernoulli --help
and on Windows with
bernoulli --help
To run the Stan unit tests of basic functionality, run the following commands from a shell.
% cd <stan-home>
% make O=0 test-unit
That's the letter O followed by an equal sign followed by the digit 0, which sets the tests to run at the lowest optimization level.
Warning: The make program may take 20+ minutes and consume 3+GB of memory to run the unit tests. Warnings can be safely ignored if the tests complete without a FAIL error.
The following document provides a user's guide for writing models in Stan along with a complete reference manual, including full documentation for running Stan from the command line.