[R-pkg-devel] Examples with conditional blocks

[Lenth, Russell V]

Dear package developers,

What is the best way to provide examples in help pages that should only be run under certain conditions -- 
e.g., whether another package is installed? The code that is run conditionally is then an expression, so
only the results of the last statement are displayed; and even if we force-print results, the output is
separated from the code that produces it. 

The best I have been able to come up with is to use withAutoprint(), such as we see here:
---------------------------------------------------------------------------
> example(hpd.summary)

hpd.sm> if(require("coda")) withAutoprint({
hpd.sm+   # Create an emmGrid object from a system file
hpd.sm+   cbpp.rg <- do.call(emmobj, 
hpd.sm+       readRDS(system.file("extdata", "cbpplist", package = "emmeans")))
hpd.sm+   cbpp.emm <- emmeans(cbpp.rg, "period")
hpd.sm+   hpd.summary(cbpp.emm)   # or just summary(cbpp.emm) as it gets redirected
hpd.sm+   
hpd.sm+   # Test for any two-fold difference
hpd.sm+   summary(pairs(cbpp.emm), type = "response", delta = log(2))
hpd.sm+ }, spaced = TRUE)
Loading required package: coda

> cbpp.rg <- do.call(emmobj, readRDS(system.file("extdata", "cbpplist", package = "emmeans")))

> cbpp.emm <- emmeans(cbpp.rg, "period")

> hpd.summary(cbpp.emm)
 period emmean lower.HPD upper.HPD
 1       -1.43     -1.96    -0.894
 2       -2.39     -3.13    -1.823
 3       -2.52     -3.19    -1.862
 4       -2.97     -3.88    -1.998

Point estimate displayed: median 
Results are given on the logit (not the response) scale. 
HPD interval probability: 0.95 

> summary(pairs(cbpp.emm), type = "response", delta = log(2))
 contrast          odds.ratio lower.HPD upper.HPD p.equiv odds.eq
 period1 / period2       2.60     1.264      4.34   0.210  0.2658
 period1 / period3       2.90     1.266      5.42   0.114  0.1287
 period1 / period4       4.64     1.595      9.76   0.026  0.0267
 period2 / period3       1.14     0.486      2.36   0.918 11.1951
 period2 / period4       1.78     0.580      4.35   0.604  1.5253
 period3 / period4       1.55     0.437      4.01   0.700  2.3333

Point estimate displayed: median 
'p.equiv' and 'odds.eq' based on posterior P(|lin. pred.| < 0.6931) 
Results are back-transformed from the log odds ratio scale 
HPD interval probability: 0.95
---------------------------------------------------------------------------

This "works" in that we can see the code and the output, but it is unduly messy: The example code is displayed twice, the call to withAutoprint() adds clutter, comments are suppressed, and the part last part no longer has the example prompt string ("hpd.sm>" in this illustration).

Along these lines, I have a suggestion for enhancement of the example() function. That function allows for the example code to be marked-up with conditional blocks such as \dontrun{}. My suggestion is to provide an additional conditional markup option, perhaps \runif{expr}{...}, that runs the code in the second pair of braces exactly like any other example code when expr is true, and behaves like \dontrun{} otherwise.

Thanks

Russ Lenth
Univ of Iowa