bqmm

Bayesian Multilevel Quantile Regression

bqmm fits Bayesian mixed-effects (multilevel) quantile regression models in R using the asymmetric Laplace working likelihood and Stan. It lets you ask how a predictor relates to any quantile of an outcome — the median, the tails, or a whole grid — while accounting for clustered or repeated-measures data through random effects, and it returns full Bayesian uncertainty.

The package fills a genuine gap in the R ecosystem. Existing tools are either frequentist (lqmm, qrLMM), Bayesian but single-level (bayesQR, Brq), or able to fit multilevel quantile models only awkwardly and with statistically invalid uncertainty (brms’s asym_laplace()). bqmm provides a clean, quantile-first interface and valid fixed-effect inference via the Yang, Wang & He (2016) correction.

📖 Full documentation, primer, and articles: https://kvenkita.github.io/bqmm/

Installation

# install.packages("remotes")
remotes::install_github("kvenkita/bqmm")

bqmm compiles Stan models on installation, so a working C++ toolchain is required (Rtools on Windows, the standard compiler chain on macOS/Linux).

Quick start

library(bqmm)
data(Orthodont, package = "nlme")

# Conditional median of growth, with a random intercept per child
fit <- bqmm(distance ~ age + (1 | Subject), data = Orthodont, tau = 0.5)

summary(fit)              # fixed effects with valid (adjusted) intervals
VarCorr(fit)             # random-effect standard deviations

# Several quantiles in one call
fit_q <- bqmm(distance ~ age + (1 | Subject), data = Orthodont,
              tau = c(0.1, 0.5, 0.9))
plot(fit_q)              # coefficient-versus-quantile paths
predict(fit_q, noncrossing = "rearrange")   # non-crossing quantiles

Key features

Familiar lme4 formula interface — y ~ x + (1 + x | group); nested and crossed random effects work out of the box.
One or many quantiles in a single call (a scalar or vector tau).
Valid inference — the Yang, Wang & He (2016) posterior-variance correction is applied by default, fixing the well-known invalidity of naive asymmetric-Laplace credible intervals. Verified by simulation to cover at or above the nominal level.
Correlated random effects — cov = "unstructured" adds an LKJ-correlated random intercept and slope, with the correlation reported by VarCorr().
Non-crossing — optional post-hoc rearrangement so fitted quantiles never cross.
Ecosystem citizen — works with the posterior and bayesplot stacks via as_draws(), and ships the usual lme4/rstanarm-style methods.

Key functions

Function	Purpose
`bqmm()`	Fit a Bayesian multilevel quantile regression model
`bqmm_prior()`	Specify priors (fixed effects, scale, random-effect SDs, LKJ)
`ald()`	The asymmetric Laplace family object
`summary()`, `fixef()`, `coef()`	Fixed-effect estimates and intervals
`ranef()`, `VarCorr()`	Random effects and their (co)variances
`vcov(fit, adjusted = TRUE)`	Yang–Wang–He–corrected covariance
`predict()`, `fitted()`	Fitted / predicted conditional quantiles
`posterior_predict()`, `posterior_epred()`	Posterior predictive draws
`as_draws()`	Hand the fit to `posterior` / `bayesplot`
`rearrange_quantiles()`	Remove quantile crossing

Documentation

Primer — a thorough, accessible guide for applied researchers: the method, fitting, priors, inference, diagnostics, and visualization.
Get started — a short tour.
Multilevel structure — random intercepts/slopes, correlated and crossed effects.
Valid inference — why naive intervals fail and how the correction works.
Review & testing report — the validation evidence behind the package.
Function reference.

Citation

If you use bqmm, please cite it:

Venkitasubramanian, K. (2026). bqmm: Bayesian Multilevel Quantile Regression. R package version 0.1.0. https://github.com/kvenkita/bqmm

citation("bqmm")

Please also cite the underlying methodology where appropriate — Yu & Moyeed (2001) for the asymmetric Laplace approach and Yang, Wang & He (2016) for the inference correction.

Author and license

Created and maintained by Kailas Venkitasubramanian. Released under the MIT License.

References

Yu, K. & Moyeed, R. A. (2001). Bayesian quantile regression. Statistics & Probability Letters, 54(3), 437–447.
Kozumi, H. & Kobayashi, G. (2011). Gibbs sampling methods for Bayesian quantile regression. J. Stat. Comput. Simul., 81(11), 1565–1578.
Geraci, M. & Bottai, M. (2014). Linear quantile mixed models. Statistics and Computing, 24(3), 461–479.
Yang, Y., Wang, H. J. & He, X. (2016). Posterior inference in Bayesian quantile regression with asymmetric Laplace likelihood. International Statistical Review, 84(3), 327–344.
Chernozhukov, V., Fernández-Val, I. & Galichon, A. (2010). Quantile and probability curves without crossing. Econometrica, 78(3), 1093–1125.