Getting started with flexstanr

flexstanr gives a Stan-based R package one interface for fitting its models through either rstan or (optionally) cmdstanr. Your package supplies its own compiled models; flexstanr resolves them at run time, so the same fitting code works whichever backend is installed.

Wiring it into your package

From the root of your Stan package, run the setup helper once:

flexstanr::use_flexstanr()

This adds flexstanr (and rstan, the default backend) to your Imports and, while flexstanr is still pre-CRAN, an interim Remotes: ACCIDDA/flexstanr entry so remotes / pak can install it from GitHub. Once flexstanr is on CRAN, pass on_cran = TRUE to skip the Remotes entry.

Building sampler options

stan_options() collects and validates sampler arguments for the chosen backend, forwarding them verbatim so a call feels native to that backend:

opts <- stan_options(chains = 2, iter = 500, seed = 1)
str(opts)
#> List of 4
#>  $ iter   : int 500
#>  $ seed   : int 1
#>  $ chains : int 2
#>  $ backend: chr "rstan"

Each backend has its own argument vocabulary, and mixing them is caught early with a “did you mean” hint rather than failing deep inside the sampler:

# `parallel_chains` is a cmdstanr word; the rstan backend rejects it.
try(stan_options(backend = "rstan", parallel_chains = 4))
#> Error : These stan_options() arguments are not valid for the 'rstan' backend:
#>   - `parallel_chains`: use `cores`

Fitting a model

fit_model() dispatches to the backend recorded on the options and resolves the compiled model by name from your package. A host fitting one of its own models needs no extra arguments; the calling package is detected automatically.

# `"coverage"` is resolved from your package's stanmodels (rstan) or
# inst/stan/coverage.stan (cmdstanr).
fit <- fit_model(
  "coverage",
  dat_stan  = data_list,
  init      = init_list,
  stan_opts = opts
)

Reading a fit

The backend_* accessors read a fitted object without your code needing to know which backend produced it:

# posterior draws as an iterations x chains x parameters array
draws <- backend_draws_array(fit)

# named parameters, matching rstan::extract()'s shape
post <- backend_extract(fit, pars = c("beta", "sigma"))

# guard against the degenerate "no draws" case before using a fit
stopifnot(backend_has_draws(fit))

Unrecognized objects pass through backend_has_draws() as if they carry draws, so test doubles are left untouched:

backend_has_draws(list())
#> [1] TRUE

Choosing cmdstanr

Pass backend = "cmdstanr" to stan_options(). cmdstanr is optional and not on CRAN, so install it separately (see the cmdstanr getting-started guide); selecting it without the package installed errors early with an actionable message.

opts <- stan_options(backend = "cmdstanr", parallel_chains = 4, iter_warmup = 500)