Hi Martin
Thank you for your reply.
> On 30 May 2018, at 12:03, Martin Maechler <maech...@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.
I agree with you. In my specific example, I later also use MASS::ginv(), but
unfortunately that was not visible in the excerpt.
> ... 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)’}
Thank you for that!
>
> 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.
But how do I only hide the if statement and its closing curly brace? The
following doesn’t work:
> \examples{
> \dontshow{
> if (TRUE) {
> }
> test(1)
> \dontshow{
> }
> }
> }
The example section on the help page is empty, because the curly braces of the
if statement and the \dontshow get mixed up.
Ordering the statements this way:
> \examples{
> \dontshow{
> if (TRUE)
> }
> {
> test(1)
> }
> }
is better, but the opening and closing curly brace of the if statement remain
on the help page.
Furthermore, I keep the examples in standalone files that I include in the
documentation using roxygen2’s @example. Adding the \dontshow markup means I
can’t source them anymore.
>
> 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).
Quoting from the WRE manual:
> 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.)
So according to the manual, even MASS needs a conditional.
I do use random data in my tests, but I think that the examples profit from
using a real dataset.
Regards
Christian
>
> Best,
> Martin
>
>
>> Regards
>> Christian
>
>> —
>> Christian Sigg
>> https://sigg-iten.ch/research
>
>> ______________________________________________
>> R-package-devel@r-project.org mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-package-devel
______________________________________________
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
