[R-pkg-devel] Examples with conditional blocks

[Duncan Murdoch]

On 01/09/2022 5:53 p.m., Lenth, Russell V wrote:
> 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:

I don't think I've seen much better.

> ---------------------------------------------------------------------------
>> 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.
> 

I think that would be a good idea, but it doesn't look easy.

Duncan Murdoch