[Bioc-devel] NAMESPACE, vignette and .Rd examples

[Martin Morgan]

On 09/22/2010 12:16 PM, Christian Ruckert wrote:
> In an old posting on this list
> https://stat.ethz.ch/pipermail/r-devel/2008-December/051602.html it is
> stated, that for vignettes and the NAMESPACE file the following holds:
> 
> Packages used in the vignette must be loaded with library():
> - If the package is already listed as Imports or Depends, it will load
> without problems
> - Otherwise the package should be listed in Suggests, but the vignette
> may not run, as installation of the package is not ensured
> 
> 
> Does this also hold for examples in the help-files (.Rd)?
> 
> The bioconductor package guidelines say:
> "Depends: is also appropriate when a package is used in the example
> section of a man page. It is very unusual for a package to list more
> than three packages as 'Depends:'."
> 

Hi Christian --

It's probably useful to divide the answer into different parts.

First, in terms of the code you write in your package, it is much better
to use Imports: and NAMESPACE to ensure that you get exactly the objects
you expect, regardless of what the user adds to their search path. This
is the primary driver behind the "It is very unusual for a package to
list more than three packages as 'Depends:" statement -- the only
packages relevant to the evaluation of your code that belong in the
Depends: fields are those that can't (e.g., because they don't have a
NAMESPACE) be Import'ed.

Second, it's useful to think of the role of an example versus a vignette
versus a test. Examples are meant to illustrate how the function works.
They should be straight-forward and readily evaluated (e.g., calling
example(foo) returns within seconds). It will often be convenient to
'curate' a few key examples that are small but illustrative, and have
these as data objects in the package. In contrast the vignette can
definitely be more comprehensive, and might rely on several additional
packages with 'real' computations involved (while still conforming to
the Bioc guidelines for overall build time). Perhaps your package is
using 'examples' for what might better be placed in a vignette?

Tests are really another beast entirely, and don't belong in either the
examples or vignette -- they should be simple, typically using
artificial data constructed to test the code that you write; there
paradigm we've adopted can be seen in a package like GenomicRanges,
where the basic structure is created by the
codetoolsBioC::writeRUnitRUnner (codetoolsBioC is available via svn
only, see http://bioconductor.org/developers/source-control/). Test code
seldom has explicit package dependencies -- you're testing your own
code, not that produced by others.

> For my package I will have definitely far more than three packages in
> the depends list. If doing so can I omit the call to library() in the
> example section? Is it ok to list the same packages in Imports as well
> as in Depends?

Useful to remember that Depend:'ing on a package implies that its
dependencies and imports are also available and attached / loaded as
prescribed by the corresponding packages.

A package might end up on the Depends: and Imports: fields if on the one
hand your code uses functions from the package, and on the other hand
not having a package available to the user would make your package not
very useful, e.g., if your functions always return GRanges objects from
GenomicRanges, then you'd really like to Import: GenomicRanges for your
internal code, and set the user's environment up for success
manipulating the objects you return with Depends: GenomicRanges. This is
actually not a very common occurrence in practice.

If the package appears in Depends: then you won't need library() in the
examples.

This is just general advice; why will your package have 'far more than
three packages' in the Depends: list?

Martin

> 
> Best,
> Christian
> 
> _______________________________________________
> Bioc-devel at stat.math.ethz.ch mailing list
> https://stat.ethz.ch/mailman/listinfo/bioc-devel