Title: Pre-Compiled 'CmdStan' Models in R Packages
Description: Similar to 'rstantools' for 'rstan', the 'instantiate' package builds pre-compiled 'CmdStan' models into CRAN-ready statistical modeling R packages. The models compile once during installation, the executables live inside the file systems of their respective packages, and users have the full power and convenience of 'cmdstanr' without any additional compilation after package installation. This approach saves time and helps R package developers migrate from 'rstan' to the more modern 'cmdstanr'. Packages 'rstantools', 'cmdstanr', 'stannis', and 'stanapi' are similar Stan clients with different objectives.
Version: 0.2.3
License: MIT + file LICENSE
URL: https://wlandau.github.io/instantiate/, https://github.com/wlandau/instantiate
BugReports: https://github.com/wlandau/instantiate/issues
Depends: R (≥ 4.0.0)
Imports: callr, fs, rlang, utils
Suggests: knitr (≥ 1.30), markdown (≥ 1.1), rmarkdown (≥ 2.4), testthat (≥ 3.0.0), withr
Encoding: UTF-8
Language: en-US
Config/testthat/edition: 3
RoxygenNote: 7.3.2
NeedsCompilation: yes
Packaged: 2024-10-02 17:24:15 UTC; C240390
Author: William Michael Landau ORCID iD [aut, cre], Eli Lilly and Company [cph, fnd]
Maintainer: William Michael Landau <will.landau.oss@gmail.com>
Repository: CRAN
Date/Publication: 2024-10-02 18:20:06 UTC

instantiate: pre-compiled CmdStan models in R packages

Description

Similar to rstantools for rstan, the instantiate package builds pre-compiled CmdStan models into CRAN-ready statistical modeling R packages. The models compile once during installation, the executables live inside the file systems of their respective packages, and users have the full power and convenience of CmdStanR without any additional compilation after package installation. This approach saves time and helps R package developers migrate from rstan to the more modern CmdStanR.

Check if instantiate can find CmdStanR and CmdStan.

Description

Check if instantiate can find CmdStanR and CmdStan.

Usage

stan_cmdstan_exists(
  cmdstan_install = Sys.getenv("CMDSTAN_INSTALL", unset = "")
)

Arguments

cmdstan_install

Character of length 1, how to look for an installed copy of CmdStan. See https://wlandau.github.io/instantiate/ for details. Choices:

  1. "" (default): look at the original value that the CMDSTAN_INSTALL environment variable contained when instantiate at the time when it was installed. If it was "implicit" or "fixed", then choose the corresponding option below. Otherwise, default to "implicit".

  2. "implicit": Let the cmdstanr::cmdstan_path() decide where to look for CmdStan. As explained in the cmdstanr documentation, the output of cmdstanr::cmdstan_path() depends on the current value of the CMDSTAN environment variable. The cmdstanr package must be installed. If it is not installed, then stan_cmdstan_path() returns the empty string "".

  3. "fixed": Use the path to CmdStan that was originally contained in Sys.getenv("CMDSTAN") at the time when instantiate was installed.

Value

TRUE if instantiate can find the CmdStanR R package and the CmdStan command line tool. Returns FALSE otherwise.

See Also

Other cmdstan: stan_cmdstan_version()

Examples

stan_cmdstan_exists()

Path to CmdStan for instantiate

Description

Return the directory path to CmdStan that the instantiate package uses.

Usage

stan_cmdstan_path(cmdstan_install = Sys.getenv("CMDSTAN_INSTALL", unset = ""))

Arguments

cmdstan_install

Character of length 1, how to look for an installed copy of CmdStan. See https://wlandau.github.io/instantiate/ for details. Choices:

  1. "" (default): look at the original value that the CMDSTAN_INSTALL environment variable contained when instantiate at the time when it was installed. If it was "implicit" or "fixed", then choose the corresponding option below. Otherwise, default to "implicit".

  2. "implicit": Let the cmdstanr::cmdstan_path() decide where to look for CmdStan. As explained in the cmdstanr documentation, the output of cmdstanr::cmdstan_path() depends on the current value of the CMDSTAN environment variable. The cmdstanr package must be installed. If it is not installed, then stan_cmdstan_path() returns the empty string "".

  3. "fixed": Use the path to CmdStan that was originally contained in Sys.getenv("CMDSTAN") at the time when instantiate was installed.

Value

Character of length 1, directory path to CmdStan. The path may or may not exist. Returns the empty string "" if the path cannot be determined.

See Also

Other packages: stan_package_clean(), stan_package_compile(), stan_package_configure(), stan_package_model_files()

Examples

stan_cmdstan_path()

Version of CmdStan that instantiate uses.

Description

Return the version of CmdStan that the instantiate package uses.

Usage

stan_cmdstan_version(
  cmdstan_install = Sys.getenv("CMDSTAN_INSTALL", unset = ""),
  error_on_NA = TRUE
)

