diff --git a/R/R/bridgestan.R b/R/R/bridgestan.R index 7e416390..34e4a8ca 100755 --- a/R/R/bridgestan.R +++ b/R/R/bridgestan.R @@ -152,11 +152,11 @@ StanModel <- R6::R6Class("StanModel", }, #' @description #' Returns a vector of constrained parameters given the unconstrained parameters. - #' See also `StanModel$param_unconstrain()`, the inverse of this function. + #' See also [StanModel$param_unconstrain()], the inverse of this function. #' @param theta_unc The vector of unconstrained parameters. #' @param include_tp Whether to also output the transformed parameters of the model. #' @param include_gq Whether to also output the generated quantities of the model. - #' @param rng The random number generator to use if `include_gq` is `TRUE`. See `StanModel$new_rng()`. + #' @param rng The random number generator to use if `include_gq` is `TRUE`. See [StanModel$new_rng()]. #' @return The constrained parameters of the model. param_constrain = function(theta_unc, include_tp = FALSE, include_gq = FALSE, rng) { if (missing(rng)) { @@ -184,7 +184,7 @@ StanModel <- R6::R6Class("StanModel", vars$theta }, #' @description - #' Create a new persistent PRNG object for use in `param_constrain()`. + #' Create a new persistent PRNG object for use in [param_constrain()]. #' @param seed The seed for the PRNG. #' @return A `StanRNG` object. new_rng = function(seed) { @@ -194,9 +194,9 @@ StanModel <- R6::R6Class("StanModel", #' Returns a vector of unconstrained parameters give the constrained parameters. #' #' It is assumed that these will be in the same order as internally represented by - #' the model (e.g., in the same order as `StanModel$param_names()`). - #' If structured input is needed, use `StanModel$param_unconstrain_json()`. - #' See also `StanModel$param_constrain()`, the inverse of this function. + #' the model (e.g., in the same order as [StanModel$param_names()]). + #' If structured input is needed, use [StanModel$param_unconstrain_json()]. + #' See also [StanModel$param_constrain()], the inverse of this function. #' @param theta The vector of constrained parameters. #' @return The unconstrained parameters of the model. param_unconstrain = function(theta) { @@ -353,7 +353,7 @@ handle_error <- function(lib_name, err_msg, err_ptr, function_name) { #' StanRNG #' -#' RNG object for use with `StanModel$param_constrain()` +#' RNG object for use with [StanModel$param_constrain()] #' @field ptr The pointer to the RNG object. #' @keywords internal StanRNG <- R6::R6Class("StanRNG", diff --git a/R/R/compile.R b/R/R/compile.R index 306dc135..c2b5da14 100644 --- a/R/R/compile.R +++ b/R/R/compile.R @@ -34,7 +34,7 @@ set_bridgestan_path <- function(path) { #' a matching version of BridgeStan to a folder called #' `.bridgestan` in the user's home directory. #' -#' @seealso [set_bridgestan_path] +#' @seealso [set_bridgestan_path()] get_bridgestan_path <- function() { # try to get from environment path <- Sys.getenv("BRIDGESTAN", unset = "") diff --git a/R/man/StanModel.Rd b/R/man/StanModel.Rd index 267f9292..8dedc776 100644 --- a/R/man/StanModel.Rd +++ b/R/man/StanModel.Rd @@ -191,7 +191,7 @@ The number of parameters in the model. \if{latex}{\out{\hypertarget{method-StanModel-param_constrain}{}}} \subsection{Method \code{param_constrain()}}{ Returns a vector of constrained parameters given the unconstrained parameters. -See also \code{StanModel$param_unconstrain()}, the inverse of this function. +See also \code{\link[=StanModel$param_unconstrain]{StanModel$param_unconstrain()}}, the inverse of this function. \subsection{Usage}{ \if{html}{\out{
}}\preformatted{StanModel$param_constrain( theta_unc, @@ -210,7 +210,7 @@ See also \code{StanModel$param_unconstrain()}, the inverse of this function. \item{\code{include_gq}}{Whether to also output the generated quantities of the model.} -\item{\code{rng}}{The random number generator to use if \code{include_gq} is \code{TRUE}. See \code{StanModel$new_rng()}.} +\item{\code{rng}}{The random number generator to use if \code{include_gq} is \code{TRUE}. See \code{\link[=StanModel$new_rng]{StanModel$new_rng()}}.} } \if{html}{\out{
}} } @@ -222,7 +222,7 @@ The constrained parameters of the model. \if{html}{\out{}} \if{latex}{\out{\hypertarget{method-StanModel-new_rng}{}}} \subsection{Method \code{new_rng()}}{ -Create a new persistent PRNG object for use in \code{param_constrain()}. +Create a new persistent PRNG object for use in \code{\link[=param_constrain]{param_constrain()}}. \subsection{Usage}{ \if{html}{\out{
}}\preformatted{StanModel$new_rng(seed)}\if{html}{\out{
}} } @@ -245,9 +245,9 @@ A \code{StanRNG} object. Returns a vector of unconstrained parameters give the constrained parameters. It is assumed that these will be in the same order as internally represented by -the model (e.g., in the same order as \code{StanModel$param_names()}). -If structured input is needed, use \code{StanModel$param_unconstrain_json()}. -See also \code{StanModel$param_constrain()}, the inverse of this function. +the model (e.g., in the same order as \code{\link[=StanModel$param_names]{StanModel$param_names()}}). +If structured input is needed, use \code{\link[=StanModel$param_unconstrain_json]{StanModel$param_unconstrain_json()}}. +See also \code{\link[=StanModel$param_constrain]{StanModel$param_constrain()}}, the inverse of this function. \subsection{Usage}{ \if{html}{\out{
}}\preformatted{StanModel$param_unconstrain(theta)}\if{html}{\out{
}} } diff --git a/R/man/StanRNG.Rd b/R/man/StanRNG.Rd index e5f14dda..ff56e0d1 100644 --- a/R/man/StanRNG.Rd +++ b/R/man/StanRNG.Rd @@ -9,7 +9,7 @@ StanRNG StanRNG } \details{ -RNG object for use with \code{StanModel$param_constrain()} +RNG object for use with \code{\link[=StanModel$param_constrain]{StanModel$param_constrain()}} } \keyword{internal} \section{Public fields}{ diff --git a/R/man/get_bridgestan_path.Rd b/R/man/get_bridgestan_path.Rd index f3556a73..9c658401 100644 --- a/R/man/get_bridgestan_path.Rd +++ b/R/man/get_bridgestan_path.Rd @@ -16,5 +16,5 @@ a matching version of BridgeStan to a folder called \code{.bridgestan} in the user's home directory. } \seealso{ -\link{set_bridgestan_path} +\code{\link[=set_bridgestan_path]{set_bridgestan_path()}} } diff --git a/README.md b/README.md index 2b79f8f0..2e411454 100644 --- a/README.md +++ b/README.md @@ -103,7 +103,7 @@ We are aware of the following projects using BridgeStan. ## Research using BridgeStan If you use BridgeStan in your research, please consider citing [our JOSS paper](https://joss.theoj.org/papers/10.21105/joss.05236) -and letting us know so we list your project here. +and letting us know so we can list your project here. - [*Verified Density Compilation for a Probabilistic Programming Language*](https://doi.org/10.1145/3591245) - [*Variational Inference with Gaussian Score Matching*](https://arxiv.org/pdf/2307.07849.pdf) diff --git a/docs/getting-started.rst b/docs/getting-started.rst index 0c8236ab..24ac4b33 100644 --- a/docs/getting-started.rst +++ b/docs/getting-started.rst @@ -19,7 +19,8 @@ Downloading BridgeStan .. note:: The :doc:`Julia `, :doc:`Python `, and :doc:`R ` - interfaces will download the source for you the first time you compile a model. + interfaces will download the source for you the first time you compile a model, and the :doc:`Rust ` + interface has an optional feature to download the source upon request. This section is optional for users primarily interested in those interfaces. diff --git a/docs/index.rst b/docs/index.rst index ae1722af..0c13001b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,14 +1,14 @@ -Welcome to BridgeStan's documentation! -====================================== +BridgeStan -- efficient, in-memory access to the methods of a Stan model +======================================================================== -BridgeStan provides efficient in-memory access through Python, Julia, -R, and Rust to the methods of a `Stan `__ model, including -log densities, gradients, Hessians, and constraining and unconstraining -transforms. +BridgeStan is a library (with :doc:`bindings ` available in Python, +Julia, R, and Rust) that grants access to the methods of a `Stan `__ +model, including log densities, gradients, Hessians, and constraining and +unconstraining transforms. -The motivation is developing inference algorithms in -higher-level languages for arbitrary Stan models, such as those in +This allows researchers and library authors to develop inference algorithms in +higher-level languages and apply them to arbitrary Stan models, such as those in `posteriordb `__. diff --git a/docs/languages.rst b/docs/languages.rst index f21bcc1f..31ac50cc 100644 --- a/docs/languages.rst +++ b/docs/languages.rst @@ -8,11 +8,11 @@ written in C. All language interfaces expose the same core functionality from the :doc:`C API <./languages/c-api>`. -Additional "quality of life" features such as the ability to download -BridgeStan's source code automatically or compile models from inside the language -(rather than manually calling :command:`make`) are available on a best-effort basis. -If you are missing these features in your favorite language, we would welcome a -`contribution `__! + + +Additional "quality of life" features are available on a best-effort basis. +If BridgeStan's bindings to your favorite language are missing one of these features, we welcome +`contributions `__! .. toctree:: :maxdepth: 2 diff --git a/docs/languages/julia.md b/docs/languages/julia.md index 08c0ebde..b8b84fa1 100644 --- a/docs/languages/julia.md +++ b/docs/languages/julia.md @@ -131,7 +131,7 @@ Data should either be a string containing a JSON string literal, a path to a dat If seed is supplied, it is used to initialize the RNG used by the model's constructor. -source
+source
# **`BridgeStan.log_density`** — *Function*. @@ -147,7 +147,7 @@ Return the log density of the specified unconstrained parameters. This calculation drops constant terms that do not depend on the parameters if `propto` is `true` and includes change of variables terms for constrained parameters if `jacobian` is `true`. -source
+source
# **`BridgeStan.log_density_gradient`** — *Function*. @@ -165,7 +165,7 @@ This calculation drops constant terms that do not depend on the parameters if `p This allocates new memory for the gradient output each call. See [`log_density_gradient!`](julia.md#BridgeStan.log_density_gradient!) for a version which allows re-using existing memory. -source
+source
# **`BridgeStan.log_density_hessian`** — *Function*. @@ -183,7 +183,7 @@ This calculation drops constant terms that do not depend on the parameters if `p This allocates new memory for the gradient and Hessian output each call. See [`log_density_hessian!`](julia.md#BridgeStan.log_density_hessian!) for a version which allows re-using existing memory. -source
+source
# **`BridgeStan.log_density_hessian_vector_product`** — *Function*. @@ -201,7 +201,7 @@ This calculation drops constant terms that do not depend on the parameters if `p This allocates new memory for the output each call. See [`log_density_hessian_vector_product!`](julia.md#BridgeStan.log_density_hessian_vector_product!) for a version which allows re-using existing memory. -source
+source
# **`BridgeStan.param_constrain`** — *Function*. @@ -221,7 +221,7 @@ This allocates new memory for the output each call. See [`param_constrain!`](jul This is the inverse of [`param_unconstrain`](julia.md#BridgeStan.param_unconstrain). -source
+source
# **`BridgeStan.param_unconstrain`** — *Function*. @@ -241,7 +241,7 @@ This allocates new memory for the output each call. See [`param_unconstrain!`](j This is the inverse of [`param_constrain`](julia.md#BridgeStan.param_constrain). -source
+source
# **`BridgeStan.param_unconstrain_json`** — *Function*. @@ -259,7 +259,7 @@ The JSON is expected to be in the [JSON Format for CmdStan](https://mc-stan.org/ This allocates new memory for the output each call. See [`param_unconstrain_json!`](julia.md#BridgeStan.param_unconstrain_json!) for a version which allows re-using existing memory. -source
+source
# **`BridgeStan.name`** — *Function*. @@ -273,7 +273,7 @@ name(sm) Return the name of the model `sm` -source
+source
# **`BridgeStan.model_info`** — *Function*. @@ -289,7 +289,7 @@ Return information about the model `sm`. This includes the Stan version and important compiler flags. -source
+source
# **`BridgeStan.param_num`** — *Function*. @@ -305,7 +305,7 @@ Return the number of (constrained) parameters in the model. This is the total of all the sizes of items declared in the `parameters` block of the model. If `include_tp` or `include_gq` are true, items declared in the `transformed parameters` and `generate quantities` blocks are included, respectively. -source
+source
# **`BridgeStan.param_unc_num`** — *Function*. @@ -321,7 +321,7 @@ Return the number of unconstrained parameters in the model. This function is mainly different from `param_num` when variables are declared with constraints. For example, `simplex[5]` has a constrained size of 5, but an unconstrained size of 4. -source
+source
# **`BridgeStan.param_names`** — *Function*. @@ -339,7 +339,7 @@ For containers, indexes are separated by periods (.). For example, the scalar `a` has indexed name `"a"`, the vector entry `a[1]` has indexed name `"a.1"` and the matrix entry `a[2, 3]` has indexed names `"a.2.3"`. Parameter order of the output is column major and more generally last-index major for containers. -source
+source
# **`BridgeStan.param_unc_names`** — *Function*. @@ -355,7 +355,7 @@ Return the indexed names of the unconstrained parameters. For example, a scalar unconstrained parameter `b` has indexed name `b` and a vector entry `b[3]` has indexed name `b.3`. -source
+source
# **`BridgeStan.log_density_gradient!`** — *Function*. @@ -373,7 +373,7 @@ This calculation drops constant terms that do not depend on the parameters if `p The gradient is stored in the vector `out`, and a reference is returned. See [`log_density_gradient`](julia.md#BridgeStan.log_density_gradient) for a version which allocates fresh memory. -source
+source
# **`BridgeStan.log_density_hessian!`** — *Function*. @@ -391,7 +391,7 @@ This calculation drops constant terms that do not depend on the parameters if `p The gradient is stored in the vector `out_grad` and the Hessian is stored in `out_hess` and references are returned. See [`log_density_hessian`](julia.md#BridgeStan.log_density_hessian) for a version which allocates fresh memory. -source
+source
# **`BridgeStan.log_density_hessian_vector_product!`** — *Function*. @@ -409,7 +409,7 @@ This calculation drops constant terms that do not depend on the parameters if `p The product is stored in the vector `out` and a reference is returned. See [`log_density_hessian_vector_product`](julia.md#BridgeStan.log_density_hessian_vector_product) for a version which allocates fresh memory. -source
+source
# **`BridgeStan.param_constrain!`** — *Function*. @@ -429,7 +429,7 @@ The result is stored in the vector `out`, and a reference is returned. See [`par This is the inverse of [`param_unconstrain!`](julia.md#BridgeStan.param_unconstrain!). -source
+source
# **`BridgeStan.param_unconstrain!`** — *Function*. @@ -449,7 +449,7 @@ The result is stored in the vector `out`, and a reference is returned. See [`par This is the inverse of [`param_constrain!`](julia.md#BridgeStan.param_constrain!). -source
+source
# **`BridgeStan.param_unconstrain_json!`** — *Function*. @@ -467,7 +467,7 @@ The JSON is expected to be in the [JSON Format for CmdStan](https://mc-stan.org/ The result is stored in the vector `out`, and a reference is returned. See [`param_unconstrain_json`](julia.md#BridgeStan.param_unconstrain_json) for a version which allocates fresh memory. -source
+source
# **`BridgeStan.StanRNG`** — *Type*. @@ -485,7 +485,7 @@ This can be used in the [`param_constrain`](julia.md#BridgeStan.param_constrain) This object is not thread-safe, one should be created per thread. -source
+source
# **`BridgeStan.new_rng`** — *Function*. @@ -503,7 +503,7 @@ This can be used in the [`param_constrain`](julia.md#BridgeStan.param_constrain) The StanRNG object created is not thread-safe, one should be created per thread. -source
+source
diff --git a/docs/languages/rust.rst b/docs/languages/rust.rst index 6c24ecc3..5b2cf158 100644 --- a/docs/languages/rust.rst +++ b/docs/languages/rust.rst @@ -14,9 +14,12 @@ The BridgeStan Rust client is available on `crates.io ` +are still required and will not be automatically installed by this method. Example Program ---------------