https://github.com/ropensci/jagstargets
Reproducible Bayesian data analysis pipelines with targets and JAGS
https://github.com/ropensci/jagstargets
bayesian high-performance-computing jags make r r-targetopia reproducibility rjags rstats rstats-package statistics targets
Last synced: 4 months ago
JSON representation
Reproducible Bayesian data analysis pipelines with targets and JAGS
- Host: GitHub
- URL: https://github.com/ropensci/jagstargets
- Owner: ropensci
- License: other
- Created: 2020-12-13T13:52:27.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2024-12-03T12:25:13.000Z (over 1 year ago)
- Last Synced: 2026-01-22T06:04:15.115Z (5 months ago)
- Topics: bayesian, high-performance-computing, jags, make, r, r-targetopia, reproducibility, rjags, rstats, rstats-package, statistics, targets
- Language: R
- Homepage: https://docs.ropensci.org/jagstargets
- Size: 613 KB
- Stars: 11
- Watchers: 2
- Forks: 7
- Open Issues: 0
-
Metadata Files:
- Readme: README.Rmd
- Changelog: NEWS.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codemeta: codemeta.json
- Zenodo: .zenodo.json
Awesome Lists containing this project
README
---
output: github_document
---
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# jagstargets 
[](https://joss.theoj.org/papers/10.21105/joss.03877)
[](https://github.com/ropensci/software-review/issues/425)
[](https://zenodo.org/badge/latestdoi/321076424)
[](https://wlandau.github.io/targetopia/)
[](https://cran.r-project.org/package=jagstargets)
[](https://www.repostatus.org/#active)
[](https://github.com/ropensci/jagstargets/actions?query=workflow%3Acheck)
[](https://app.codecov.io/gh/ropensci/gittargets)
[](https://github.com/ropensci/jagstargets/actions?query=workflow%3Alint)
Bayesian data analysis usually incurs long runtimes and cumbersome custom code, and the process of prototyping and deploying custom [JAGS](https://mcmc-jags.sourceforge.io) models can become a daunting software engineering challenge. To ease this burden, the `jagstargets` R package creates [JAGS](https://mcmc-jags.sourceforge.io) pipelines that are concise, efficient, scalable, and tailored to the needs of Bayesian statisticians. Leveraging [`targets`](https://docs.ropensci.org/targets/), `jagstargets` pipelines automatically parallelize the computation and skip expensive steps when the results are already up to date. Minimal custom user-side code is required, and there is no need to manually configure branching, so `jagstargets` is easier to use than [`targets`](https://docs.ropensci.org/targets/) and [`R2jags`](https://CRAN.R-project.org/package=R2jags) directly.
## Prerequisites
1. The [prerequisites of the `targets` R package](https://docs.ropensci.org/targets/#prerequisites).
1. Basic familiarity with [`targets`](https://docs.ropensci.org/targets/): watch minutes 7 through 40 of [this video](https://youtu.be/Gqn7Xn4d5NI?t=439), then read [this chapter](https://books.ropensci.org/targets/walkthrough.html) of the [user manual](https://books.ropensci.org/targets/).
1. Familiarity with Bayesian Statistics and [JAGS](https://mcmc-jags.sourceforge.io/). Prior knowledge of [`rjags`](https://cran.r-project.org/package=rjags) or [`R2jags`](https://cran.r-project.org/package=R2jags) helps.
## How to get started
Read the `jagstargets` [introductory vignette](https://docs.ropensci.org/jagstargets/articles/introduction.html), and then use as a reference while constructing your own workflows. If you need to analyze large collections of simulated datasets, please consult the [simulation vignette](https://docs.ropensci.org/jagstargets/articles/simulation.html).
## Installation
`jagstargets` requires the user to install [JAGS](https://mcmc-jags.sourceforge.io/), [`rjags`](https://CRAN.R-project.org/package=rjags), and [`R2jags`](https://CRAN.R-project.org/package=R2jags) beforehand. You can install JAGS from , and you can install the rest from CRAN.
```{r, eval = FALSE}
install.packages(c("rjags", "R2jags"))
```
Then, install the latest release from CRAN.
```{r, eval = FALSE}
install.packages("jagstargets")
```
Alternatively, install the GitHub development version to access the latest features and patches.
```{r, eval = FALSE}
install.packages("remotes")
remotes::install_github("ropensci/jagstargets")
```
## Usage
Begin with one or more models: for example, the simple regression model below with response variable $y$ and covariate $x$.
Next, write a JAGS model file for each model like the `model.jags` file below.
```jags
model {
for (i in 1:n) {
y[i] ~ dnorm(x[i] * beta, 1)
}
beta ~ dnorm(0, 1)
}
```
To begin a reproducible analysis pipeline with this model, write a [`_targets.R` file](https://books.ropensci.org/targets/walkthrough.html) that loads your packages, defines a function to generate JAGS data, and lists a pipeline of targets. The target list can call target factories like [`tar_jags()`](https://docs.ropensci.org/jagstargets/reference/tar_jags.html) as well as ordinary targets with [`tar_target()`](https://docs.ropensci.org/targets/reference/tar_target.html). The following minimal example is simple enough to contain entirely within the `_targets.R` file, but for larger projects, you may wish to store functions in separate files as in the [`targets-stan`](https://github.com/wlandau/targets-stan) example.
```{r, eval = FALSE}
# _targets.R
library(targets)
library(jagstargets)
generate_data <- function() {
true_beta <- stats::rnorm(n = 1, mean = 0, sd = 1)
x <- seq(from = -1, to = 1, length.out = n)
y <- stats::rnorm(n, x * true_beta, 1)
out <- list(n = n, x = x, y = y, true_beta = true_beta)
}
list(
tar_jags(
example,
jags_files = "model.jags", # You provide this file.
parameters.to.save = "beta",
data = generate_data()
)
)
```
Run [`tar_visnetwork()`](https://docs.ropensci.org/targets/reference/tar_visnetwork.html) to check `_targets.R` for correctness, then call [`tar_make()`](https://docs.ropensci.org/targets/reference/tar_make.html) to run the pipeline. Access the results using [`tar_read()`](https://docs.ropensci.org/targets/reference/tar_read.html), e.g. `tar_read(tar_read(example_summary_x)`. Visit the [introductory vignette](https://docs.ropensci.org/jagstargets/articles/introduction.html) to read more about this example.
## How the package works
`jagstargets` supports specialized [target factories](https://ropensci.org/blog/2021/02/03/targets/#target-factories) that create ensembles of [target objects](https://docs.ropensci.org/targets/reference/tar_target.html) for [`R2jags`](https://CRAN.R-project.org/package=R2jags) workflows. These [target factories](https://ropensci.org/blog/2021/02/03/targets/#target-factories) abstract away the details of [`targets`](https://docs.ropensci.org/targets/) and [`R2jags`](https://CRAN.R-project.org/package=R2jags) and make both packages easier to use. For details, please read the [introductory vignette](https://docs.ropensci.org/jagstargets/articles/introduction.html).
## Help
Please read the `targets` help guide at to learn how to ask for help.
If you have trouble using `jagstargets`, you can ask for help in the [GitHub discussions forum](https://github.com/ropensci/jagstargets/discussions/categories/help). Because the purpose of `jagstargets` is to combine [`targets`](https://docs.ropensci.org/targets/) and [`R2jags`](https://CRAN.R-project.org/package=R2jags), your issue may have something to do with one of the latter two packages, a [dependency of `targets`](https://github.com/ropensci/targets/blob/4e3ef2a6c986f558a25e544416f480fc01236b6b/DESCRIPTION#L49-L88), or [`R2jags`](https://CRAN.R-project.org/package=R2jags) itself. When you troubleshoot, peel back as many layers as possible to isolate the problem. For example, if the issue comes from [`R2jags`](https://CRAN.R-project.org/package=R2jags), create a [reproducible example](https://reprex.tidyverse.org) that directly invokes [`R2jags`](https://CRAN.R-project.org/package=R2jags) without invoking `jagstargets`. The GitHub discussion and issue forums of those packages are great resources.
## Participation
Development is a community effort, and we welcome discussion and contribution. By participating in this project, you agree to abide by the [code of conduct](https://ropensci.org/code-of-conduct/) and the [contributing guide](https://github.com/ropensci/jagstargets/blob/main/CONTRIBUTING.md).
## Citation
```{r, warning = FALSE}
citation("jagstargets")
```