[Rd] NAMESPACE/DESCRIPTION and imports

[Martin Morgan]

Hi Jim --

"James MacDonald" <jmacdon at med.umich.edu> writes:

> Hi,
>
> Could someone point me to the relevant documentation that covers
> what should be in the DESCRIPTION file for packages that have
> functions imported via the NAMESPACE file? I have read the R
> Extensions manual, but I cannot find where it covers the DESCRIPTION
> file vis a vis importing from a namespace.
>
> An example:
>
> I have a package foo that uses two functions x and y from package
> bar. Both packages have namespaces, and I just want to import the
> functions from bar rather than attaching the package.
>
> I put 
>
> Imports: bar
>
> in my DESCRIPTION file and
>
> importFrom(bar, x, y)
>
> in my NAMESPACE file.
>

> I have a vignette that uses both x and y from bar, and when I run R
> CMD build foo, at the vignette building step it errors out because
> it cannot find function x. If I add
>
> Depends: bar
>
> to my DESCRIPTION file it all works, but bar is attached and it
> seems I have not accomplished what I wanted. I am obviously
> misunderstanding something but I don't know what.

If I'm reading correctly, you have a vignette chunk that does

<<>>=
x()
@

This corresponds to use of x _outside_ your package name space -- the
vignette is being processed like any R session.

You already have Imports: foo in your DESCRIPTION file (because you're
using x _within_ your package name space), so you know the user will
have foo installed. The vignette just needs to

library(foo)

before calling x -- i.e., attach foo to the search path, so that x can
be found in a normal R session.

A slightly different scenario is when your vignette uses a package
that it is not meaningful to Import: or Depend: on, in which case
you'll want to mention the package in the Suggests: field of
DESCRIPTION. In this case I think you also want to add a line

%\VignetteDepends{foo}

to the vignette. Suggests: is a little problematic because the default
for install.packages does NOT install packages mentioned in Suggests:
so users may be unable to build your vignette without first installing
additional packages.

Back to the case where the package Imports: foo. This is still
helpful, as it keeps from cluttering the user search path and allows
you to be confident that references to x within your package find the
appropriate x, regardless of what the user is doing to their search
path.

Hope that helps.

Martin

> Best,
>
> Jim
>
>
>
> James W. MacDonald, M.S.
> Biostatistician
> Hildebrandt Lab
> 8220D MSRB III
> 1150 W. Medical Center Drive
> Ann Arbor MI 48109-0646
> 734-936-8662
> **********************************************************
> Electronic Mail is not secure, may not be read every day, and should not be used for urgent or sensitive issues
>
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel

-- 
Martin Morgan
Computational Biology / Fred Hutchinson Cancer Research Center
1100 Fairview Ave. N.
PO Box 19024 Seattle, WA 98109

Location: Arnold Building M2 B169
Phone: (206) 667-2793