rmcelreath/rethinking: the R package that makes you write out every model assumption

What rmcelreath/rethinking is for, and who it is not for

This is an R package that accompanies a course and a book: McElreath 2020, Statistical Rethinking, 2nd edition, CRC Press. The README is direct about the audience. It contains tools for quick quadratic approximation of the posterior and for Hamiltonian Monte Carlo through RStan or cmdstanr. The stated signature difference is that the package forces the user to specify the model as a list of explicit distributional assumptions.

The README calls that approach more tedious than typical formula-based tools, and that is the honest framing. You do not write y ~ x1 + x2 and let the software infer the likelihood. You write the likelihood and each prior as separate formulas in an alist. The payoff the README claims is flexibility and, more importantly, teaching value: when students have to write out every detail of the model, they actually learn the model.

So the intended user is a student or instructor working through the book, or someone who wants a lightweight path from a list of priors to a Stan model without hand-writing Stan code. It is not aimed at analysts who want a tidy modelling interface, and it is not a general-purpose Bayesian toolkit for production use.

The alist model specification and what the package does with it

Every tool in the package takes the same input shape. The README gives this example of a simple Gaussian model:

f <- alist(
    y ~ dnorm( mu , sigma ),
    mu ~ dnorm( 0 , 10 ),
    sigma ~ dexp( 1 )
)

The first formula is the likelihood, the second is the prior for mu, the third is the prior for sigma. That ordering convention is the whole interface. From there the package branches in two directions. quap produces a quadratic approximation of the posterior. ulam and map2stan compile the same list into a Stan model and run Hamiltonian Monte Carlo.

ulam is the newer of the two Stan backends, and the README says new features will be added to ulam going forward. It allows explicit variable types and custom distributions, and it accepts Stan-style distribution names instead of R names, so normal(mu, sigma) works where dnorm(mu, sigma) would. map2stan is the original tool from the first edition and remains available.

The README also notes a naming history worth knowing: the quap function was called map in the first edition, and the alias still works. It was renamed because map was misleading, since the function returns a quadratic approximation of the posterior rather than a maximum a posteriori estimate.

Installing rethinking in R: three steps, and the CRAN trap

The README lays out three steps: install the C++ toolchain, install cmdstanr, then install rethinking. For the toolchain it points to the cmdstan installation page at mc-stan.org and says to follow the platform instructions there. For cmdstanr it points to mc-stan.org/cmdstanr, and notes that the first time you install cmdstanr you also need to compile the libraries with cmdstanr::install_cmdstan(). The README adds that if you do not want to use MCMC, you do not have to complete that step.

The third step is the one people get wrong. The package is not on CRAN and, per the README, never will be. Install it from GitHub:

install.packages(c("coda","mvtnorm","devtools","loo","dagitty","shape"))
devtools::install_github("rmcelreath/rethinking")

The README is explicit about the failure mode: if you get an error about rethinking not being available for your version of R, it is because you tried to install from CRAN. Use the GitHub call above.

A first real use, again from the README, fits the model defined earlier with quadratic approximation:

library(rethinking)

fit <- quap(
    f ,
    data=list(y=c(-1,1)) ,
    start=list(mu=0,sigma=1)
)

The README says fit holds the result and that summary(fit) or precis(fit) gives marginal posterior summaries. The output shown in the README has columns mean, sd, 5.5% and 94.5%, with mu near 0.00 and sigma near 0.84. If you want the Stan path instead, the same list goes to ulam:

fit_stan <- ulam( f , data=list(y=c(-1,1)) )

The README states the chain runs automatically provided rstan is installed, and that precis(fit_stan) adds n_eff and Rhat columns to the summary.

The slim branch, and when you can skip Stan entirely

There is a documented escape hatch for the first half of the course. The README describes a 'slim' version that avoids the MCMC and Stan installs:

install.packages(c("coda","mvtnorm","devtools","loo","dagitty"))
devtools::install_github("rmcelreath/rethinking@slim")

The README says quap and related helper functions should still work, and that you can work through Chapter 8 before you need the full version with Stan. This is the most practical detail in the entire document. The C++ toolchain is the step where installs fail, and the slim branch removes it for the early chapters.

The limitation is structural, not incidental. quap is a quadratic approximation, which means it assumes a roughly Gaussian posterior. The README itself says quap is limited to fixed effects models for the most part, while ulam can specify multilevel models, even quite complex ones. So the slim install is a genuine off-ramp, but it is an off-ramp that ends at the point where the book starts needing varying intercepts and slopes.

Posterior prediction and multilevel formulas in ulam

