Stan is an open source, cross-platform suite of tools for probabilistic modeling. The Stan project primarily consists of three components: A language, a compiler, and a set of “C++ Headers”. Because it is primarily written in C++, the project has several interfaces, including Rstan, JuliaStan, StataStan, PyStan, CMDStan, CMDStanR, and others. We will be using Rstan.
When you write a model in the Stan language, the compiler converts the model code into C++ and includes the Stan Headers. The C++ source code must then be compiled into a program. Therefore, a C++ compiler toolchain must be installed and configured before using (R)Stan. This document guides you through that process on OSX and Windows 101.
Note: Catalina (OSX Version 10.15) and Pre-Catalina (OSX Versions < 10.15; e.g., High Sierra, Mojave) have different installation instructions. Please ensure you know which OSX version you are using, then go to the correct section. I tested the installation process on a fresh installation of High Sierra, Mojave, and Catalina.
Note: R 4.0 recently released. The instructions for R 4.0 can differ from 3.6.3 and earlier. Be mindful of which R you have installed, or are installing. When following the installation instructions, there is one panel for 3.6.3 an earlier, and another for 4.0 and later. Use the correct panel.
Use this section for R 3.6.3 and earlier
xcode-select --install
Rtools
.)macos-rtools-3.2.2.pkg
from hereinstall.packages("rstan")
. If any packages must be built from source, say No.Go here and follow the instructions.
Use this section for R 4.0 and later
xcode-select --install
Rtools
.)Nothing needed! Move onto the Rstan tab.
install.packages("rstan")
Go here and follow the instructions.
Use this section for R 3.6.3 and earlier
xcode-select --install
Rtools
.)install.packages("Rcpp", repos = "https://rcppcore.github.io/drat")
. Say “Yes” when prompted to install from sources.install.packages("rstan", type = "source")
Go here and follow the instructions.
Use this section for R 4.0 and later
xcode-select --install
Rtools
.)Nothing needed! Move onto the Rstan tab.
install.packages("rstan")
Go here and follow the instructions.
Use this section for R 3.6.3 and earlier
Rtools35.exe
from here.Rtools35.exe
to install RTools. Important: When you see a checkbox for “Add rtools to system path”, click the checkbox to enable it.install.packages("rstan")
Go here and follow the instructions.
Use this section for R 4.0 and later
rtools40-x86_64.exe
from here.rtools40-x86_64.exe
to install RTools. Accept all defaults.writeLines('PATH="${RTOOLS40_HOME}\\usr\\bin;${PATH}"', con = "~/.Renviron")
. Exit R.install.packages("rstan")
Go here and follow the instructions.
The code in this section is to test whether RStan is usable.
Copy and paste all of the following code into R(Studio) and run it.
Note: Make sure to run all of it, you may need to scroll to see it all.
# Load rstan
library(rstan)
# Set seed
set.seed(13)
# Make data
stan_data <- list(y = rnorm(500, 0, 1),
N = 500)
# Define model
stan_code <- "
/*
This model is just for testing.
*/
functions {
real times_two(real x) { // Custom function test.
return(x*2);
}
}
data {
int N; // Data length
vector[N] y; // Data
}
transformed data {
real a = 2.0; // Constant Test
}
parameters {
real<lower = 0> sigma; // Constraint test; residual SD
real mu; // Mean
}
transformed parameters {
real mu_over_sigma = mu / sigma; // Transformed param test.
}
model {
mu ~ normal(0, 1); // ~ syntax test.
target += student_t_lpdf(sigma | 5, 0, 1); // Increment test.
y ~ normal(mu, sigma); // Likelihood
}
generated quantities {
real b = normal_rng(0, 1); // RNG test
real c = times_two(a*b); // Custom Function test.
}
"
# Compile model
sm <- stan_model(model_code = stan_code)
# Run model on single core.
stanOut <- sampling(sm, data = stan_data, chains = 1, cores = 1, iter = 2000)
round(summary(stanOut)$summary, 5)
# Run model on multiple cores
stanOut <- sampling(sm, data = stan_data, chains = 4, cores = 4, iter = 2000)
round(summary(stanOut)$summary, 5)
Run the above and then compare your output, or examine any errors.
The output should look close to this (within a few decimal places):
mean se_mean sd 2.5% 25% 50%
sigma 1.04405 0.00055 0.03380 0.97955 1.02048 1.04310
mu 0.00285 0.00084 0.04727 -0.09233 -0.02750 0.00311
mu_over_sigma 0.00268 0.00080 0.04520 -0.08833 -0.02631 0.00295
b -0.00005 0.01580 1.01092 -1.96261 -0.68167 0.01641
c -0.00019 0.06319 4.04369 -7.85043 -2.72666 0.06566
lp__ -272.87483 0.02530 1.08191 -275.85477 -273.23449 -272.53438
75% 97.5% n_eff Rhat
sigma 1.06605 1.11447 3733.553 0.99987
mu 0.03455 0.09353 3158.630 0.99937
mu_over_sigma 0.03304 0.09024 3176.873 0.99939
b 0.67423 2.00185 4095.370 1.00019
c 2.69694 8.00738 4095.370 1.00019
lp__ -272.12221 -271.86788 1829.128 1.00355
If the summary output looks nothing like this, or has NA
/NaN
, contact me.
If stan_model
fails, there is a compiler configuration problem. Ensure you’ve followed the exact steps in the above section for your operating system. See the troubleshooting tab above for your OS to see if your error matches one listed. If these steps do not help, or if your error is not listed in troubleshooting, contact me for troubleshooting.
If sampling
fails when cores = 1, contact me with the error message and output.
If sampling
fails when cores = 4, contact me with the error message and output.
If you see a compilation error when calling stan_model()
that mentions something about pragma
or libstd++
, then follow the steps here. These errors appear if you upgrade from R 3.6.3 to R 4.0, and had a previous installation of the macos Rtools. I experienced this in Catalina, and did not test High Sierra or Mojave.
Note: Do not follow these steps if you are using R 3.6.3 or earlier. These steps effectively remove the pre-4.0 method for configuring the Macos-rtools. If you are on R 3.6.3 or earlier, the following steps will not solve the problem.
cd ~
and hit enter.sudo mv .Renviron .Renviron.bak
, hit entercd .R
, hit entersudo mv Makevars Makevars.bak
, hit enter↓ There are multiple tabs for different errors ↓
If you see an error similar to the following3:
Error in compileCode(f, code, language = language, verbose = verbose) : Compilation ERROR, function(s)/method(s) not created!
g++.exe: error: Files/R/R-3.6.2/library/StanHeaders/include/stan/math/prim/mat/fun/Eigen.hpp: No such file or directory
g++.exe: error: Files/R/R-3.6.2/library/StanHeaders/include: No such file or directory
g++.exe: error: Files/R/R-3.6.2/library/RcppEigen/include: No such file or directory
make: *** [C:/PROGRA~1/R/R-3.6.2/etc/x64/Makeconf:215: file4f647a08385b.o] Error 1
Solution
Try reinstalling rstan and StanHeaders using: install.packages(c("rstan","StanHeaders"), type = "source")
.
If you see an error similar to the following: 4
*** arch - i386
Error in .shlib_internal(args) :
C++14 standard requested but CXX14 is not defined
* removing 'C:/Users/Stephen Martin/Documents/R/win-library/3.6/rstan'
* restoring previous 'C:/Users/Stephen Martin/Documents/R/win-library/3.6/rstan'
The downloaded source packages are in
‘C:\Users\Stephen Martin\AppData\Local\Temp\RtmpW2sDwx\downloaded_packages’
Warning messages:
1: In install.packages(c("rstan", "StanHeaders"), type = "source") :
installation of package ‘StanHeaders’ had non-zero exit status
2: In install.packages(c("rstan", "StanHeaders"), type = "source") :
installation of package ‘rstan’ had non-zero exit status
Solution:
Open R and run:
dotR <- file.path(Sys.getenv("HOME"), ".R")
if (!file.exists(dotR)) dir.create(dotR)
M <- file.path(dotR, "Makevars.win")
if (!file.exists(M)) file.create(M)
cat("\nCXX14FLAGS=-O3 -march=corei7 -mtune=corei7",
"CXX14 = $(BINPREF)g++ -m$(WIN) -std=c++1y",
"CXX11FLAGS=-O3 -march=corei7 -mtune=corei7",
file = M, sep = "\n", append = TRUE)
Restart R, and run install.packages(c("rstan","StanHeaders"), type = "source")
.
If you see an error similar to the following:5
WARNING: Rtools is required to build R packages, but the version of Rtools previously installed in C:/rtools40 has been deleted.
Please download and install Rtools custom from http://cran.r-project.org/bin/windows/Rtools/.
Scanning R CMD config CC...
cc_path:
'' does not exist
Scanning path...
Scanning registry...
Found C:/rtools40 for 4.0
WARNING: Rtools is required to build R packages, but the version of Rtools previously installed in C:/rtools40 has been deleted.
Please download and install Rtools custom from http://cran.r-project.org/bin/windows/Rtools/.
WARNING: Rtools is required to build R packages, but the version of Rtools previously installed in C:/rtools40 has been deleted.
Please download and install Rtools custom from http://cran.r-project.org/bin/windows/Rtools/.
Error in file(con, "r") : cannot open the connection
In addition: Warning messages:
1: In system(cmd, intern = !verbose) :
running command 'C:/PROGRA~1/R/R-40~1.0/bin/x64/R CMD SHLIB file17028f27fa4.cpp 2> file17028f27fa4.cpp.err.txt' had status 1
2: In file(con, "r") :
cannot open file 'file17028f27fa4.cpp.err.txt': No such file or directory
Error in sink(type = "output") : invalid connection
Solution:
Open R and run: writeLines('PATH="${RTOOLS40_HOME}\\usr\\bin;${PATH}"', con = "~/.Renviron")
If you use Linux (like me), just make sure you have a reasonably recent version of gcc installed. You may need to modify ~/.R/Makevars
to include:
CXX14FLAGS=-O3 -mtune=native -march=native -Wno-unused-variable -Wno-unused-function -fPIC
CXX14 = g++
Then just run install.packages("rstan")
in R.↩︎
This step is apparently necessary due to Catalina security features. The software is open source and safe, but unsigned. The manual step of Right clicking and clicking open allows the user to circumvent these checks.↩︎
The reason this occurs is because CRAN released the StanHeaders 2.21 binary package, but rolled it back to 2.19. 2.19 is correct to use with Rstan 2.19; but the binary package is still stuck on 2.21. Blame CRAN.↩︎
The reason for this error is that Makevars.win does not define a C++ 14 compiler for some reason. Sometimes it does; sometimes it doesn’t; who knows. If this fix does not work, it is likely because Rtools was not installed with the system path modifications, and therefore BINPREF not being found.↩︎
The reason for this error is that Rtools 4.0 needs to have a “PATH” defined where the R build tools are located. For some reason, it doesn’t automatically set this up for you. The fix just adds the location of the build tools to the “PATH”, which is where Windows searches for executables.↩︎