Introduction

Column

About this document

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.

Column

Instructions

  1. Go to the tab above for your operating system.
  2. Follow the instructions, in order, for your operating system.
  3. If any steps fail with errors, contact me before continuing. Windows users: You may want to try the troubleshooting section if steps fail.

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.

Mojave

R 3.6.3

Use this section for R 3.6.3 and earlier

R environment

  1. Download and install R-3.6.3.nn.pkg from here.
  2. (Optional). Install RStudio from here.

xcode

  1. Open spotlight and search for and open the “Terminal” app.
  2. Once the terminal appears, type the following and hit Return: xcode-select --install
  3. Agree to install xcode/developer tools, and wait for installation to complete.
  4. (If it says “command line tools are already installed”, then move onto Rtools.)

RTools

  1. Install macos-rtools-3.2.2.pkg from here

Rstan

  1. Open R(Studio).
  2. In the prompt, run the following: install.packages("rstan"). If any packages must be built from source, say No.

Testing

Go here and follow the instructions.

R 4.0

Use this section for R 4.0 and later

R environment

  1. Download and install R-4.0.0.pkg from here.
  2. (Optional). Install RStudio from here.

xcode

  1. Open spotlight and search for and open the “Terminal” app.
  2. Once the terminal appears, type the following and hit Return: xcode-select --install
  3. Agree to install xcode/developer tools, and wait for installation to complete.
  4. (If it says “command line tools are already installed”, then move onto Rtools.)

RTools

Nothing needed! Move onto the Rstan tab.

Rstan

  1. Open R(Studio).
  2. In the prompt, run the following: install.packages("rstan")

Testing

Go here and follow the instructions.

Catalina

R 3.6.3

Use this section for R 3.6.3 and earlier

R environment

  1. Download and install R-3.6.3.pkg from here. Note: It must be the R-3.6.3.pkg (Notarized, for Catalina) and not R-3.6.3.nn.pkg.
  2. (Optional). Install RStudio from here.

xcode

  1. Open spotlight and search for and open the “Terminal” app.
  2. Once the terminal appears, type the following and hit Return: xcode-select --install
  3. Agree to install xcode/developer tools, and wait for installation to complete.
  4. (If it says “command line tools are already installed”, then move onto Rtools.)

RTools

  1. Download (do not yet install) macos-rtools-3.2.2.pkg from here.
  2. Go to “Downloads” in the dock, click “Open in Finder”; or go to Finder and go to Downloads directory.
  3. Hold CTRL, and right-click on macos-rtools-3.2.2.pkg. Click Open. Install it.2

Rstan

  1. Open R(Studio).
  2. In the prompt, run the following: install.packages("Rcpp", repos = "https://rcppcore.github.io/drat"). Say “Yes” when prompted to install from sources.
  3. Run the following: install.packages("rstan", type = "source")

Testing

Go here and follow the instructions.

R 4.0

Use this section for R 4.0 and later

R environment

  1. Download and install R-4.0.0.pkg from here.
  2. (Optional). Install RStudio from here.

xcode

  1. Open spotlight and search for and open the “Terminal” app.
  2. Once the terminal appears, type the following and hit Return: xcode-select --install
  3. Agree to install xcode/developer tools, and wait for installation to complete.
  4. (If it says “command line tools are already installed”, then move onto Rtools.)

RTools

Nothing needed! Move onto the Rstan tab.

Rstan

  1. Open R(Studio).
  2. In the prompt, run the following: install.packages("rstan")

Testing

Go here and follow the instructions.

Windows 10

R 3.6.3

Use this section for R 3.6.3 and earlier

R environment

  1. Download and install R from here.
  2. (Optional). Install RStudio from here.

RTools

  1. Download Rtools35.exe from here.
  2. Run Rtools35.exe to install RTools. Important: When you see a checkbox for “Add rtools to system path”, click the checkbox to enable it.

RStan

  1. Open R(Studio).
  2. In the prompt, run the following: install.packages("rstan")

Testing

Go here and follow the instructions.

R 4.0

Use this section for R 4.0 and later

R environment

  1. Download and install R from here.
  2. (Optional). Install RStudio from here.

RTools

  1. Download rtools40-x86_64.exe from here.
  2. Run rtools40-x86_64.exe to install RTools. Accept all defaults.
  3. After installation, open R and run the following: writeLines('PATH="${RTOOLS40_HOME}\\usr\\bin;${PATH}"', con = "~/.Renviron"). Exit R.

RStan

  1. Open R(Studio).
  2. In the prompt, run the following: install.packages("rstan")

Testing

Go here and follow the instructions.

Test code

The code in this section is to test whether RStan is usable.

Test code column

Run this test code:

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.

Commentary column

Compare your output

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 you hit an error…

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.

MacOS

Column

Compilation ERROR

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.

  1. Quit R.
  2. Use Spotlight or Launchpad to open Terminal
  3. When in terminal, type cd ~ and hit enter.
  4. sudo mv .Renviron .Renviron.bak, hit enter
  5. cd .R, hit enter
  6. sudo mv Makevars Makevars.bak, hit enter
  7. Open R, and try the test code again.

Windows 10

↓ There are multiple tabs for different errors ↓

Column

Eigen.hpp: No such file or directory

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

CXX14 is not defined

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

rtools40 has been deleted

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

Footnotes


  1. 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.↩︎

  2. 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.↩︎

  3. 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.↩︎

  4. 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.↩︎

  5. 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.↩︎