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

[Duncan Murdoch]

On 11/06/2022 11:10 a.m., James Pustejovsky wrote:
> 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()?

You can call print() explicitly rather than relying on auto-printing, 
but I don't think there's a way to do this elegantly.  I posted a 
suggestion to add something to Bugzilla recently (see 
https://bugs.r-project.org/show_bug.cgi?id=18352), and haven't had any 
response to it.  (It is certainly not the first time this issue has been 
raised, but I couldn't spot a previous bug/enhancement request about it.)

Duncan Murdoch