学术资源 / 固定快照
CmdStanR 1.0 候选版改了编译方式
CmdStanR 是 Stan 开发团队维护的 R 接口：在 R 里编译 Stan 模型，交给命令行程序 CmdStan 运行，再把结果读回 R，代码采用 BSD 3-Clause 许可证。2026 年 10 月 15 日，团队在 Stan 官方论坛发布 1.0 候选版，改动集中在模型何时需要重新编译。本文为资料核验，未安装实测。  AI 生成示意图：在 R 中调用 Stan 模型，由 CmdStan 编译并运行算法，再把后验抽样结果读回 R 做汇总与作图。 ### 1.0 候选版的主要变化 截至 2026 年 10 月 21 日核验，GitHub 仓库 stan-dev/cmdstanr 发布页上的最新正式版仍是 2025 年 3 月 30 日的 v0.9.0。1.0 候选版没有作为正式 release 发布。项目负责人 Jonah Gabry 在论坛公告中说明，候选版放在 GitHub 的 v1.0 分支上，安装后 `packageVersion("cmdstanr")` 显示为 0.99.0，等这个分支合并后才会成为 1.0.0；仓库另有 v1.0.0-rc1 标签，指向 10 月 15 日的提交。公告称这是该包首发以来规模最大的一次更新，测试顺利的话计划在几周后发布正式版。候选版要求 R 4.0 及以上和 CmdStan 2.37.0 及以上，配套的文档、教程和更新日志单独放在 [mc-stan.org/cmdstanr/rc](https://mc-stan.org/cmdstanr/rc/)。 改动最大的是编译环节。旧版本只能可靠地发现 Stan 程序本身的修改；1.0 会记录可执行文件由哪些输入生成，包括 Stan 程序及其 `#include` 文件、用户头文件、`cpp_options`、`stanc_options`、`make/local` 和 CmdStan 版本，其中任何一项变化，再次调用 `cmdstan_model()` 时都会重新编译。可执行文件过期时，运行模型会直接报错，提示重新调用 `cmdstan_model()`，不再悄悄运行旧程序，`force_recompile` 参数也只在极少数情况下才需要。这份构建记录保存在可执行文件旁一个隐藏的 JSON 文件里，可用 `mod$build_info()` 查看；如果存放可执行文件的目录纳入 git 管理，官方建议把 `.*.cmdstanr.json` 加进 `.gitignore`。 不兼容的改动也集中在编译上。单独的 `$compile()` 方法和 `cmdstan_model()` 的 `compile = FALSE` 参数被移除，模型对象创建后总是可以直接使用；只想编译而不创建对象时，改用新函数 `compile_stan_file()`，它返回可执行文件的路径。`compile_standalone` 和 `compile_model_methods` 两个参数同样删除，对应功能仍由 `$expose_functions()` 和 `$init_model_methods()` 提供；`cpp_options` 必须写成具名列表；此前标为弃用的接口全部删除。按公告的说法，只用 `cmdstan_model()` 编译、拟合模型再读取抽样结果的用户，大多不会碰到这些变化。新增功能包括：基于 progressr 包的 MCMC 进度条（实验性）、对元组和复数的完整支持、读取 CSV 结果时内存占用明显减少、可写出压缩的输出文件、`$materialize()` 一次读入全部结果、`$save_object()` 可用 qs2 格式更快保存，以及 `install_cmdstan()` 升级时可沿用原有的 `make/local` 设置。 ### 安装与基本流程 使用 CmdStanR 要装两样东西：R 包本身，以及命令行程序 CmdStan。官方入门教程给出的稳定版安装方式是从 Stan 团队的 r-universe 仓库安装，并建议在新开的 R 会话中执行；试用 1.0 候选版则从 GitHub 的 v1.0 分支安装。CmdStan 需要可用的 C++ 工具链，先用 `check_cmdstan_toolchain()` 检查，具体要求见 CmdStan 安装指南，再用 `install_cmdstan()` 安装。截至核验日，CmdStan 最新正式版为 2.40.0，满足候选版的版本要求。 ```r # stable release from the Stan r-universe repository install.packages("cmdstanr", repos = c("https://stan-dev.r-universe.dev", getOption("repos"))) # or the 1.0 release candidate (reports version 0.99.0) # remotes::install_github("stan-dev/cmdstanr@v1.0") library(cmdstanr) check_cmdstan_toolchain() install_cmdstan(cores = 2) ``` `install_cmdstan()` 默认把 CmdStan 装到用户主目录下的 `.cmdstan/cmdstan-<版本号>`，加载 cmdstanr 时会自动选用其中版本号最大的一份；装在其他位置时，可以用环境变量 `CMDSTAN` 或 `set_cmdstan_path()` 指定，`cmdstan_path()` 和 `cmdstan_version()` 用来确认当前使用的路径和版本。 基本流程是编译、运行、读取三步。`cmdstan_model()` 读入 `.stan` 文件，由 CmdStan 把模型翻译成 C++ 并编译成可执行文件，返回一个 `CmdStanModel` 对象，各项操作都用 `$` 调用方法。`$sample()` 运行 Stan 默认的 MCMC 算法，数据可以是与 Stan 程序 data 块同名的 R 列表，也可以是 JSON 或 R dump 格式的数据文件；它返回 `CmdStanMCMC` 对象，再用 `$summary()` 汇总、`$draws()` 提取抽样、`$diagnostic_summary()` 查看发散转移等采样诊断。同一个模型对象还提供 `$optimize()`、`$laplace()`、`$variational()` 和 `$pathfinder()`，分别做优化求众数、拉普拉斯近似和两种变分推断。下面是官方教程中的伯努利示例，本文没有在本机运行： ```r library(cmdstanr) file <- file.path(cmdstan_path(), "examples", "bernoulli", "bernoulli.stan") mod <- cmdstan_model(file) # compiles only when the executable is out of date data_list <- list(N = 10, y = c(0, 1, 0, 0, 0, 0, 0, 0, 0, 1)) fit <- mod$sample( data = data_list, seed = 123, chains = 4, parallel_chains = 4 ) fit$summary() fit$diagnostic_summary() ```
- 收录日期
- 2026-10-21
- 类别
- 数据与评测
- 状态
- 资料核验，未安装实测
为何收录
做贝叶斯分析的研究者常用 Stan 写概率模型，而数据整理、作图和报告多半在 R 里完成。CmdStanR 把两边接起来：模型在 R 中调用，计算交给独立的 CmdStan 进程，结果再按 posterior 包的格式读回 R。由于 CmdStan 与 R 包分开安装，Stan 发布新版本时，通常升级 CmdStan 即可用上，不必等 R 包跟进。它适合已经用 R 做统计分析、需要自己编写 Stan 模型的研究生和研究人员，也适合用 brms 等上层包拟合多层模型、希望改用 CmdStan 作为计算后端的用户。
与 rstan 的区别
rstan 是 Stan 更早的 R 接口。按官方教程的对比，两者的根本差别在于怎样调用 Stan 的 C++ 代码：rstan 借助 Rcpp 在 R 进程的内存中运行 Stan；CmdStanR 在外部进程中运行 CmdStan，再读取输出文件，只有暴露 Stan 函数、计算对数密度和梯度等可选功能才用到 Rcpp。由此带来几点不同。CmdStanR 一方：升级 Stan 往往只需升级 CmdStan；推断过程与 R 进程隔离，推断中途出错时不容易把整个 R 会话一起带崩；结果先写入 CSV 文件、需要时才读进 R，R 会话的内存占用可能更低；许可证是 BSD 3-Clause，比 rstan 的 GPL（≥3）宽松，与 CmdStan 和 Stan C++ 源码一致。
rstan 一方的长处在安装：CRAN 为 Windows 和 macOS 提供 rstan 的二进制包，基于 rstan 的 R 包还能附带预编译好的模型，用户不装 C++ 工具链也能运行；它也不使用 R6 类，写法对多数 R 用户更熟悉。CmdStanR 用户开发 R 包时，可以用 instantiate 在安装阶段编译模型，但 CRAN 的构建机器上没有 CmdStan，这类包目前需要在装有 CmdStan 和 C++ 工具链的环境中从源码安装。
与 posterior、bayesplot、brms 的配合
CmdStanR 只负责运行算法，汇总和作图交给 Stan 生态里的其他包，官方把这种模块化写进了设计目标。posterior 是它的必需依赖：$summary() 内部调用 posterior::summarise_draws()，默认给出均值、中位数、分位数、R-hat 和有效样本量等指标；$draws() 返回 posterior 定义的 draws_array、draws_df 等格式。bayesplot 和 loo 列为建议依赖：抽样结果可以直接传给 bayesplot 的 mcmc_hist() 等绘图函数，下图就是官方教程这样画出的后验分布；拟合对象的 $loo() 方法则配合 loo 包做近似留一交叉验证，用于模型比较。
官方入门教程的示例：伯努利模型参数 theta 的后验抽样直方图，由 mcmc_hist(fit$draws("theta")) 绘制。图片：Jonah Gabry、Rok Češnovar、Andrew Johnson / Stan Development Team，来源 CmdStanR 1.0 候选版文档（Getting started with CmdStanR），许可 CC BY 4.0。
brms 用 R 公式语法描述多层回归等模型，再自动生成 Stan 代码。它的 brm() 函数有一个 backend 参数，默认值是 "rstan"，设为 "cmdstanr" 就改由 CmdStanR 拟合，也可以用 options(brms.backend = "cmdstanr") 在整个 R 会话中切换；这时传给 Stan 的额外参数会转交 CmdStanR 的 $sample() 或 $variational()。试用候选版要注意版本搭配：公告发布时，与它兼容的是 GitHub 上 brms 的 master 分支（对应 PR #1947），instantiate 已在 CRAN 发布兼容的 0.2.4 版，rethinking 则要安装 PR #477 的分支。公告还提到，新进度条同样适用于 brms 等以 CmdStanR 为后端的包。
局限与验收建议
选用前有几项限制需要确认。第一，必须有可用的 C++ 工具链，每个模型都要先编译成可执行文件才能运行；在无法安装编译环境的机房或教学电脑上，rstan 的二进制包更省事。第二，1.0 目前只是候选版，含有不兼容改动，正式版发布前仍可能调整；已有脚本如果用到 $compile()、compile = FALSE 或未具名的 cpp_options，需要按更新日志改写。新的重新编译逻辑正是候选期的测试重点，团队请用户报告不该重编译却重编译、该重编译却没有重编译的情况，以及与 make/local、用户头文件、#include 路径、R 包内模型相关的问题。第三，部分功能仍属实验性：新进度条目前只支持 MCMC，ADVI 变分推断在 CmdStan 的运行输出中也标注为实验性算法。此外，CmdStanR 用 R6 对象和 $ 调用方法，和常见的 R 函数写法不同，需要适应。
想判断候选版是否适合自己的项目，可以做一个小规模验收（这是建议，本文未执行）：在独立的 R 环境里从 v1.0 分支安装，用一个现有的 Stan 模型依次运行 cmdstan_model() 和 $sample()，固定随机种子，对照旧版本检查 $summary() 和 $diagnostic_summary() 的结果；再只改动一个 #include 文件或一项 cpp_options，看再次调用 cmdstan_model() 时是否按预期重新编译。遇到问题时，按公告要求附上 mod$build_info() 的输出，到 GitHub issues 或论坛帖下反馈。
参考文献
-
Jonah Gabry. CmdStanR 1.0 release candidate is now available. Stan Forums，2026-10-15。
-
stan-dev/cmdstanr. GitHub，2026-10-21 核验。
-
LICENSE.md（BSD 3-Clause License）. GitHub，2026-10-21 核验。
-
cmdstanr v0.9.0. GitHub，2025-03-30 发布。
-
DESCRIPTION（v1.0.0-rc1 标签）. GitHub，2026-10-21 核验。
-
R Interface to CmdStan（1.0 候选版文档）. Stan Development Team，2026-10-21 核验。
-
Jonah Gabry, Rok Češnovar, Andrew Johnson. Getting started with CmdStanR. CmdStanR 1.0 候选版文档，2026-10-21 核验。
-
brm(): Fit Bayesian Generalized (Non-)Linear Multivariate Multilevel Models. brms 文档，2026-10-21 核验。
-
CmdStan v2.40.0. GitHub，2026-10-21 核验。
-
信息由 Scholay 学术一站式平台 整理并发表，如有侵权请反馈下架。
-
信息同步发表于恩特学术，智能时代的学者社区
在交互式日历中查看这条记录 ↗
