[Bioc-devel] NAMESPACE questions

[Seth Falcon]

Hi Diego,

I'm cc'ing bioc-devel because I think others may find interest in
answers to your questions.  The good stuff is at the bottom.


On 18 Nov 2005, ddiez at iib.uam.es wrote:
> Hi Seth,
>
> I forgot to mention that the link http://www.bioconductor.org/
> develPage/develPage.html to developer page you send me in the
> attached file is not working.

Oops.  The best place for updated developer info is the Developer
Wiki:
http://www.bioconductor.org/developers/devwiki

We'll restore that URL, however, thanks for the report.


> Also I'm having some problems using NAMESPACE (I don't known if this
> question is better to be in bioc-devel, sorry for the
> inconvenience).  I create a NAMESPACE file and initially exported
> all variables with the export command as:
>
> export(arraySize.Codelink, as.matrix.Codelink, bkgdCorrect.Codelink,
> Codelink-class, codelink.example, cutCV.Codelink, dec.Codelink,
> dim.Codelink, fc.Codelink, log2.Codelink, mergeArray.Codelink,
> na2false, normalize.Codelink, normalize.loess.Codelink,
> plotCorrelation.Codelink, plotCV.Codelink,
> plotDensities.Codelink,
> plotMA.Codelink, printHead.Codelink, read.Codelink,
> readHeader.Codelink, report.Codelink, selCV.Codelink,
> snr.Codelink,
> SNR, write.Codelink)

Some of these names seem strange:

Codelink-class especially because this is not a valid name unless it
is quoted.  I would suggest renaming.

The dots in the names can cause confusion because that is how S3
method dispatch works.


> Then R CMD check gives me error:
> ------------------------------------------------------------------------ 
> -----------------
> * checking package directory ... OK
> * checking for portable file names ... OK
> * checking for sufficient/correct file permissions ... OK
> * checking DESCRIPTION meta-information ... OK
> * checking package dependencies ... OK
> * checking index information ... OK
> * checking package subdirectories ... OK
> * checking R files for syntax errors ... OK
> * checking R files for library.dynam ... OK
> * checking S3 generic/method consistency ... WARNING
> Error: package/namespace load failed for 'codelink'
> Call sequence:
> 2: stop(gettextf("package/namespace load failed for '%s'",
> libraryPkgName(packag
> e)),
> call. = FALSE, domain = NA)
> 1: library(package, lib.loc = lib.loc, character.only = TRUE, verbose
> = FALSE)
> Execution halted
> See section 'Generic functions and methods' of the 'Writing R
> Extensions'
> manual.
> * checking replacement functions ... WARNING
> Error: package/namespace load failed for 'codelink'
>

So one thing to try is simply R CMD INSTALL <YOURPACKAGE> before
running check.  


> Before I tried exportin only a few functions as example and then I
> found that some examples fail to compile when using R CMD check.
> Maeby I miss some basic concept about all of that?

Well the examples are supposed to illustrate how to use the public API
of your package.  That is, the part that end users will interact
with.  Hence, when running examples, only those functions that are
exported in the NAMESPACE file will be accessible.  Make sense?

> Also I don't understand fully how NAMESPACE works. For example if I
> define a function 'normalize' with the same name as 'normalize' in
> affy package, and both packages export 'normalize' function, when I
> do:
>
> library(affy)
> library(codelink)
>
> I will have attached both version (one masking the other)? 

Yes, exactly.  And since you loaded codelink last, I believe that an
unqualified call to normalize() would get the function defined in
codelink.  Names are resolved by looking in the environments defined
by the search path which you can inspect using search().  

If packges A and B both define a function foo (whether or not they use
a NAMESPACE) and if A appears before B in the search list as reported
by search(), then a call to foo() will get the definition in package
A.

> how diferentiate the call to one or other? I have seen the
> possibility affy::normalize described in the documentation but it
> says it is a not recommended alternative to the use of NAMESPACE.

At the interactive level, using "::" to fully qualify your function
calls is the best way to get the function you want.  The comment in
the documentation is about what to do inside your own package code.
Before I say a bit more on that...

Continuing with the packages A and B both defining foo(), let's
suppose that package A has a function bar that calls foo:

Package A                   
                            
bar <- function(x) {        
  ## stuff                  
  z <- foo(x*2)             
  z                         
}                           

Now suppose that package B comes first on the search path.  Without
NAMESPACES, when we call packge A's bar() function, it will end up
calling package B's foo and this is bad.

NAMESPACES protect us from this type of situation.  With a NAMESPACE,
package A can be sure that the foo it gets is its own regardless of
what the search path looks like.

If in package A we wanted to call function baz from package B then we
could:

- use B::baz()
- import baz from B in the NAMESPACE file and just call baz()

Either method will guarantee that we get the right baz.

Hope that clarifies some things with NAMESPACES.  If there are
questions, post 'em to the list and we'll do our best to clarify
further.

Best,

+ seth