[R-pkg-devel] Examples that require Suggested packages

[James Pustejovsky]

Dear package developers,

I have a package (clubSandwich) that provides methods for a range of
different models implemented in other packages (nlme::lme, lme4::lmer,
metafor::rma.mv, etc.). These other packages are listed in SUGGESTS because
one need not have all of them in order to use the methods for any given
model. I'm working on re-writing examples for the function documentation
that a) run conditional on the presence of the suggested package and b) are
legible and aesthetically attractive to read.

The problem I'm encountering is examples that include more than one line
that prints to the console. If I follow the standard approach of wrapping
the entire example in a conditional that checks for the suggested package,
then only the last line prints to the console. For example:

library(clubSandwich)
if (requireNamespace("metafor", quietly = TRUE) &&
requireNamespace("metadat", quietly = TRUE)) {
library(metafor)
data(dat.assink2016, package = "metadat")
mfor_fit <- rma.uni(yi ~ year + deltype, vi = vi, data = dat.assink2016)
mfor_fit

mfor_CR2 <- vcovCR(mfor_fit, type = "CR2", cluster = dat.assink2016$study)
mfor_CR2
}

When run interactively, only mfor_CR2 is printed in the console.
Alternately, I could wrap each chunk of the code in a separate conditional,
as in:

pkgs_available <- requireNamespace("metafor", quietly = TRUE) &&
requireNamespace("metadat", quietly = TRUE)

if (pkgs_available) {
  library(metafor)
  data(dat.assink2016, package = "metadat")
  mfor_fit <- rma.uni(yi ~ year + deltype, vi = vi, data = dat.assink2016)
  mfor_fit
}

if (pkgs_available) {
  mfor_CR2 <- vcovCR(mfor_fit, type = "CR2", cluster = dat.assink2016$study)
  mfor_CR2
}

But this is awkward and distracts from the content of the example. A
further possibility is to wrap the entire example in withAutoprint(), as in:

if (requireNamespace("metafor", quietly = TRUE) &&
requireNamespace("metadat", quietly = TRUE)) withAutoprint({
library(metafor)
data(dat.assink2016, package = "metadat")
mfor_fit <- rma.uni(yi ~ year + deltype, vi = vi, data = dat.assink2016)
mfor_fit

mfor_CR2 <- vcovCR(mfor_fit, type = "CR2", cluster = dat.assink2016$study)
mfor_CR2
})

With this approach, we can see all of the output in the console, but the
code and output are not inter-woven as they would be if run outside of the
conditional. Instead, the entire example is printed in the console, then
each line of the example is re-printed with output inter-woven. I like this
solution better than the other approaches above, but it's still not great.

Does anyone have suggestions or pointers to examples of package
documentation that handles this issue in a more elegant way? Is there any
way to check whether suggested packages are loaded at the beginning of the
example script and stop execution of the remainder if they are not
available similar to testthat::skip_if_not_installed()?

James

	[[alternative HTML version deleted]]