Arguments

cmdstan_install

Character of length 1, how to look for an installed copy of CmdStan. See https://wlandau.github.io/instantiate/ for details. Choices:

  1. "" (default): look at the original value that the CMDSTAN_INSTALL environment variable contained when instantiate at the time when it was installed. If it was "implicit" or "fixed", then choose the corresponding option below. Otherwise, default to "implicit".

  2. "implicit": Let the cmdstanr::cmdstan_path() decide where to look for CmdStan. As explained in the cmdstanr documentation, the output of cmdstanr::cmdstan_path() depends on the current value of the CMDSTAN environment variable. The cmdstanr package must be installed. If it is not installed, then stan_cmdstan_path() returns the empty string "".

  3. "fixed": Use the path to CmdStan that was originally contained in Sys.getenv("CMDSTAN") at the time when instantiate was installed.

error_on_NA

Logical of length 1, whether an error should be thrown if CmdStan is not found.

Value

Character of length 1, version of CmdStan that the instantiate package uses. If CmdStan is not found, then the return value depends on the error_on_NA argument.

See Also

Other cmdstan: stan_cmdstan_exists()

Examples

if (stan_cmdstan_exists()) {
  message(stan_cmdstan_version())
}

Remove one or more compiled Stan models in an R package.

Description

Remove one or more compiled Stan models from the file system of an R package.

Usage

stan_package_clean(models = instantiate::stan_package_model_files())

Arguments

models

Character vector of file paths to Stan model source code files. Defaults to the Stan files in ⁠./src/stan/⁠ because all the Stan model files must live in the ⁠src/stan/⁠ folder for an R package built with instantiate.

Value

NULL (invisibly). Called for its side effects.

See Also

Other packages: stan_cmdstan_path(), stan_package_compile(), stan_package_configure(), stan_package_model_files()

Examples

if (identical(Sys.getenv("INSTANTIATE_EXAMPLES"), "true")) {
path <- tempfile()
stan_package_create(path = path)
stan_package_configure(path = path)
models <- stan_package_model_files(path)
list.files(file.path(path, "inst", "stan"))
stan_package_compile(models)
list.files(file.path(path, "inst", "stan"))
# Clean up the compiled Stan model files:
stan_package_clean(models = models)
list.files(file.path(path, "inst", "stan"))
}

Compile the Stan models in an R package.

Description

Compile all Stan models in a directory, usually in a package.

Usage

stan_package_compile(
  models = instantiate::stan_package_model_files(),
  cmdstan_install = Sys.getenv("CMDSTAN_INSTALL", unset = ""),
  verbose = TRUE,
  quiet = FALSE,
  pedantic = FALSE,
  include_paths = NULL,
  user_header = NULL,
  cpp_options = list(),
  stanc_options = list(),
  force_recompile = getOption("cmdstanr_force_recompile", default = FALSE),
  threads = FALSE,
  ...
)

Arguments

models

Character vector of file paths to Stan model source code files. Defaults to the Stan files in ⁠./src/stan/⁠ because all the Stan model files must live in the ⁠src/stan/⁠ folder for an R package built with instantiate.

cmdstan_install

Character of length 1, how to look for an installed copy of CmdStan. See https://wlandau.github.io/instantiate/ for details. Choices:

  1. "" (default): look at the original value that the CMDSTAN_INSTALL environment variable contained when instantiate at the time when it was installed. If it was "implicit" or "fixed", then choose the corresponding option below. Otherwise, default to "implicit".

  2. "implicit": Let the cmdstanr::cmdstan_path() decide where to look for CmdStan. As explained in the cmdstanr documentation, the output of cmdstanr::cmdstan_path() depends on the current value of the CMDSTAN environment variable. The cmdstanr package must be installed. If it is not installed, then stan_cmdstan_path() returns the empty string "".

  3. "fixed": Use the path to CmdStan that was originally contained in Sys.getenv("CMDSTAN") at the time when instantiate was installed.

verbose

Logical of length 1, whether to set the cmdstanr_verbose global option to print more compiler messages than usual.

quiet

Argument to cmdstanr::cmdstan_model() to control compilation.

pedantic

Logical of length 1, whether to activate pedantic mode when compiling the Stan models. See the cmdstanr documentation for details.

include_paths

Argument to cmdstanr::cmdstan_model() to control model compilation.

user_header

Argument to cmdstanr::cmdstan_model() to control model compilation.

cpp_options

Argument to cmdstanr::cmdstan_model() to control model compilation.

stanc_options

Argument to cmdstanr::cmdstan_model() to model control compilation.

force_recompile

Argument to cmdstanr::cmdstan_model() to model control compilation.

threads

Argument to cmdstanr::cmdstan_model() to model control compilation.

...

Other named arguments to cmdstanr::cmdstan_model().

Details

