Recommended way to call/import functions from a Suggested package

If in my package "Foo" I call a function from another package "Bar" if it's available, according to R-exts, this sounds like I should include "Suggests: Bar" in package Foo's description. But the manual is silent on how to treat Bar's namespace. Should I import it? If so, should this be conditional or unconditional? There is a thread from 2008 in which Duncan Murdoch suggests trying conditionally importing a package if it's installed, with the caveat "If this is allowed" (http://tolstoy.newcastle.edu.au/R/e5/devel/08/10/0488.html). This appears to work in current release of R, 2.15.2, but I'm still not clear if it's officially allowed, much less recommended.

The manual also says:

If a package only needs a few objects from another package it can use a fully qualified variable reference in the code instead of a formal import. A fully qualified reference to the function f in package foo is of the form foo::f. This is slightly less efficient than a formal import and also loses the advantage of recording all dependencies in the NAMESPACE file, so this approach is usually not recommended. Evaluating foo::f will cause package foo to be loaded, but not attached, if it was not loaded already?this can be an advantage in delaying the loading of a rarely used package.

Would this be a better solution than importing when calling into a suggested package?

Davor


        [[alternative HTML version deleted]]

Hi Davor,

To the best of my knowledge, there's only one way to use functions
from a suggested package: with require:

if (require("suggested_package")) {
 function_from_suggested_package()
} else {
 stop("suggested package not installed")
}

Unfortunately I don't think there's any way to use a suggested package
without polluting the search path.

On Feb 22, 2013, at 6:13 PM, Hadley Wickham wrote:

Hi Davor,

To the best of my knowledge, there's only one way to use functions
from a suggested package: with require:

if (require("suggested_package")) {
function_from_suggested_package()
} else {
stop("suggested package not installed")
}

Unfortunately I don't think there's any way to use a suggested package
without polluting the search path.

I've always wondered: How does lattice manage to use grid functions without putting them on the search path?

sessionInfo()

require(ggplot2)

sessionInfo()

?grid.text

?grid::grid.text

grid.text

grid::grid.text

Hi Davor,

To the best of my knowledge, there's only one way to use functions
from a suggested package: with require:

if (require("suggested_package")) {
 function_from_suggested_package()
} else {
 stop("suggested package not installed")
}

Unfortunately I don't think there's any way to use a suggested package
without polluting the search path.

Hadley

On Fri, Feb 22, 2013 at 6:26 PM, Davor Cubranic <cubranic at stat.ubc.ca> wrote:

If in my package "Foo" I call a function from another package "Bar" if it's available, according to R-exts, this sounds like I should include "Suggests: Bar" in package Foo's description. But the manual is silent on how to treat Bar's namespace. Should I import it? If so, should this be conditional or unconditional? There is a thread from 2008 in which Duncan Murdoch suggests trying conditionally importing a package if it's installed, with the caveat "If this is allowed" (http://tolstoy.newcastle.edu.au/R/e5/devel/08/10/0488.html). This appears to work in current release of R, 2.15.2, but I'm still not clear if it's officially allowed, much less recommended.

The manual also says:

If a package only needs a few objects from another package it can use a fully qualified variable reference in the code instead of a formal import. A fully qualified reference to the function f in package foo is of the form foo::f. This is slightly less efficient than a formal import and also loses the advantage of recording all dependencies in the NAMESPACE file, so this approach is usually not recommended. Evaluating foo::f will cause package foo to be loaded, but not attached, if it was not loaded already?this can be an advantage in delaying the loading of a rarely used package.

Would this be a better solution than importing when calling into a suggested package?

Davor


       [[alternative HTML version deleted]]

-- 
Chief Scientist, RStudio
http://had.co.nz/

On Feb 22, 2013, at 6:39 PM, David Winsemius wrote:

I've always wondered: How does lattice manage to use grid functions
without putting them on the search path?

Neither can the R interpreter find it. But it's clearly available if
you ask nicely:

grid::grid.text

To summarize, it appears that the only way to call functions from a
suggested package is by using either 'require' (which will dynamically
attach it) or the double colon method. Is this something that should be
mentioned in R-exts?

To summarize, it appears that the only way to call functions from a
suggested package is by using either 'require' (which will dynamically
attach it) or the double colon method. Is this something that should be
mentioned in R-exts?

Except the double colon method doesn't work (i.e. does not pass R CMD
check) unless you also import the package, which means it's no longer
just a suggestion - it must always be installed.

A simple test case (attached DESCRIPTION and R/test.r) yields this
warning on R CMD check:

* checking for unstated dependencies in R code ... WARNING
'::' or ':::' import not declared from: 'MASS'
See the information on DESCRIPTION files in the chapter 'Creating R
packages' of the 'Writing R Extensions' manual.

Hadley

loadNamespaces loads but does not attach the package. Suggests: is enough to
quieten the warning with

~/tmp$ R --version
R Under development (unstable) (2013-02-21 r62017) -- "Unsuffered
Consequences"

This is consistent with RShowDoc("R-exts") section 1.1.1

  Namespaces accessed by the ?::? and ?:::? operators must be listed here,
or in ?Suggests? or ?Enhances? (see below).

To summarize, it appears that the only way to call functions from a
suggested package is by using either 'require' (which will dynamically
attach it) or the double colon method. Is this something that should be
mentioned in R-exts?

Except the double colon method doesn't work (i.e. does not pass R CMD
check) unless you also import the package, which means it's no longer
just a suggestion - it must always be installed.

