Abstract
The C++ header files of the Stan project are provided by this package, but it contains little R code or documentation. The main reference is the vignette. There is a shared object containing part of the 'CVODES' library, but its functionality is not accessible from R. 'StanHeaders' is primarily useful for developers who want to utilize the 'LinkingTo' directive of their package's DESCRIPTION file to build on the Stan library without incurring unnecessary dependencies. The Stan project develops a probabilistic programming language that implements full or approximate Bayesian statistical inference via Markov Chain Monte Carlo or 'variational' methods and implements (optionally penalized) maximum likelihood estimation via optimization. The Stan library includes an advanced automatic differentiation scheme, 'templated' statistical and linear algebra functions that can handle the automatically 'differentiable' scalar types (and doubles, 'ints', etc.), and a parser for the Stan language. The 'rstan' package provides user-facing R functions to parse, compile, test, estimate, and analyze Stan models.
Introduction
StanHeaders serves as the essential "bridge" package that provides the C++ source headers of the Stan probabilistic programming language to the R ecosystem. It allows developers to tap into Stan’s powerful automatic differentiation and high-performance statistical algorithms to build their own specialized R packages without the overhead of a full Stan installation. By acting as a header-only repository, it enables researchers to write high-performance R extensions that leverage Stan’s numerical stability and speed without having to reinvent the wheel or force users to install the entire Stan modeling framework.
Bridging R and Stan C++
Stan is a gold standard for Bayesian inference, but its core power lies in its underlying C++ library—specifically its advanced automatic differentiation (AD) engine and specialized linear algebra functions. For developers building R packages, accessing these C++ tools was historically difficult due to complex dependency management. StanHeaders solves this by utilizing R’s native package system to expose C++ headers to other compiled packages via the LinkingTo directive.
This decoupling of the engine from the user-facing rstan package creates a modular architecture. It allows for a "leaner" development environment where one can use Stan's math library without necessarily using the Stan modeling language itself. The library highlights the use of "templated" C++ functions, which allow Stan to handle "differentiable" scalar types alongside standard doubles, enabling the automatic calculation of gradients essential for Hamiltonian Monte Carlo.
The stanFunction Utility
A standout feature of the package is the stanFunction utility. This tool wraps Rcpp::cppFunction, allowing a user to pass the name of a Stan Math Library function (such as log_sum_exp) and have it dynamically compiled and exposed as a native R function. This significantly lowers the barrier to entry for testing Stan’s math; instead of writing a full C++ file and manual wrappers, a researcher can test a Stan C++ function’s behavior directly from the R console.
As shown in the documentation for stanFunction, the utility accepts several parameters to manage the compilation environment and output. However, it does have specific functional constraints: it cannot handle "higher-order" functions (functions that take other functions as arguments, such as integrate_1d) or functions that operate on character strings.
Type Mapping and Data Translation
To facilitate the interaction between R and the Stan C++ library, the package manages the translation between R data types and Stan’s internal C++ types. This mapping is crucial for ensuring that data passed from the R environment is correctly interpreted by Stan's Eigen-based vectors and matrices.
This standardization provides a stable, versioned interface for the Stan C++ codebase within the CRAN ecosystem, enabling the existence of downstream packages like rstan. Through these mechanisms, users can access a vast library of Stan-specific functions—such as lkj_corr_rng or log_sum_exp—that are not natively available in R.
Limitations and Conclusion
While StanHeaders is a powerful developer tool, it is designed with a specific focus. It contains minimal R code or documentation because it is intended as a back-end resource. For instance, while it includes the CVODES library (part of the SUNDIALS suite) for solving ordinary differential equations, this functionality is strictly for developers to link against and is not directly accessible from R. Users looking for a high-level, user-facing interface are generally directed toward the rstan package, while StanHeaders remains the foundational layer for high-performance statistical computing in R.
Summary updated