All quap, ulam and map2stan objects can be post-processed to produce posterior predictive distributions. The README assigns three functions to that job. link computes values of linear models over samples from the posterior. sim simulates outcomes over samples from the posterior of parameters, and can also simulate prior predictives. postcheck automatically computes posterior predictive checks, and the README notes it merely uses link and sim.

Multilevel specification is where the alist approach earns its keep. The README's varying intercepts example on the UCBadmit data writes the varying effect as an indexed parameter:

m_glmm1 <- ulam(
    alist(
        admit ~ binomial(applications,p),
        logit(p) <- a[dept] + b*male,
        a[dept] ~ normal( abar , sigma ),
        abar ~ normal( 0 , 4 ),
        sigma ~ half_normal(0,1),
        b ~ normal(0,1)
    ), data=UCBadmit )

Note the logit(p) <- a[dept] + b*male line. The linear model is declared with an assignment rather than a distribution, and the varying intercept is just a parameter with a subscript and its own prior. That is the flexibility the README advertises, and it is visible in the syntax rather than asserted.

One more detail that matters for anyone who wants to leave the package later: the stanfit object lives in the @stanfit slot, and the README says anything you would do with a Stan model can be done with that slot directly. stancode(fit_stan) prints the generated Stan code, so the model is not locked inside the R abstraction.

Where rethinking is the wrong tool

The package is not on CRAN and the README states it never will be. For a team maintaining an R package or a production pipeline, that is a hard constraint, not a preference. A dependency installed through devtools::install_github("rmcelreath/rethinking") pins you to a GitHub repository rather than a versioned CRAN release, and the recent release history is sparse: v2.2.1 in December 2021, 2.13 in August 2020, 2.12 in August 2020. The repository's last push was on 2026-06-10, so it is not abandoned, but the tagged releases do not track the commit history closely.

There is also a real install burden. The full path requires a C++ toolchain and a cmdstanr install with cmdstanr::install_cmdstan() to compile the libraries. That is a one-time cost the README acknowledges, but on a locked-down machine or a shared server it can be the difference between a working session and an afternoon of compiler errors. The slim branch avoids it and gives up multilevel models in exchange.

Finally, the explicit alist interface is a deliberate tax. If you already know exactly which model you want and it is a standard regression, writing out every prior buys you nothing over a formula interface, and it costs you time. The README's own justification for the design is pedagogical, and that justification does not transfer to an analyst who already understands the model.

How rethinking differs from brms and rstanarm

The natural comparison is with brms or rstanarm, both of which also fit Bayesian models in R through Stan. The difference is in what you type and what the software decides for you. brms and rstanarm take lme4-style formula syntax such as y ~ x + (1 | group) and generate the priors and the Stan code from that formula. rethinking takes the opposite position: you supply the likelihood and each prior as separate entries in an alist, and the package translates that list into Stan.

That difference has consequences in both directions. With a formula interface you get a large library of pre-built model structures and default priors, which makes standard multilevel models quick to fit. With rethinking you get control over every distributional assumption, including custom distributions and explicit parameter types in ulam, at the cost of writing each one. For the varying intercepts example above, a formula-based tool would express the varying intercept as a random-effect term and choose the prior for sigma itself; the rethinking version makes you write sigma ~ half_normal(0,1) yourself.

There is also a reachability difference. rethinking is installable only from GitHub, while brms and rstanarm are on CRAN. And because rethinking exposes the underlying stanfit in the @stanfit slot and prints Stan code with stancode(), you are not sealed off from the generated model, which is a reasonable middle position between a black-box formula interface and hand-written Stan.

Licence status and upgrade cost

The repository metadata does not state a licence, and the README does not mention one either. That is worth flagging before you build anything on top of the package: with no declared licence, the terms under which you may redistribute it or incorporate it into another work are not documented in the repository. If that matters for your use, the place to look is the DESCRIPTION file and the repository's own licensing statement, not this article.

Upgrade cost is low in the ordinary case because the package is installed from a GitHub branch rather than from a versioned CRAN release. Re-running devtools::install_github("rmcelreath/rethinking") pulls the current state of master, which means an upgrade is not a deliberate version bump unless you pin a tag or commit yourself. The slim install follows the same pattern against the slim branch. The practical consequence is that you should expect the installed code to move with the repository rather than with the release list, and the release list itself has been quiet since v2.2.1 in December 2021.

Editorial conclusion

Adopt rethinking if you are working through Statistical Rethinking or teaching Bayesian modelling and want students to state every distributional assumption explicitly. Do not adopt it if you need a CRAN-installable dependency for production pipelines, or if you only want a formula interface for a standard regression. Before you rely on it, verify that the C++ toolchain and cmdstanr are working on your platform, and check whether the slim branch covers the chapters you need, since the slim install omits Stan entirely.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. rmcelreath/rethinking on GitHub