A simple test case (attached DESCRIPTION and R/test.r) yields this
warning on R CMD check:

* checking for unstated dependencies in R code ... WARNING
'::' or ':::' import not declared from: 'MASS'
See the information on DESCRIPTION files in the chapter 'Creating R
packages' of the 'Writing R Extensions' manual.

Hadley

-- 
Chief Scientist, RStudio
http://had.co.nz/
<test.r><DESCRIPTION>

I haven't gotten any complaints from "R CMD check" when I used Simon's
suggestion, even with "--as-cran" flag. Hadley's suggestion to use
'require' also works, and its side-effect of attaching the other
package can in some applications be seen by the end user as a nice
bonus, so I'll probably have to decide on a case-by-case basis which
method to use.

On the other hand, conditional import fails the check with "Namespace
dependency not required: 'foo'", if 'foo' is only listed in the
Suggests. Putting it in Imports gets rid of the warning, but then I
don't need to conditionally import it any more. :-)

To summarize, it appears that the only way to call functions from a
suggested package is by using either 'require' (which will dynamically
attach it) or the double colon method. Is this something that should
be mentioned in R-exts?

Davor


On 2013-02-22, at 8:40 PM, Hadley Wickham wrote:

On Friday, February 22, 2013, Simon Urbanek wrote:

On Feb 22, 2013, at 9:13 PM, Hadley Wickham wrote:

Hi Davor,

To the best of my knowledge, there's only one way to use functions
from a suggested package: with require:

if (require("suggested_package")) {
 function_from_suggested_package()
} else {
 stop("suggested package not installed")
}

Unfortunately I don't think there's any way to use a suggested package
without polluting the search path.

Why -- wouldn't

if (is.function(try(foo::bar, silent=TRUE))) {
  foo::bar(...)
}

do the job?


 I may be misremembering, but I think r cmd check complains about that.

Hadley


-- 
Chief Scientist, RStudio
http://had.co.nz/

	[[alternative HTML version deleted]]

loadNamespaces loads but does not attach the package. Suggests: is enough to
quieten the warning with

~/tmp$ R --version
R Under development (unstable) (2013-02-21 r62017) -- "Unsuffered
Consequences"

This is consistent with RShowDoc("R-exts") section 1.1.1

   Namespaces accessed by the ?::? and ?:::? operators must be listed here,
or in ?Suggests? or ?Enhances? (see below).

I guess that's changed since I last tried it.  (My reproducible
example forgot to include MASS in the Suggests :/ )

Thanks!

Hadley

Hi,

So MASS::huber(1:10) seems to do the job i.e. (1) loads the MASS
package (if it's installed), (2) does not pollute the search path,
(3) no 'R CMD check' warning if MASS is listed in Suggests,
and (4) descent error message if MASS is not installed:

 > MASS::huber(1:10)

 Error in loadNamespace(name) : there is no package called ?MASS?

So is this recommendable or are there good reasons for stating in
the manual that "this approach is usually not recommended"? (In which
case it would be good to know what the recommended way is.)

Thanks,
H.


On 02/25/2013 02:56 PM, Hadley Wickham wrote:

loadNamespaces loads but does not attach the package. Suggests: is enough to
quieten the warning with

~/tmp$ R --version
R Under development (unstable) (2013-02-21 r62017) -- "Unsuffered
Consequences"

This is consistent with RShowDoc("R-exts") section 1.1.1

  Namespaces accessed by the ?::? and ?:::? operators must be listed here,
or in ?Suggests? or ?Enhances? (see below).

I guess that's changed since I last tried it.  (My reproducible
example forgot to include MASS in the Suggests :/ )

Thanks!

Hadley

-- 
Herv? Pag?s

