---
title: "stanflow: quick tour"
vignette: >
  %\VignetteIndexEntry{tour}
  %\VignetteEngine{quarto::html}
  %\VignetteEncoding{UTF-8}
knitr:
  opts_chunk:
    collapse: true
    comment: '#>'
---

```{r}
#| include: false
options(
  repos = c(
    P3M = "https://packagemanager.posit.co/cran/latest",
    CRAN = "https://cloud.r-project.org"
  )
)
```

`stanflow` is a lightweight metapackage that sets up a Stan-based Bayesian workflow. It attaches a core toolkit for model analysis (`posterior`, `loo`, `projpred`, `bayesplot`, `shinystan`) and helps you install/configure Stan interfaces (`cmdstanr`, `rstan`, `brms`, `rstanarm`).

## Attach `stanflow`

```{r}
library(stanflow)
stan_logo()
```

Startup messages list attached packages and any namespace clashes. You can re-print that status later with `flow_check()`, or just the namespace conflicts with `stanflow_conflicts()`.

```{r}
flow_check()
stanflow_conflicts()
```

## Keep the flow fresh

Check whether your Stan workflow packages are up to date (stable releases by default, or dev builds with `dev = TRUE`). Set `recursive` to check the full dependency closure.

```{r}
#| eval: false
stanflow_update(recursive = TRUE)
```

You can also check if stanflow's direct dependencies are up to date using `flow_check()`.

```{r}
#| eval: false
flow_check(check_updates = TRUE)
```

## Choose interface backends

Use `setup_interface()` to install (if needed), attach, and configure interfaces. This example prefers the `cmdstanr` backend for `brms`. Running this command will attach both packages and ensure that `brms` calls rely on `cmdstanr` by default.

```{r}
setup_interface(
  interface = "brms",
  brms_backend = "cmdstanr",
  cores = 2,
  quiet = TRUE, # only silences R output
  force = TRUE # only required for non-interactive usage
)
flow_check()
```

If you prefer `RStan`, you could load it alongside `brms`.

```{r}
#| eval: false
setup_interface(
  interface = c("rstan", "brms"),
  cores = 2,
  quiet = TRUE
)
```

You can setup as many interfaces you'd like:

```{r}
#| eval: false
setup_interface(
  interface = c("rstan", "rstanarm", "brms", "cmdstanr"),
  brms_backend = "cmdstanr",
  cores = 2,
  quiet = TRUE
)
```

## A tiny workflow

With the core packages attached, you can generate, summarise, and visualise draws immediately.

```{r}
set.seed(0)
draws <- as_draws_df(
  matrix(rnorm(4000), ncol = 1, dimnames = list(NULL, "theta"))
)
summarise_draws(draws, mean, sd, rhat, ess_bulk)
mcmc_hist(draws, pars = "theta")
log_lik <- matrix(rnorm(4000 * 10, -1, 0.2), ncol = 10)
loo(log_lik)
```

## Painless citations

Once you've finished your analysis and need to cite the Stan software you used, simply run `stan_cite()` on your project/files to quickly generate an appropriate BibTeX or bibentry.

```{r}
start <- Sys.time()
citations <- stan_cite("stanflow.qmd")
Sys.time() - start
citations
```