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

[Christian Ruckert]

Am 22.09.2010 21:52, schrieb 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
>

Thank you very much for this detailed answer. I ended up with three 
packages in Depends, as you guessed I had to move some examples to the 
vignette.

Many thanks,
Christian