Program in Computational Biology
Division of Public Health Sciences
Fred Hutchinson Cancer Research Center
1100 Fairview Ave. N, M1-B514
P.O. Box 19024
Seattle, WA 98109-1024

E-mail: hpages at fhcrc.org
Phone:  (206) 667-5791
Fax:    (206) 667-1319

On Feb 26, 2013, at 5:47 PM, Herv? Pag?s wrote:

Hi,

So MASS::huber(1:10) seems to do the job i.e. (1) loads the MASS
package (if it's installed), (2) does not pollute the search path,
(3) no 'R CMD check' warning if MASS is listed in Suggests,
and (4) descent error message if MASS is not installed:

  > MASS::huber(1:10)

  Error in loadNamespace(name) : there is no package called ?MASS?

But (4) is a problem - it may not fail without MASS since it is only suggested, that's why you need the try() ...

The whole thread (which you omitted) was started because the usual if(require(...)) { .. } has an unwanted side-effect which the requestor did not want so the question was what does the job and that got settled before you joined in ...

Cheers,
S

So is this recommendable or are there good reasons for stating in
the manual that "this approach is usually not recommended"? (In which
case it would be good to know what the recommended way is.)

Thanks,
H.


On 02/25/2013 02:56 PM, Hadley Wickham wrote:

loadNamespaces loads but does not attach the package. Suggests: is enough to
quieten the warning with

~/tmp$ R --version
R Under development (unstable) (2013-02-21 r62017) -- "Unsuffered
Consequences"

This is consistent with RShowDoc("R-exts") section 1.1.1

   Namespaces accessed by the ?::? and ?:::? operators must be listed here,
or in ?Suggests? or ?Enhances? (see below).

I guess that's changed since I last tried it.  (My reproducible
example forgot to include MASS in the Suggests :/ )

Thanks!

Hadley

--
Herv? Pag?s

Program in Computational Biology
Division of Public Health Sciences
Fred Hutchinson Cancer Research Center
1100 Fairview Ave. N, M1-B514
P.O. Box 19024
Seattle, WA 98109-1024

E-mail: hpages at fhcrc.org
Phone:  (206) 667-5791
Fax:    (206) 667-1319

On 02/26/2013 03:12 PM, Simon Urbanek wrote:

On Feb 26, 2013, at 5:47 PM, Herv? Pag?s wrote:

Hi,

So MASS::huber(1:10) seems to do the job i.e. (1) loads the MASS
package (if it's installed), (2) does not pollute the search path,
(3) no 'R CMD check' warning if MASS is listed in Suggests,
and (4) descent error message if MASS is not installed:

 > MASS::huber(1:10)

 Error in loadNamespace(name) : there is no package called ?MASS?

But (4) is a problem - it may not fail without MASS since it is only suggested, that's why you need the try() ...

Not everybody needs the try(). Some functions in my package won't be
able to return anything if the suggested package is not installed, so they will have to fail, preferably loudly rather than silently. A pretty common situation.

Believe it or not, the discussion was not just about the recommended
way to call functions from the multicore package or another package
providing some kind of support for parallelization, where not having
it installed doesn't diminish the set of functionalities provided by
my package, only makes it slower.

The whole thread (which you omitted) was started because the usual if(require(...)) { .. } has an unwanted side-effect which the requestor did not want so the question was what does the job and that got settled before you joined in ...

I didn't omit the thread: I actually read every answer including yours.
Are you claiming your solution is the recommended one?

Thanks for
clarifying. Also as suggested by some posts in this thread, a
clarification in the official documentation would be nice.

Thanks,
H.

Cheers,
S

So is this recommendable or are there good reasons for stating in
the manual that "this approach is usually not recommended"? (In which
case it would be good to know what the recommended way is.)

Thanks,
H.


On 02/25/2013 02:56 PM, Hadley Wickham wrote:

loadNamespaces loads but does not attach the package. Suggests: is enough to
quieten the warning with

~/tmp$ R --version
R Under development (unstable) (2013-02-21 r62017) -- "Unsuffered
Consequences"

This is consistent with RShowDoc("R-exts") section 1.1.1

  Namespaces accessed by the ?::? and ?:::? operators must be listed here,
or in ?Suggests? or ?Enhances? (see below).

I guess that's changed since I last tried it.  (My reproducible
example forgot to include MASS in the Suggests :/ )

Thanks!

Hadley

--
Herv? Pag?s

Program in Computational Biology
Division of Public Health Sciences
Fred Hutchinson Cancer Research Center
1100 Fairview Ave. N, M1-B514
P.O. Box 19024
Seattle, WA 98109-1024

