Roxygen documentation for stan model(s) in R

Developers
1

I’ve been googling a bit and searching here, but I’ve been unable to find anything on documenting stan models in an R package. I am currently developing an R package that has several RStan models and I would like to have a roxygen documentation briefly describing each model. That is, I would like my users to be able to do ?stan_model and get brief documentation regarding the model. Nothing fancy since they just pick which model they want to run and do not need to do anything in terms of inputs, but I would like a paragraph or two describing each model and how it is different from the others.
So my question: what is the best way (if possible) to add roxygen documentation to a stan model in an R package? Or, what are different ways to add documentation and if possible a brief pros/cons of each.
Thanks in advance.

2

Sorry this didn’t get answered. I don’t know the answer, but @bgoodri or @Jonah should be able to answer.

3

No, problem! Thank you for bumping and tagging!

4

You can’t add roxygen documentation for the Stan model itself in R but you can add it for a wrapper function that you use to expose the model to the user. For example, here’s the documentation for rstanarm’s stan_glm function, which internally runs a Stan program:

Basically you document the R function and then call the Stan program internally from the R function. Hope that helps!

5

Yeah, at least I know my options. So it is probably better to have a model = string than model = package:::stanmodels$model argument and add a case_when or if term to set the model based on the string, and then annotate the different models in the main/exposed function. Was hoping to have separate documentation for different models to reduce the size of the exposed function’s documentation (and focus solely on how to run the exposed function in its documentation). Oh well. Still, thank you for the input.

6

Actually, now that I think about it, you can add freestanding doc pages not associated with any function (to document the models) and then link to them from the exposed function doc. For example, something like this should work:

#' Doc for Stan model 1
#' ... // however many lines of doc
#' ...
#' @name stan-model-1
NULL

#' Doc for exposed function
#' ...  // other lines of doc
#' See [stan-model-1] for details.

The [stan-model-1] part should link to the doc page for that (because of @name stan-model-1 in that doc), assuming you have Roxygen: list(markdown = TRUE) somewhere in your DESCRIPTION file.

7

Yeah I was thinking of something similar. I was also thinking if I could add something like the following in a zzz.R file stan_mode ← stanmodels$stan_model and then annotate the variable stan_model (possibly attaching it to the package environment) similar to a dataset. But I haven’t had time to play with the kinks of it yet. I think the easiest is your idea for my first release and maybe try to work out something else later. Thanks again!

1 Like
8

Just wanted to add here (in case others want to add doc and an exported variable for a stan model) that, adding the following snippet to a zzz.R file will export/expose stan models so that one can do pkg::some_stan_model:

.onLoad <- function(libname, pkgname) {
lapply(seq_along(stanmodels), 
    \(x) assign(names(stanmodels)[x], stanmodels[[x]],
    envir = asNamespace('pkg'))
)
}

Then following @jonah’s suggestion of having empty documentation appears to work nicely and one can do ?pkg::some_stan_model or some_stan_model if pkg is loaded.

1 Like