From a3a1b6e94cca31d355220ac85ad2d084718eb731 Mon Sep 17 00:00:00 2001 From: Brian Ward Date: Mon, 29 Jan 2024 15:25:26 -0500 Subject: [PATCH] Automate R docs build from roxygen comments (#205) * Automate R docs build from roxygen comments * Update docs on docs --- .github/workflows/docs.yaml | 15 +- R/R/bridgestan.R | 2 +- R/R/compile.R | 34 +- R/convert_docs.R | 30 ++ R/man/StanModel.Rd | 5 - R/man/compile_model.Rd | 15 +- ...dgestan_path.Rd => get_bridgestan_path.Rd} | 11 +- R/man/set_bridgestan_path.Rd | 5 +- docs/conf.py | 24 + docs/internals/documentation.rst | 9 +- docs/languages/_r/README | 3 + docs/languages/_r/StanModel.md | 453 ++++++++++++++++++ docs/languages/_r/compile_model.md | 25 + docs/languages/_r/set_bridgestan_path.md | 11 + docs/languages/r.md | 427 +---------------- 15 files changed, 609 insertions(+), 460 deletions(-) create mode 100644 R/convert_docs.R rename R/man/{verify_bridgestan_path.Rd => get_bridgestan_path.Rd} (75%) create mode 100644 docs/languages/_r/README create mode 100644 docs/languages/_r/StanModel.md create mode 100644 docs/languages/_r/compile_model.md create mode 100644 docs/languages/_r/set_bridgestan_path.md diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 1020c165..0595c8d6 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -49,12 +49,25 @@ jobs: - name: Set up Julia uses: julia-actions/setup-julia@v1 - - name: Install package + + - name: Install R + uses: r-lib/actions/setup-r@v2.6.5 + + - name: Install R dependencies + uses: r-lib/actions/setup-r-dependencies@v2.6.5 + with: + packages: | + any::roxygen2 + github::Genentech/rd2markdown + + - name: Install packages run: | cd python/ pip install . cd ../julia julia --project=./docs -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()' + cd ../R/ + Rscript -e "install.packages(getwd(), repos=NULL, type=\"source\")" - name: Calculate version if: diff --git a/R/R/bridgestan.R b/R/R/bridgestan.R index e675a3a5..666278f8 100755 --- a/R/R/bridgestan.R +++ b/R/R/bridgestan.R @@ -1,6 +1,6 @@ #' StanModel #' -#' R6 Class representing a compiled BridgeStan model. +#' @description R6 Class representing a compiled BridgeStan model. #' #' This model exposes log density, gradient, and Hessian information #' as well as constraining and unconstraining transforms. diff --git a/R/R/compile.R b/R/R/compile.R index 8d5b414a..f2c43f84 100644 --- a/R/R/compile.R +++ b/R/R/compile.R @@ -2,16 +2,6 @@ IS_WINDOWS <- isTRUE(.Platform$OS.type == "windows") MAKE <- Sys.getenv("MAKE", ifelse(IS_WINDOWS, "mingw32-make", "make")) -#' Get the path to BridgeStan. -#' -#' By default this is set to the value of the environment -#' variable `BRIDGESTAN`. -#' -#' If there is no path set, this function will download -#' a matching version of BridgeStan to a folder called -#' `.bridgestan` in the user's home directory. -#' -#' See also `set_bridgestan_path` verify_bridgestan_path <- function(path) { suppressWarnings({ folder <- normalizePath(path) @@ -26,15 +16,25 @@ verify_bridgestan_path <- function(path) { } } -#' Set the path to BridgeStan. -#' -#' This should point to the top-level folder of the repository. +#' @title Function `set_bridgestan_path()` +#' @description Set the path to BridgeStan. +#' @details This should point to the top-level folder of the repository. #' @export set_bridgestan_path <- function(path) { verify_bridgestan_path(path) Sys.setenv(BRIDGESTAN = normalizePath(path)) } +#' Get the path to BridgeStan. +#' +#' By default this is set to the value of the environment +#' variable `BRIDGESTAN`. +#' +#' If there is no path set, this function will download +#' a matching version of BridgeStan to a folder called +#' `.bridgestan` in the user's home directory. +#' +#' @seealso [set_bridgestan_path] get_bridgestan_path <- function() { # try to get from environment path <- Sys.getenv("BRIDGESTAN", unset = "") @@ -54,8 +54,10 @@ get_bridgestan_path <- function() { } -#' Run BridgeStan's Makefile on a `.stan` file, creating the `.so` -#' used by the StanModel class. +#' @title Function `compile_model()` +#' @description Compiles a Stan model. +#' @details Run BridgeStan's Makefile on a `.stan` file, creating +#' the `.so` used by the StanModel class. #' This function checks that the path to BridgeStan is valid #' and will error if not. This can be set with `set_bridgestan_path`. #' @@ -67,6 +69,8 @@ get_bridgestan_path <- function() { #' threading for the compiled model. If the same flags are defined #' in `make/local`, the versions passed here will take precedent. #' @return Path to the compiled model. +#' +#' @seealso [bridgestan::set_bridgestan_path()] #' @export compile_model <- function(stan_file, stanc_args = NULL, make_args = NULL) { verify_bridgestan_path(get_bridgestan_path()) diff --git a/R/convert_docs.R b/R/convert_docs.R new file mode 100644 index 00000000..e0e22fd8 --- /dev/null +++ b/R/convert_docs.R @@ -0,0 +1,30 @@ +# Converts R documentation (.Rd) files to markdown (.md) files +# for use in Sphinx. + +library(rd2markdown) +library(roxygen2) + +roxygen2::roxygenize() + +files <- list.files("man", pattern="*.Rd") + +# we only want to doc exported functions, so we need +# to read the NAMESPACE file +namespace <- paste0(readLines("NAMESPACE"), collapse="\n") + +for (f in files){ + name <- substr(f, 1, nchar(f)-3) + + if (!grepl(name, namespace, fixed=TRUE)){ + print(paste0("Skipping unexported ", name)) + next + } + + # read .Rd file and convert to markdown + rd <- rd2markdown::get_rd(file=file.path(".", "man", f)) + md <- rd2markdown::rd2markdown(rd, fragments=c()) + + # write it to the docs folder + writeLines(md, file.path("..", "docs", "languages", "_r", paste0(name, ".md"))) + +} diff --git a/R/man/StanModel.Rd b/R/man/StanModel.Rd index 11197612..57ba7980 100644 --- a/R/man/StanModel.Rd +++ b/R/man/StanModel.Rd @@ -4,11 +4,6 @@ \alias{StanModel} \title{StanModel} \description{ -StanModel - -StanModel -} -\details{ R6 Class representing a compiled BridgeStan model. This model exposes log density, gradient, and Hessian information diff --git a/R/man/compile_model.Rd b/R/man/compile_model.Rd index bc5833c3..03d7202c 100644 --- a/R/man/compile_model.Rd +++ b/R/man/compile_model.Rd @@ -2,10 +2,7 @@ % Please edit documentation in R/compile.R \name{compile_model} \alias{compile_model} -\title{Run BridgeStan's Makefile on a \code{.stan} file, creating the \code{.so} -used by the StanModel class. -This function checks that the path to BridgeStan is valid -and will error if not. This can be set with \code{set_bridgestan_path}.} +\title{Function \code{compile_model()}} \usage{ compile_model(stan_file, stanc_args = NULL, make_args = NULL) } @@ -24,8 +21,14 @@ For example, \code{c('--O1')} will enable compiler optimization level 1.} Path to the compiled model. } \description{ -Run BridgeStan's Makefile on a \code{.stan} file, creating the \code{.so} -used by the StanModel class. +Compiles a Stan model. +} +\details{ +Run BridgeStan's Makefile on a \code{.stan} file, creating +the \code{.so} used by the StanModel class. This function checks that the path to BridgeStan is valid and will error if not. This can be set with \code{set_bridgestan_path}. } +\seealso{ +\code{\link[=set_bridgestan_path]{set_bridgestan_path()}} +} diff --git a/R/man/verify_bridgestan_path.Rd b/R/man/get_bridgestan_path.Rd similarity index 75% rename from R/man/verify_bridgestan_path.Rd rename to R/man/get_bridgestan_path.Rd index 02b7b406..f3556a73 100644 --- a/R/man/verify_bridgestan_path.Rd +++ b/R/man/get_bridgestan_path.Rd @@ -1,10 +1,10 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/compile.R -\name{verify_bridgestan_path} -\alias{verify_bridgestan_path} +\name{get_bridgestan_path} +\alias{get_bridgestan_path} \title{Get the path to BridgeStan.} \usage{ -verify_bridgestan_path(path) +get_bridgestan_path() } \description{ By default this is set to the value of the environment @@ -14,6 +14,7 @@ variable \code{BRIDGESTAN}. If there is no path set, this function will download a matching version of BridgeStan to a folder called \code{.bridgestan} in the user's home directory. - -See also \code{set_bridgestan_path} +} +\seealso{ +\link{set_bridgestan_path} } diff --git a/R/man/set_bridgestan_path.Rd b/R/man/set_bridgestan_path.Rd index 4130a632..ed9f2602 100644 --- a/R/man/set_bridgestan_path.Rd +++ b/R/man/set_bridgestan_path.Rd @@ -2,10 +2,13 @@ % Please edit documentation in R/compile.R \name{set_bridgestan_path} \alias{set_bridgestan_path} -\title{Set the path to BridgeStan.} +\title{Function \code{set_bridgestan_path()}} \usage{ set_bridgestan_path(path) } \description{ +Set the path to BridgeStan. +} +\details{ This should point to the top-level folder of the repository. } diff --git a/docs/conf.py b/docs/conf.py index fa73080d..0b73de00 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -140,6 +140,30 @@ else: print("Failed to build julia docs!\n", e) +try: + print("Building R doc") + subprocess.run( + ["Rscript", "convert_docs.R"], + cwd=pathlib.Path(__file__).parent.parent / "R", + check=True, + ) + + # delete some broken links in the generated R docs + StanModel = (pathlib.Path(__file__).parent / "languages" / "_r" / "StanModel.md") + text = StanModel.read_text() + start = text.find("### Public methods") + end = text.find("### Method `") + text = text[:start] + text[end:] + StanModel.write_text(text) + +except Exception as e: + # fail loudly in Github Actions + if RUNNING_IN_CI: + raise e + else: + print("Failed to build R docs!\n", e) + + try: print("Checking C++ doc availability") import breathe diff --git a/docs/internals/documentation.rst b/docs/internals/documentation.rst index 52997dd5..cdea0820 100644 --- a/docs/internals/documentation.rst +++ b/docs/internals/documentation.rst @@ -6,8 +6,8 @@ Documenting a mixed-language project such as BridgeStan can be tricky. We attempt to keep documentation in the natural place for each language: C/C++ code is documented with doxygen-style comments in the source, Python documentation -appears in docstrings, etc. With the exception of the R interface, our documentation -generation (powered by `Sphinx `__) automatically +appears in docstrings, etc. Our documentation generation +(powered by `Sphinx `__) automatically combines these together into the documentation you are reading now. To build the documentation, you can run ``make docs`` in the top-level directory. @@ -31,3 +31,8 @@ Similarly, the Julia documentation will only update if Julia is installed. Julia documentation is written in :file:`julia/docs/src/julia.md`. We then build this with `DocumenterMarkdown.jl `__, and the output is placed in :file:`docs/languages/julia.md`. + +Finally, the R documentation is primarily written in :file:`/docs/languages/r.md`. +The API documentation for R is done by including files generated by +`rd2markdown `__, which runs +on the results of the `roxygen2 package `__. diff --git a/docs/languages/_r/README b/docs/languages/_r/README new file mode 100644 index 00000000..0902f2e5 --- /dev/null +++ b/docs/languages/_r/README @@ -0,0 +1,3 @@ +These files are automatically generated in `conf.py` and should +not be manually edited. They are built from the documentation +comments in the R source code. diff --git a/docs/languages/_r/StanModel.md b/docs/languages/_r/StanModel.md new file mode 100644 index 00000000..ea3f9abe --- /dev/null +++ b/docs/languages/_r/StanModel.md @@ -0,0 +1,453 @@ +# StanModel + +R6 Class representing a compiled BridgeStan model. + +This model exposes log density, gradient, and Hessian information as well as constraining and unconstraining transforms. + +## Methods + +### Method `new()` + +Create a Stan Model instance. + +#### Usage + +``` +StanModel$new(lib, data, seed, stanc_args = NULL, make_args = NULL) +``` + + + +#### Arguments + +- **`lib`**: A path to a compiled BridgeStan Shared Object file or a .stan file (will be compiled). +- **`data`**: Either a JSON string literal, a path to a data file in JSON format ending in ".json", or the empty string. +- **`seed`**: Seed for the RNG used in constructing the model. +- **`stanc_args`**: A list of arguments to pass to stanc3 if the model is not already compiled. +- **`make_args`**: A list of additional arguments to pass to Make if the model is not already compiled. + + + +#### Returns + +A new StanModel. + + + + + + + +### Method `name()` + +Get the name of this StanModel. + +#### Usage + +``` +StanModel$name() +``` + + + +#### Returns + +A character vector of the name. + + + + + + + +### Method `model_info()` + +Get compile information about this Stan model. + +#### Usage + +``` +StanModel$model_info() +``` + + + +#### Returns + +A character vector of the Stan version and important flags. + + + + + + + +### Method `model_version()` + +Get the version of BridgeStan used in the compiled model. + +#### Usage + +``` +StanModel$model_version() +``` + + + + + + + + + +### Method `param_names()` + +Return the indexed names of the (constrained) parameters. 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 name "a.2.3". Parameter order of the output is column major and more generally last-index major for containers. + +#### Usage + +``` +StanModel$param_names(include_tp = FALSE, include_gq = FALSE) +``` + + + +#### Arguments + +- **`include_tp`**: Whether to include variables from transformed parameters. +- **`include_gq`**: Whether to include variables from generated quantities. + + + +#### Returns + +A list of character vectors of the names. + + + + + + + +### Method `param_unc_names()` + +Return the indexed names of the unconstrained parameters. 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 name "a.2.3". Parameter order of the output is column major and more generally last-index major for containers. + +#### Usage + +``` +StanModel$param_unc_names() +``` + + + +#### Returns + +A list of character vectors of the names. + + + + + + + +### Method `param_num()` + +Return the number of (constrained) parameters in the model. + +#### Usage + +``` +StanModel$param_num(include_tp = FALSE, include_gq = FALSE) +``` + + + +#### Arguments + +- **`include_tp`**: Whether to include variables from transformed parameters. +- **`include_gq`**: Whether to include variables from generated quantities. + + + +#### Returns + +The number of parameters in the model. + + + + + + + +### Method `param_unc_num()` + +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. + +#### Usage + +``` +StanModel$param_unc_num() +``` + + + +#### Returns + +The number of parameters in the model. + + + + + + + +### Method `param_constrain()` + +Returns a vector of constrained parameters given the unconstrained parameters. See also `StanModel$param_unconstrain()`, the inverse of this function. + +#### Usage + +``` +StanModel$param_constrain( + theta_unc, + include_tp = FALSE, + include_gq = FALSE, + rng +) +``` + + + +#### Arguments + +- **`theta_unc`**: The vector of unconstrained parameters. +- **`include_tp`**: Whether to also output the transformed parameters of the model. +- **`include_gq`**: Whether to also output the generated quantities of the model. +- **`rng`**: The random number generator to use if `include_gq` is `TRUE`. See `StanModel$new_rng()`. + + + +#### Returns + +The constrained parameters of the model. + + + + + + + +### Method `new_rng()` + +Create a new persistent PRNG object for use in `param_constrain()`. + +#### Usage + +``` +StanModel$new_rng(seed) +``` + + + +#### Arguments + +- **`seed`**: The seed for the PRNG. + + + +#### Returns + +A `StanRNG` object. + + + + + + + +### Method `param_unconstrain()` + +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. + +#### Usage + +``` +StanModel$param_unconstrain(theta) +``` + + + +#### Arguments + +- **`theta`**: The vector of constrained parameters. + + + +#### Returns + +The unconstrained parameters of the model. + + + + + + + +### Method `param_unconstrain_json()` + +This accepts a JSON string of constrained parameters and returns the unconstrained parameters. + +The JSON is expected to be in the [JSON Format for CmdStan](https://mc-stan.org/docs/cmdstan-guide/json.html). + +#### Usage + +``` +StanModel$param_unconstrain_json(json) +``` + + + +#### Arguments + +- **`json`**: Character vector containing a string representation of JSON data. + + + +#### Returns + +The unconstrained parameters of the model. + + + + + + + +### Method `log_density()` + +Return the log density of the specified unconstrained parameters. + +#### Usage + +``` +StanModel$log_density(theta_unc, propto = TRUE, jacobian = TRUE) +``` + + + +#### Arguments + +- **`theta_unc`**: The vector of unconstrained parameters. +- **`propto`**: If `TRUE`, drop terms which do not depend on the parameters. +- **`jacobian`**: If `TRUE`, include change of variables terms for constrained parameters. + + + +#### Returns + +The log density. + + + + + + + +### Method `log_density_gradient()` + +Return the log density and gradient of the specified unconstrained parameters. + +#### Usage + +``` +StanModel$log_density_gradient(theta_unc, propto = TRUE, jacobian = TRUE) +``` + + + +#### Arguments + +- **`theta_unc`**: The vector of unconstrained parameters. +- **`propto`**: If `TRUE`, drop terms which do not depend on the parameters. +- **`jacobian`**: If `TRUE`, include change of variables terms for constrained parameters. + + + +#### Returns + +List containing entries `val` (the log density) and `gradient` (the gradient). + + + + + + + +### Method `log_density_hessian()` + +Return the log density, gradient, and Hessian of the specified unconstrained parameters. + +#### Usage + +``` +StanModel$log_density_hessian(theta_unc, propto = TRUE, jacobian = TRUE) +``` + + + +#### Arguments + +- **`theta_unc`**: The vector of unconstrained parameters. +- **`propto`**: If `TRUE`, drop terms which do not depend on the parameters. +- **`jacobian`**: If `TRUE`, include change of variables terms for constrained parameters. + + + +#### Returns + +List containing entries `val` (the log density), `gradient` (the gradient), and `hessian` (the Hessian). + + + + + + + +### Method `log_density_hessian_vector_product()` + +Return the log density and the product of the Hessian with the specified vector. + +#### Usage + +``` +StanModel$log_density_hessian_vector_product( + theta_unc, + v, + propto = TRUE, + jacobian = TRUE +) +``` + + + +#### Arguments + +- **`theta_unc`**: The vector of unconstrained parameters. +- **`v`**: The vector to multiply the Hessian by. +- **`propto`**: If `TRUE`, drop terms which do not depend on the parameters. +- **`jacobian`**: If `TRUE`, include change of variables terms for constrained parameters. + + + +#### Returns + +List containing entries `val` (the log density) and `Hvp` (the hessian-vector product). diff --git a/docs/languages/_r/compile_model.md b/docs/languages/_r/compile_model.md new file mode 100644 index 00000000..bb424c53 --- /dev/null +++ b/docs/languages/_r/compile_model.md @@ -0,0 +1,25 @@ +# Function `compile_model()` + +```r +compile_model(stan_file, stanc_args = NULL, make_args = NULL) +``` + +## Arguments + +- `stan_file`: A path to a Stan model file. +- `make_args`: A vector of additional arguments to pass to Make. For example, `c('STAN_THREADS=True')` will enable threading for the compiled model. If the same flags are defined in `make/local`, the versions passed here will take precedent. +- `stanc_arg`: A vector of arguments to pass to stanc3. For example, `c('--O1')` will enable compiler optimization level 1. + +## Returns + +Path to the compiled model. + +Compiles a Stan model. + +## Details + +Run BridgeStan's Makefile on a `.stan` file, creating the `.so` used by the StanModel class. This function checks that the path to BridgeStan is valid and will error if not. This can be set with `set_bridgestan_path`. + +## See Also + +`set_bridgestan_path()` diff --git a/docs/languages/_r/set_bridgestan_path.md b/docs/languages/_r/set_bridgestan_path.md new file mode 100644 index 00000000..d97aeef4 --- /dev/null +++ b/docs/languages/_r/set_bridgestan_path.md @@ -0,0 +1,11 @@ +# Function `set_bridgestan_path()` + +```r +set_bridgestan_path(path) +``` + +Set the path to BridgeStan. + +## Details + +This should point to the top-level folder of the repository. diff --git a/docs/languages/r.md b/docs/languages/r.md index 7eb78208..fe6c2626 100644 --- a/docs/languages/r.md +++ b/docs/languages/r.md @@ -1,13 +1,5 @@ # R Interface -% The skeleton of this page was made using Roxygen2 and tools::Rd2txt, but it is not automated. -% Maybe it will be one day -% Used: -% roxygen2::roxygenize() -% tools::Rd2txt_options(underline_titles=FALSE, itemBullet="* ", showURLs=TRUE) -% tools::Rd2txt('./man/StanModel.Rd', 'r.txt') - - --- ## Installation @@ -49,427 +41,14 @@ An example program is provided alongside the R interface code in `example.R`: ## API Reference -### *R6::R6Class* `StanModel` - -`R6` Class representing a compiled BridgeStan model. - -This model exposes log density, gradient, and Hessian information -as well as constraining and unconstraining transforms. - -#### Methods - -**Method** `new()`: - -Create a Stan Model instance. - -_Usage_ - -```R -StanModel$new(lib, data, seed) -``` - - -_Arguments_ - - - `lib` A path to a compiled BridgeStan Shared Object file or a .stan file (will be compiled). - - `data` Either a JSON string literal, a path to a data file in JSON format ending in ".json", or the empty string. - - - `seed` Seed for the RNG used in constructing the model. - - - `stan_args` A list of arguments to pass to stanc3 if the model is not already compiled. - - - `make_args` A list of additional arguments to pass to Make if the model is not already compiled. - -_Returns_ - - A new StanModel. - - -**Method** `name()`: - -Get the name of this StanModel. - -_Usage_ - -```R -StanModel$name() +```{include} ./_r/StanModel.md ``` - -_Returns_ - - A character vector of the name. - - -**Method** `model_info()`: - -Get compile information about this Stan model. - -_Usage_ - -```R -StanModel$model_info() -``` - - -_Returns_ - - A character vector of the Stan version and important flags. - -**Method** `param_names()`: - -Return the indexed names of the (constrained) parameters. 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 name a.2.3. Parameter order of the output is column -major and more generally last-index major for containers. - -_Usage_ - -```R -StanModel$param_names(include_tp = FALSE, include_gq = FALSE) -``` - - -_Arguments_ - - - `include_tp` Whether to include variables from transformed - parameters. - - - `include_gq` Whether to include variables from generated - quantities. - - -_Returns_ - - A list of character vectors of the names. - - -**Method** `param_unc_names()`: - -Return the indexed names of the unconstrained parameters. 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 name a.2.3. Parameter order of the output is column -major and more generally last-index major for containers. - -_Usage_ - -```R -StanModel$param_unc_names() -``` - - -_Returns_ - - A list of character vectors of the names. - - -**Method** `param_num()`: - -Return the number of (constrained) parameters in the model. - -_Usage_ - -```R -StanModel$param_num(include_tp = FALSE, include_gq = FALSE) -``` - - -_Arguments_ - - - `include_tp` Whether to include variables from transformed - parameters. - - - `include_gq` Whether to include variables from generated - quantities. - - -_Returns_ - - The number of parameters in the model. - - -**Method** `param_unc_num()`: - -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. - -_Usage_ - -```R -StanModel$param_unc_num() -``` - - -_Returns_ - - The number of parameters in the model. - - -**Method** `param_constrain()`: - -Returns a vector of constrained parameters given the unconstrained parameters. See also `StanModel$param_unconstrain()`, the inverse -of this function. - -_Usage_ - -```R -StanModel$param_constrain(theta_unc, include_tp = FALSE, include_gq = FALSE, rng) -``` - - -_Arguments_ - - - `theta_unc` The vector of unconstrained parameters. - - - `include_tp` Whether to also output the transformed parameters - of the model. - - - `include_gq` Whether to also output the generated quantities - of the model. - - - `rng` The random number generator to use if `include_gq` is - `TRUE`. See `StanModel$new_rng()`. - - -_Returns_ - - The constrained parameters of the model. - - -**Method** `new_rng()`: - -Create a new persistent PRNG object for use in `param_constrain()`. - - -_Usage_ - -```R -StanModel$new_rng(seed) -``` - - -_Arguments_ - - - `seed` The seed for the PRNG. - -_Returns_ - - A `StanRNG` object. - - -**Method** `param_unconstrain()`: - -Returns a vector of unconstrained parameters given 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. - -_Usage_ - -```R -StanModel$param_unconstrain(theta) -``` - - -_Arguments_ - - - `theta` The vector of constrained parameters. - - -_Returns_ - - The unconstrained parameters of the model. - - -**Method** `param_unconstrain_json()`: - -This accepts a JSON string of constrained parameters and returns -the unconstrained parameters. - -The JSON is expected to be in the [JSON Format for -CmdStan](https://mc-stan.org/docs/cmdstan-guide/json.html). - -_Usage_ - -```R -StanModel$param_unconstrain_json(json) -``` - - -_Arguments_ - - - `json` Character vector containing a string representation of - JSON data. - - -_Returns_ - - The unconstrained parameters of the model. - - -**Method** `log_density()`: - -Return the log density of the specified unconstrained -parameters. - -_Usage_ - -```R -StanModel$log_density(theta_unc, propto = TRUE, jacobian = TRUE) -``` - - -_Arguments_ - - - `theta_unc` The vector of unconstrained parameters. - - - `propto` If `TRUE`, drop terms which do not depend on the - parameters. - - - `jacobian` If `TRUE`, include change of variables terms for - constrained parameters. - - -_Returns_ - - The log density. - - -**Method** `log_density_gradient()`: - -Return the log density and gradient of the specified -unconstrained parameters. - -_Usage_ - -```R -StanModel$log_density_gradient(theta_unc, propto = TRUE, jacobian = TRUE) -``` - - -_Arguments_ - - - `theta_unc` The vector of unconstrained parameters. - - - `propto` If `TRUE`, drop terms which do not depend on the - parameters. - - - `jacobian` If `TRUE`, include change of variables terms for - constrained parameters. - - -_Returns_ - - List containing entries `val` (the log density) and `gradient` - (the gradient). - - -**Method** `log_density_hessian()`: - -Return the log density, gradient, and Hessian of the specified -unconstrained parameters. - -_Usage_ - -```R -StanModel$log_density_hessian(theta_unc, propto = TRUE, jacobian = TRUE) -``` - - -_Arguments_ - - - `theta_unc` The vector of unconstrained parameters. - - - `propto` If `TRUE`, drop terms which do not depend on the - parameters. - - - `jacobian` If `TRUE`, include change of variables terms for - constrained parameters. - - -_Returns_ - - List containing entries `val` (the log density), `gradient` - (the gradient), and `hessian` (the Hessian). - - -**Method** `log_density_hessian_vector_product()`: - -Return the log density and the product of the Hessian -with the specified vector. - -_Usage_ - -```R -StanModel$log_density_hessian_vector_product(theta_unc, v, propto = TRUE, jacobian = TRUE) -``` - - -_Arguments_ - - - `theta_unc` The vector of unconstrained parameters. - - - `v` The vector to multiply the Hessian by. - - - `propto` If `TRUE`, drop terms which do not depend on the - parameters. - - - `jacobian` If `TRUE`, include change of variables terms for - constrained parameters. - - -_Returns_ - - List containing entries `val` (the log density) and `Hvp` - (the hessian-vector product). - ### Compilation utilities -**Function** `compile_model()`: - -Run BridgeStan's Makefile on a `.stan` file, creating the `.so` used by -the StanModel class. This function checks that the path to BridgeStan -is valid and will error if not. This can be set with `set_bridgestan_path()`. - -_Usage_ -```R -compile_model(stan_file, stanc_args = NULL, make_args = NULL) +```{include} ./_r/compile_model.md ``` -_Arguments_ - - - `stan_file` A path to a Stan model file. - - - `stanc_arg` A vector of arguments to pass to stanc3. For example, - `c("--O1")` will enable compiler optimization level 1. - - - `make_args` A vector of additional arguments to pass to Make. For example, - `c("STAN_THREADS=True")` will enable threading for the - compiled model. If the same flags are defined in - `make/local`, the versions passed here will take precedent. - -_Returns_ - - Path to the compiled `.so` file. - -**Function** `set_bridgestan_path()`: - -Set the path to BridgeStan. This should point to the top-level folder of the repository. - -_Usage_ -```R -set_bridgestan_path(path) +```{include} ./_r/set_bridgestan_path.md ```