E-mail: hpages at fhcrc.org
Phone:  (206) 667-5791
Fax:    (206) 667-1319

-- 
Herv? Pag?s

Program in Computational Biology
Division of Public Health Sciences
Fred Hutchinson Cancer Research Center
1100 Fairview Ave. N, M1-B514
P.O. Box 19024
Seattle, WA 98109-1024

E-mail: hpages at fhcrc.org
Phone:  (206) 667-5791
Fax:    (206) 667-1319

On Feb 26, 2013, at 6:48 PM, Herv? Pag?s wrote:

On 02/26/2013 03:12 PM, Simon Urbanek wrote:

On Feb 26, 2013, at 5:47 PM, Herv? Pag?s wrote:

Hi,

So MASS::huber(1:10) seems to do the job i.e. (1) loads the MASS
package (if it's installed), (2) does not pollute the search path,
(3) no 'R CMD check' warning if MASS is listed in Suggests,
and (4) descent error message if MASS is not installed:

  > MASS::huber(1:10)

  Error in loadNamespace(name) : there is no package called ?MASS?

But (4) is a problem - it may not fail without MASS since it is only suggested, that's why you need the try() ...

Not everybody needs the try(). Some functions in my package won't be
able to return anything if the suggested package is not installed, so they will have to fail, preferably loudly rather than silently. A pretty common situation.

Hmm.. according to the docs that is not quite as intended: a package must work without "suggests" dependencies in the entirety. You can (conditionally) use suggested packages in datasets, examples or vignettes. Obviously, you could be tempted to hide this deficiency (functions failing without suggested packages) by not calling the functions that fail in your examples or tests, but I'd argue that is bypassing the design of "suggests".

Believe it or not, the discussion was not just about the recommended
way to call functions from the multicore package or another package
providing some kind of support for parallelization, where not having
it installed doesn't diminish the set of functionalities provided by
my package, only makes it slower.

I have no assumptions about what the author intended this functionality for, nor what you intend to use it for.

The whole thread (which you omitted) was started because the usual if(require(...)) { .. } has an unwanted side-effect which the requestor did not want so the question was what does the job and that got settled before you joined in ...

I didn't omit the thread: I actually read every answer including yours.
Are you claiming your solution is the recommended one?

No - but as far as I can see it is in the spirit of the documentation which explicitly mentions if(require(..)) and further down talks about :: and Suggests - so putting 1 + 1 (conditionality and ::) has led me to devise what I suggested.

Cheers,
Simon

Thanks for
clarifying. Also as suggested by some posts in this thread, a
clarification in the official documentation would be nice.

Thanks,
H.

Cheers,
S

So is this recommendable or are there good reasons for stating in
the manual that "this approach is usually not recommended"? (In which
case it would be good to know what the recommended way is.)

Thanks,
H.


On 02/25/2013 02:56 PM, Hadley Wickham wrote:

loadNamespaces loads but does not attach the package. Suggests: is enough to
quieten the warning with

~/tmp$ R --version
R Under development (unstable) (2013-02-21 r62017) -- "Unsuffered
Consequences"

This is consistent with RShowDoc("R-exts") section 1.1.1

   Namespaces accessed by the ?::? and ?:::? operators must be listed here,
or in ?Suggests? or ?Enhances? (see below).

I guess that's changed since I last tried it.  (My reproducible
example forgot to include MASS in the Suggests :/ )

Thanks!

Hadley

--
Herv? Pag?s

Program in Computational Biology
Division of Public Health Sciences
Fred Hutchinson Cancer Research Center
1100 Fairview Ave. N, M1-B514
P.O. Box 19024
Seattle, WA 98109-1024

E-mail: hpages at fhcrc.org
Phone:  (206) 667-5791
Fax:    (206) 667-1319

--
Herv? Pag?s

Program in Computational Biology
Division of Public Health Sciences
Fred Hutchinson Cancer Research Center
1100 Fairview Ave. N, M1-B514
P.O. Box 19024
Seattle, WA 98109-1024

E-mail: hpages at fhcrc.org
Phone:  (206) 667-5791
Fax:    (206) 667-1319

On 02/26/2013 05:28 PM, Simon Urbanek wrote:

On Feb 26, 2013, at 6:48 PM, Herv? Pag?s wrote:

On 02/26/2013 03:12 PM, Simon Urbanek wrote:

On Feb 26, 2013, at 5:47 PM, Herv? Pag?s wrote:

Hi,

