{"id":16273646,"url":"https://github.com/wlandau/instantiate","last_synced_at":"2025-03-16T13:31:15.867Z","repository":{"id":182711252,"uuid":"668968305","full_name":"wlandau/instantiate","owner":"wlandau","description":"Pre-compiled CmdStan models in R packages","archived":false,"fork":false,"pushed_at":"2024-10-02T19:05:31.000Z","size":738,"stargazers_count":23,"open_issues_count":2,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-13T13:19:39.296Z","etag":null,"topics":["bayesian-statistics","cmdstan","cmdstanr","markov-chain-monte-carlo","mc-stan","stan"],"latest_commit_sha":null,"homepage":"https://wlandau.github.io/instantiate/","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wlandau.png","metadata":{"files":{"readme":"README.Rmd","changelog":"NEWS.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-21T03:16:59.000Z","updated_at":"2024-12-11T19:03:28.000Z","dependencies_parsed_at":"2023-07-21T04:43:16.433Z","dependency_job_id":"468d1f81-30ff-43f4-8738-365d474610f8","html_url":"https://github.com/wlandau/instantiate","commit_stats":null,"previous_names":["wlandau/instantiate"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wlandau%2Finstantiate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wlandau%2Finstantiate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wlandau%2Finstantiate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wlandau%2Finstantiate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wlandau","download_url":"https://codeload.github.com/wlandau/instantiate/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243817055,"owners_count":20352489,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bayesian-statistics","cmdstan","cmdstanr","markov-chain-monte-carlo","mc-stan","stan"],"created_at":"2024-10-10T18:24:58.775Z","updated_at":"2025-03-16T13:31:15.457Z","avatar_url":"https://github.com/wlandau.png","language":"R","funding_links":[],"categories":[],"sub_categories":[],"readme":"---\noutput: github_document\n---\n\n```{r, include = FALSE}\nknitr::opts_chunk$set(\n  eval = FALSE,\n  collapse = TRUE,\n  comment = \"#\u003e\",\n  fig.path = \"man/figures/README-\",\n  out.width = \"100%\"\n)\n```\n\n# instantiate: pre-compiled CmdStan models in R packages\n\n[![CRAN](https://www.r-pkg.org/badges/version/instantiate)](https://CRAN.R-project.org/package=instantiate)\n[![status](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)\n[![check-cmdstanr](https://github.com/wlandau/instantiate/workflows/check-cmdstanr/badge.svg)](https://github.com/wlandau/instantiate/actions?query=workflow%3Acheck-cmdstanr)\n[![check-cran](https://github.com/wlandau/instantiate/workflows/check-cran/badge.svg)](https://github.com/wlandau/instantiate/actions?query=workflow%3Acheck-cran)\n[![check-fixed](https://github.com/wlandau/instantiate/workflows/check-fixed/badge.svg)](https://github.com/wlandau/instantiate/actions?query=workflow%3Acheck-fixed)\n[![codecov](https://codecov.io/gh/wlandau/instantiate/branch/main/graph/badge.svg)](https://app.codecov.io/gh/wlandau/instantiate)\n[![lint](https://github.com/wlandau/instantiate/workflows/lint/badge.svg)](https://github.com/wlandau/instantiate/actions?query=workflow%3Alint)\n\nSimilar to [`rstantools`](https://mc-stan.org/rstantools/) for [`rstan`](https://mc-stan.org/rstan/), the `instantiate` package builds pre-compiled [`CmdStan`](https://mc-stan.org/users/interfaces/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`](https://mc-stan.org/cmdstanr/) without any additional compilation after package installation. This approach saves time and helps R package developers migrate from [`rstan`](https://mc-stan.org/rstan/) to the more modern [`CmdStanR`](https://mc-stan.org/cmdstanr/).\n\n# Documentation\n\nThe website at \u003chttps://wlandau.github.io/instantiate/\u003e includes a [function reference](https://wlandau.github.io/instantiate/reference/index.html) and other documentation.\n\n# Installing `instantiate`\n\nThe `instantiate` package depends on the R package [`CmdStanR`](https://mc-stan.org/cmdstanr/) and the command line tool [`CmdStan`](https://mc-stan.org/users/interfaces/cmdstan), so it is important to follow these stages in order:\n\n1. Install the R package [`CmdStanR`](https://mc-stan.org/cmdstanr/). [`CmdStanR`](https://mc-stan.org/cmdstanr/) is not on CRAN, so the recommended way to install it is `install.packages(\"cmdstanr\", repos = c(\"https://mc-stan.org/r-packages/\", getOption(\"repos\")))`.\n2. Optional: set environment variables `CMDSTAN_INSTALL` and/or `CMDSTAN` to manage the  [`CmdStan`](https://mc-stan.org/users/interfaces/cmdstan) installation. See the \"Administering CmdStan\" section below for details.\n3. Install `instantiate` using one of the R commands below.\n\nType | Source | Command\n---|---|---\nRelease | CRAN | `install.packages(\"instantiate\")`\nDevelopment | GitHub | `remotes::install_github(\"wlandau/instantiate\")`\nDevelopment | R-universe | `install.packages(\"instantiate\", repos = \"https://wlandau.r-universe.dev\")`\n\n# Installing packages that use `instantiate`\n\nPackages that use `instantiate` may be published on CRAN. CRAN does not have `CmdStan`, so the models are not pre-compiled in the Mac OS and Windows binaries. If you install from CRAN, please install from the source. For example:\n\n```{r, eval = FALSE}\ninstall.packages(\"hdbayes\", type = \"source\")\n```\n\n# Environment variables\n\nThe `instantiate` package uses environment variables to manage the installation of [`CmdStan`](https://mc-stan.org/users/interfaces/cmdstan). An environment variable is an operating system setting with a name and a value (both text strings). In R, there are two ways to set environment variables:\n\n1. `Sys.setenv()`, which sets environment variables temporarily for the current R session.\n2. The `.Renviron` text file in you home directory, which passes environment variables to all new R sessions. the [`edit_r_environ()`](https://usethis.r-lib.org/reference/edit.html) function from the [`usethis`](https://usethis.r-lib.org/) package helps.\n\n# Administering CmdStan\n\nBy default, `instantiate` looks for the copy of [`CmdStan`](https://mc-stan.org/users/interfaces/cmdstan) located at `cmdstanr::install_cmdstan()`. If you upgrade [`CmdStan`](https://mc-stan.org/users/interfaces/cmdstan), then the path returned by `cmdstanr::install_cmdstan()` will change, which may not be desirable in some cases. To permanently lock the path that `instantiate` uses, follow these steps:\n\n1. Set the `CMDSTAN` environment variable to the desired path to [`CmdStan`](https://mc-stan.org/users/interfaces/cmdstan).\n2. Set the `CMDSTAN_INSTALL` environment variable to `\"fixed\"`.\n3. Install `instantiate`.\n\nHenceforth, `instantiate` will automatically use the [`CmdStan`](https://mc-stan.org/users/interfaces/cmdstan) path from (1), regardless of the value of `CMDSTAN` after (3). To prefer `cmdstanr::cmdstan_path()` instead, you could do one of the following:\n\n* Reinstall `instantiate` with `CMDSTAN_INSTALL` not equal to `\"fixed\"`, or\n* Set `CMDSTAN_INSTALL` to `\"implicit\"` at runtime, or\n* Set the `cmdstan_install` argument to `\"implicit\"` for the current `instantiate` package function you are using.\n\n\n# Packaging Stan models\n\nThe following section explains how to create an R package with pre-compiled Stan models. This stage of the development workflow is considered \"runtime\" for the purposes of administering [`CmdStan`](https://mc-stan.org/users/interfaces/cmdstan) as described previously.\n\n## Structure\n\nBegin with an R package with one or more Stan model files inside the `src/stan/` directory. `stan_package_create()` is a convenient way to start.\n\n```r\nstan_package_create(path = \"package_folder\")\n#\u003e Example package named \"example\" created at \"package_folder\". Run stan_package_configure(path = \"package_folder\") so that the built-in Stan model will compile when the package installs.\n```\n\nAt minimum the package file structure should look something like this:\n\n```r\nfs::dir_tree(\"package_folder\")\n#\u003e package_folder\n#\u003e ├── DESCRIPTION\n#\u003e └── src\n#\u003e     └── stan\n#\u003e         └── bernoulli.stan\n```\n\n## Configuration\n\nConfigure the package so the Stan models compile during installation. `stan_package_configure()` writes required scripts `cleanup`, `cleanup.win`, `src/Makevars`, `src/Makevars.win`, and `src/install.libs.R`. Inside `src/install.libs.R` is a call to `instantiate::stan_package_compile()` which you can manually edit to control how your models are compiled. For example, different calls to `stan_package_compile()` can compile different groups of models using different C++ compiler flags.\n\n\n```r\nfs::dir_tree(\"package_folder\")\n#\u003e package_folder\n#\u003e ├── DESCRIPTION\n#\u003e ├── cleanup\n#\u003e ├── cleanup.win\n#\u003e └── src\n#\u003e     ├── Makevars\n#\u003e     ├── Makevars.win\n#\u003e     ├── install.libs.R\n#\u003e     └── stan\n#\u003e         └── bernoulli.stan\n```\n\n## Installation\n\nInstall the package just like you would any other R package. To install it from your local copy of `package_folder`, open R and run:\n\n```r\ninstall.packages(pkgs = \"package_folder\", type = \"source\", repos = NULL)\n```\n\n## Models\n\nA user can now run a model from the package without any additional compilation. See the documentation of [`CmdStanR`](https://mc-stan.org/cmdstanr/index.html) to learn how to use [`CmdStanR`](https://mc-stan.org/cmdstanr/index.html) model objects.\n\n```r\nlibrary(example)\nmodel \u003c- stan_package_model(name = \"bernoulli\", package = \"example\")\nprint(model) # CmdStanR model object\n#\u003e data {\n#\u003e   int\u003clower=0\u003e N;\n#\u003e   array[N] int\u003clower=0,upper=1\u003e y;\n#\u003e }\n#\u003e parameters {\n#\u003e   real\u003clower=0,upper=1\u003e theta;\n#\u003e }\n#\u003e model {\n#\u003e   theta ~ beta(1,1);  // uniform prior on interval 0,1\n#\u003e   y ~ bernoulli(theta);\n#\u003e }\nfit \u003c- model$sample(\n  data = list(N = 10, y = c(1, 0, 1, 0, 1, 0, 0, 0, 0, 0)),\n  refresh = 0,\n  iter_warmup = 2000,\n  iter_sampling = 4000\n)\n#\u003e Running MCMC with 4 sequential chains...\n#\u003e \n#\u003e Chain 1 finished in 0.0 seconds.\n#\u003e Chain 2 finished in 0.0 seconds.\n#\u003e Chain 3 finished in 0.0 seconds.\n#\u003e Chain 4 finished in 0.0 seconds.\n#\u003e \n#\u003e All 4 chains finished successfully.\n#\u003e Mean chain execution time: 0.0 seconds.\n#\u003e Total execution time: 0.6 seconds.\n\nfit$summary()\n#\u003e # A tibble: 2 × 10\n#\u003e   variable   mean median    sd   mad     q5    q95  rhat ess_bulk ess_tail\n#\u003e   \u003cchr\u003e     \u003cnum\u003e  \u003cnum\u003e \u003cnum\u003e \u003cnum\u003e  \u003cnum\u003e  \u003cnum\u003e \u003cnum\u003e    \u003cnum\u003e    \u003cnum\u003e\n#\u003e 1 lp__     -8.15  -7.87  0.725 0.317 -9.60  -7.64   1.00    7365.    8498.\n#\u003e 2 theta     0.333  0.324 0.130 0.134  0.137  0.563  1.00    6229.    7560.\n```\n\nYou can write an exported user-side function in your R package to access the model. For example, you might store this code in a `R/model.R` file in the package:\n\n```r\n#' @title Fit the Bernoulli model.\n#' @export\n#' @family models\n#' @description Fit the Bernoulli Stan model and return posterior summaries.\n#' @return A data frame of posterior summaries.\n#' @param y Numeric vector of Bernoulli observations (zeroes and ones).\n#' @param `...` Named arguments to the `sample()` method of CmdStan model\n#'   objects: \u003chttps://mc-stan.org/cmdstanr/reference/model-method-sample.html\u003e\n#' @examples\n#' if (instantiate::stan_cmdstan_exists()) {\n#'   run_bernoulli_model(y = c(1, 0, 1, 0, 1, 0, 0, 0, 0, 0))\n#' }\nrun_bernoulli_model \u003c- function(y, ...) {\n  stopifnot(is.numeric(y) \u0026\u0026 all(y \u003e= 0 \u0026 y \u003c= 1))\n  model \u003c- stan_package_model(name = \"bernoulli\", package = \"mypackage\")\n  fit \u003c- model$sample(data = list(N = length(y), y = y), ...)\n  fit$summary()\n}\n```\n\n## Development\n\n1. In your package `DESCRIPTION` file, list \u003chttps://mc-stan.org/r-packages/\u003e in the `Additional_repositories:` field ([example in `brms`](https://github.com/paul-buerkner/brms/blob/5c09251daabd5416e3d47004cc6c62816dc53cfa/DESCRIPTION#L95-L96)). This step is only necessary while [`cmdstanr`](https://mc-stan.org/cmdstanr/) is not yet on CRAN.\n\n```\nAdditional_repositories:\n    https://mc-stan.org/r-packages/\n```\n\n2. In your package `DESCRIPTION` and `NAMESPACE` files, import the `instantiate` package and function `stan_package_model()`.\n3. Write user-side statistical modeling functions which call the models in your package as mentioned above.\n4. [`CmdStan`](https://mc-stan.org/users/interfaces/cmdstan) is too big for [CRAN](https://cran.r-project.org), so `instantiate` will not be able to access it there. So if you plan to submit your package to CRAN, please skip the appropriate code in your examples, vignettes, and tests when `instantiate::stan_cmdstan_exists()` is `FALSE`. Explicit `if()` statements like the above one in the [`roxygen2`](https://roxygen2.r-lib.org/) `@examples` work for examples and vignettes. For tests, it is convenient to use [`testthat::skip_if_not()`](https://testthat.r-lib.org/reference/skip.html), e.g. `skip_if_not(stan_cmdstan_exists())`.\n5. [`pkgload::load_all()`](https://pkgload.r-lib.org/reference/load_all.html) might not compile your models. If you use [`pkgload`](https://pkgload.r-lib.org/) or [`devtools`](https://devtools.r-lib.org/) to load and develop your package, you may need to call `instantiate::stan_package_compile()` from the root directory of your package to compile your models manually.\n6. For [version control](https://git-scm.com/book/en/v2/Getting-Started-About-Version-Control), it is best practice to commit only source code files and documentation. Please do not commit any compiled executable Stan model files to your repository. If you do commit them, then other users with different machines will have trouble installing your package, and your commit history will consume too much storage. For [Git](https://git-scm.com), you may add the following lines to the [`.gitigore`](https://git-scm.com/docs/gitignore) file at the root of your package: \n\n```\nsrc/stan/**\n!src/stan/**/*.*\nsrc/stan/**/*.exe\nsrc/stan/**/*.EXE\n```\n\n7. For [continuous integration](https://devguide.ropensci.org/ci.html) (e.g. on [GitHub Actions](https://github.com/r-lib/actions)), please use [`cmdstanr`](https://mc-stan.org/cmdstanr/)-based installation as explained above, and tweak your workflow YAML files as explained in that section.\n8. For general information on R package development, please consult the free online book [R Packages (2e)](https://r-pkgs.org/) by [Hadley Wickham](https://github.com/hadley) and [Jennifer Bryan](https://github.com/jennybc), as well as the official manual on [Writing R Extensions](https://cran.r-project.org/doc/manuals/R-exts.html) by the R Core Team.\n\n# Code of Conduct\n\nPlease note that the `instantiate` project is released with a [Contributor Code of Conduct](https://github.com/wlandau/instantiate/blob/main/CODE_OF_CONDUCT.md). By contributing to this project, you agree to abide by its terms.\n\n# Citation\n\n```{r, eval = FALSE, warning = FALSE, comment = \"\"}\nTo cite package ‘instantiate’ in publications use:\n\n  Landau WM (2023). _instantiate: A Minimal CmdStan Client for R Packages_.\n  https://wlandau.github.io/instantiate/, https://github.com/wlandau/instantiate.\n\nA BibTeX entry for LaTeX users is\n\n  @Manual{,\n    title = {instantiate: A Minimal CmdStan Client for R Packages},\n    author = {William Michael Landau},\n    year = {2023},\n    note = {https://wlandau.github.io/instantiate/,\nhttps://github.com/wlandau/instantiate},\n  }\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwlandau%2Finstantiate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwlandau%2Finstantiate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwlandau%2Finstantiate/lists"}