If building a package using instantiate, all Stan model files must live in a folder called ⁠src/stan/⁠ in the package source directory.

Value

NULL (invisibly). Called for its side effects.

See Also

Other packages: stan_cmdstan_path(), stan_package_clean(), stan_package_configure(), stan_package_model_files()

Examples

if (identical(Sys.getenv("INSTANTIATE_EXAMPLES"), "true")) {
path <- tempfile()
stan_package_create(path = path)
stan_package_configure(path = path)
models <- stan_package_model_files(path)
list.files(file.path(path, "inst", "stan"))
stan_package_compile(models)
list.files(file.path(path, "inst", "stan"))
}

Configure an R package with built-in Stan models.

Description

Write configuration files in an R package which compile all the Stan models in ⁠src/stan/⁠ when the package installs.

Usage

stan_package_configure(path = getwd(), overwrite = FALSE)

Arguments

path

Character of length 1, file path to the package which will contain Stan models in ⁠src/stan/⁠ at installation time.

overwrite

Logical of length 1, whether to overwrite any existing configuration files.

Details

Writes configuration scripts configure and configure.win in the directory specified by the path argument.

Value

NULL (invisibly). Called for its side effects.

See Also

Other packages: stan_cmdstan_path(), stan_package_clean(), stan_package_compile(), stan_package_model_files()

Examples

if (identical(Sys.getenv("INSTANTIATE_EXAMPLES"), "true")) {
path <- tempfile()
stan_package_create(path = path)
list.files(path)
stan_package_configure(path = path)
list.files(path)
}

Create example package with a built-in Stan model.

Description

Create an example package with a Stan model inside.

Usage

stan_package_create(path = tempfile())

Arguments

path

Path to write the package. Must not already exist.

Details

After creating the package, the next step is to configure it with stan_package_configure(). After that, install it as an ordinary R package to automatically compile the models.

Value

NULL (invisibly). Called for its side effects.

Examples

if (identical(Sys.getenv("INSTANTIATE_EXAMPLES"), "true")) {
path <- tempfile()
stan_package_create(path = path)
list.files(path)
}

Get a pre-compiled Stan model built into an R package.

Description

Get the cmdstanr model object for a pre-compiled Stan model inside a package.

Usage

stan_package_model(
  name,
  package,
  library = NULL,
  cmdstan_install = Sys.getenv("CMDSTAN_INSTALL", unset = ""),
  compile = FALSE,
  ...
)

Arguments

name

Character of length 1, base name of the Stan model file (without the containing directory or .stan file extension).

package

Character of length 1, name of the R package to look for the built-in Stan model.

library

Character of length 1 or NULL, library path to look for the package with the built-in Stan model. Passed to the lib.loc argument of system.file().

cmdstan_install

Character of length 1, how to look for an installed copy of CmdStan. See https://wlandau.github.io/instantiate/ for details. Choices:

  1. "" (default): look at the original value that the CMDSTAN_INSTALL environment variable contained when instantiate at the time when it was installed. If it was "implicit" or "fixed", then choose the corresponding option below. Otherwise, default to "implicit".

  2. "implicit": Let the cmdstanr::cmdstan_path() decide where to look for CmdStan. As explained in the cmdstanr documentation, the output of cmdstanr::cmdstan_path() depends on the current value of the CMDSTAN environment variable. The cmdstanr package must be installed. If it is not installed, then stan_cmdstan_path() returns the empty string "".

  3. "fixed": Use the path to CmdStan that was originally contained in Sys.getenv("CMDSTAN") at the time when instantiate was installed.

compile

TRUE to compile the model and store the executable file where the package is installed in .libpaths(). FALSE to skip compilation and assume the model is already compiled, which is usually the case.

...

Named arguments passed via cmdstanr::cmdstan_model() to the compile() method of the CmdStan model object.

Details

Packages configured with instantiate compile their Stan models on installation. Then the stan_package_model() function retrieves the cmdstanr::cmdstan_model() object without needing to re-compile the model. Please see the documentation website of the instantiate package for examples.

Value

An R6 Stan model object from the cmdstanr package. Please visit the documentation website at https://mc-stan.org/cmdstanr/ for detailed information on the composition of this model object and how to use it to conduct Bayesian inference.

Examples

# Please see the documentation website of the {instantiate} package
#   for examples.

List Stan model file paths.

Description

List all the paths to the Stan model files in a package.

Usage

stan_package_model_files(path = getwd())

Arguments

path

Character of length 1, root path to start from when searching for Stan model files.

Details

All Stan models must live in the ⁠src/stan/⁠ directory in the package file system.

Value

Character vector of paths to Stan model files in the package.

See Also

Other packages: stan_cmdstan_path(), stan_package_clean(), stan_package_compile(), stan_package_configure()

Examples

path <- tempfile()
stan_package_create(path = path)
stan_package_model_files(path)