So MASS::huber(1:10) seems to do the job i.e. (1) loads the MASS
package (if it's installed), (2) does not pollute the search path,
(3) no 'R CMD check' warning if MASS is listed in Suggests,
and (4) descent error message if MASS is not installed:

 > MASS::huber(1:10)

 Error in loadNamespace(name) : there is no package called ?MASS?

But (4) is a problem - it may not fail without MASS since it is only suggested, that's why you need the try() ...

Not everybody needs the try(). Some functions in my package won't be
able to return anything if the suggested package is not installed, so they will have to fail, preferably loudly rather than silently. A pretty common situation.

Hmm.. according to the docs that is not quite as intended: a package must work without "suggests" dependencies in the entirety. You can (conditionally) use suggested packages in datasets, examples or vignettes. Obviously, you could be tempted to hide this deficiency (functions failing without suggested packages) by not calling the functions that fail in your examples or tests, but I'd argue that is bypassing the design of "suggests".

Here is what the "Writing R Extensions" manual says:

 The ?Suggests? field uses the same syntax as ?Depends? and lists
 packages that are not necessarily needed. This includes packages
 used only in examples, tests or vignettes (see Writing package
 vignettes), and *packages loaded in the body of functions*.

Then some examples are provided and they mostly focus on suggested
packages used in examples, tests or vignettes. I couldn't find
anywhere that ``a package must work without "suggests" dependencies
in the entirety''.

AFAIK there are many valid situations where one wants to provide
some additional functionalities in his/her package via suggested
packages. A typical example being a front-end function that supports
different back-ends defined in different packages: the default
back-end will generally be in Depends or Imports, the alternative
back-ends in Suggests. If the user specifies a back-end (thru
some argument passed to the front-end) that is not installed,
then s/he'll get an error.

I don't need to hide this deficiency by not calling the functions
that fail in my examples (or tests). I'll just call my front-end
without specifying an alternative back-end.

Not a big deal if my
function generates a plot and if using the alternative back-end
would basically produce the same plot with only some small cosmetic
differences.

Cheers,
H.

Believe it or not, the discussion was not just about the recommended
way to call functions from the multicore package or another package
providing some kind of support for parallelization, where not having
it installed doesn't diminish the set of functionalities provided by
my package, only makes it slower.

I have no assumptions about what the author intended this functionality for, nor what you intend to use it for.

The whole thread (which you omitted) was started because the usual if(require(...)) { .. } has an unwanted side-effect which the requestor did not want so the question was what does the job and that got settled before you joined in ...

I didn't omit the thread: I actually read every answer including yours.
Are you claiming your solution is the recommended one?

No - but as far as I can see it is in the spirit of the documentation which explicitly mentions if(require(..)) and further down talks about :: and Suggests - so putting 1 + 1 (conditionality and ::) has led me to devise what I suggested.

Cheers,
Simon

Thanks for
clarifying. Also as suggested by some posts in this thread, a
clarification in the official documentation would be nice.

Thanks,
H.

Cheers,
S

So is this recommendable or are there good reasons for stating in
the manual that "this approach is usually not recommended"? (In which
case it would be good to know what the recommended way is.)

Thanks,
H.


On 02/25/2013 02:56 PM, Hadley Wickham wrote:

loadNamespaces loads but does not attach the package. Suggests: is enough to
quieten the warning with

~/tmp$ R --version
R Under development (unstable) (2013-02-21 r62017) -- "Unsuffered
Consequences"

This is consistent with RShowDoc("R-exts") section 1.1.1

  Namespaces accessed by the ?::? and ?:::? operators must be listed here,
or in ?Suggests? or ?Enhances? (see below).

I guess that's changed since I last tried it.  (My reproducible
example forgot to include MASS in the Suggests :/ )

Thanks!

Hadley

--
Herv? Pag?s

Program in Computational Biology
Division of Public Health Sciences
Fred Hutchinson Cancer Research Center
1100 Fairview Ave. N, M1-B514
P.O. Box 19024
Seattle, WA 98109-1024

E-mail: hpages at fhcrc.org
Phone:  (206) 667-5791
Fax:    (206) 667-1319

--
Herv? Pag?s

Program in Computational Biology
Division of Public Health Sciences
Fred Hutchinson Cancer Research Center
1100 Fairview Ave. N, M1-B514
P.O. Box 19024
Seattle, WA 98109-1024

E-mail: hpages at fhcrc.org
Phone:  (206) 667-5791
Fax:    (206) 667-1319

-- 
Herv? Pag?s

Program in Computational Biology
Division of Public Health Sciences
Fred Hutchinson Cancer Research Center
1100 Fairview Ave. N, M1-B514
P.O. Box 19024
Seattle, WA 98109-1024

E-mail: hpages at fhcrc.org
Phone:  (206) 667-5791
Fax:    (206) 667-1319