[R-pkg-devel] Conditional use of suggested package in example code

On 30 May 2018, at 12:03, Martin Maechler <maechler at stat.math.ethz.ch> wrote:

Christian Sigg 
   on Wed, 30 May 2018 11:08:38 +0200 writes:

I am updating the ?nsprcomp? package to follow the recommendations of Section 1.1.3.1 of the Writing R Extensions manual.
Before the update, the example code for the `nsprcomp` function looked like this:

library(MASS)
set.seed(1)

# Regular PCA, with the tolerance set to return five PCs
prcomp(Boston, tol = 0.36, scale. = TRUE)

# Sparse PCA with different cardinalities per component. The number of components
# is derived from the length of vector k.
nsprcomp(Boston, k = c(13, 7, 5, 5, 5), scale. = TRUE)  

(?)

First, a only a "stylistic" remark to you (and many others):
If you only need a dataset from a package, you typically should not attach the
package [to the search() path] via library()/require(), but typically use

  data(Boston, package="MASS")

which only loads MASS' namespace *and* is self-describing that
indeed you only use MASS for getting that data set.

... but see below for your real question

The unconditional use of the suggested package ?MASS? produces an error on systems where ?MASS? is not installed. 

I personally think that this is fine in an interactive session. The error makes it obvious what the user has to do to run the example - install the missing package. But I understand that it would increase the complexity of automated checking of examples, where one would have to distinguish between this kind of error and an actual bug in the example code.

In any case, the WRE manual recommends conditional use of suggested packages via `requireNamespace`. A straightforward way to follow the recommendation is to wrap the whole example in a conditional statement:

if (requireNamespace("MASS", quietly = TRUE)) {
set.seed(1)

# Regular PCA, with the tolerance set to return five PCs
prcomp(MASS::Boston, tol = 0.36, scale. = TRUE)

# Sparse PCA with different cardinalities per component. The number of components
# is derived from the length of vector k.
nsprcomp(MASS::Boston, k = c(13, 7, 5, 5, 5), scale. = TRUE)  

(?)
}

I don?t like this for two reasons:

1. The if statement and the indentation add clutter to the example code, making the help page harder to read.

2. The if statement breaks the output of `example(?nsprcomp?, ?nsprcomp?)`. Now only the statement before the closing curly brace has its output printed to the console. I would have to add explicit print statements that further clutter up the example.

Is there a coding pattern that satisfies the WRE recommendations, but avoids these two problems?

A very good question:

I have introduced the function   withAutoprint( . )  into R 3.4.0  
to address your '2.'  -- not perfectly but at least
transparently,
so the if would going to be

 if (requireNamespace("MASS", quietly = TRUE)) withAutoprint({


 })

{and you'd have to add  'Depends: R (>= 3.4.0)?}

To address '1.'  you could wrap  \dontshow{ * } around the two
if()-related lines in your example code which makes the code
*look* better to the help page readers. 

\examples{
  \dontshow{
    if (TRUE) {
  }
  test(1)
  \dontshow{
    }
  }
}

\examples{
  \dontshow{
    if (TRUE) 
  }
  {
    test(1)
  }
}

These two "techniques" together get you quite far, though I
agree it's a bit of fiddling..

Last but not least - of course you know that, I'm just stating
the obvious here:  The small 'datasets' that comes with R
does not need any conditionals (nor does simple random-generated
data that you could use).

Some people have assumed that a ?recommended? package in ?Suggests? can safely be used unconditionally, but this is not so. (R can be installed without recommended packages, and which packages are ?recommended? may change.) 

Best,
Martin

Regards
Christian

?
Christian Sigg
https://sigg-iten.ch/research