[Bioc-devel] Proper way of documenting a BiocGenerics generics with extended prototypes

On 09/21/2015 02:06 AM, Christian Arnold wrote:

Hi Jim, Kasper, and Herv?,

thanks a lot for the quick answer. For some reason, I was under the
impression that I have to use exactly the original prototype from the
generics, but I didn't fully realize I can extend this arbitrarily as
long as the original arguments - object and ... in this case, are among
the extended list.

It works now, perfect, no complaints.

*
**A related question that I have is the following, maybe someone can
share with me his or her thoughts: *

In addition to counts (for which a generics already exists), users can
extract "enrichment" instead of counts out of my object. Because there
is a generics for counts, I thought it makes conceptually sense to also
have a generics for enrichment then, because "enrichment" may also be
something that other packages may use as a general terminology in a
genomic context. So currently, I am creating one in an identical fashion
to counts.

Similarly, I defined one for "parameters" to extract parameters out of
the object that were defined previously in the main function that
creates the object.

For both "enrichment" and "parameters", I could of course also regular
functions, but I was wondering which of the two approaches I should
take. Any thoughts?

Defining generics and methods instead of ordinary functions for
the getters/extractors/setters of an S4 object is generally considered
good practice. If you need to introduce new generics for that (because
the existing vocabulary doesn't suit your needs), it's recommended that
you keep their signatures as "generic" as possible e.g.

     setGeneric("parameters",
         function(object, ...) standardGeneric("object")

     )

so methods can add arguments that are specific to the objects they deal
with.

There are exceptions to this though:

For example the organism() generic that we added recently to
BiocGenerics doesn't have the ellipsis. The contract is simple: it's
a straightforward getter and we kind of want to enforce this i.e. we'd
like methods to stick to that very simple contract. If someone comes up
with a use-case where s/he needs extra arguments in the method that
operates on his/her objects, and makes a good case for it, then we can
always add the ellipsis to the generic.

Another exception can be made when it seems to make sense to have some
extra arguments like a modifier and/or a toggle added to the generic
itself. In that case, it's highly recommended to set dispatch on the
'object' argument only

     setGeneric("enrichment", signature="object",
         function(object, method="auto", ...)
             standardGeneric("enrichment")
     )

otherwise dispatch will be on all the arguments that precede the
ellipsis. Note that defining sensible default values (e.g.
method="auto" or verbose=FALSE) for these extra arguments is probably
a good idea (it's user-friendly and encourages consistent behavior
across methods).

It's all about trying to identify/anticipate what's the greatest common
factor across methods should/will be and have it formalized at the level
of the generic itself. Not necessarily an easy task though. In doubt,
better underestimate than overestimate.

H.

Thanks a lot, very much appreciated!
Christian



On 20.09.2015 21:09, Jim Hester wrote:

Christian,

You need to use your extended prototype in the function definition
within your `setMethod()` call.  In particular you do _not_ need to
write an explicit `@usage` directive.

See
https://github.com/jimhester/examplePrototype/blob/master/R/package.R
for an example package without any NOTEs for this situation.

Jim

On Sun, Sep 20, 2015 at 1:23 PM, Christian Arnold
<christian.arnold at embl.de <mailto:christian.arnold at embl.de>> wrote:

     Hi all,

     I am currently producing the documentation for a new hopefully
     soon-to-be-submitted Bioconductor package and I am facing some
     difficulties with R CMD check.
     In summary: I want to dispatch the existing generic for "counts"
     to make it usable with my object of type SNPhood as well.

     The original prototype from BiocGenerics:

     standardGeneric for "counts" defined from package "BiocGenerics"

     function (object, ...)



     I am calling, as you can see, an internal function for this.
     Currently, because of its original prototype, I use:

     setMethod("counts", "SNPhood", function(object, ...)
     {.getCounts(object, ...)})



     However, in my case, I want to use an extended prototype to
     specify which counts exactly should be extracted.

     .getCounts <- function(SNPhood.o, type, readGroup = NULL, dataset
     = NULL, ...)



     Everything works, but I want to document the additional arguments
     properly. However, with roxygen 2, I am not sure how to achieve
     that without producing warnings.

     I am using:

     #' @usage counts (object, type, readGroup, dataset)

     #' @template object

     #' @param type bla

     #' @template readGroup

     #' @template dataset


     This produces:

     * checking for code/documentation mismatches ... WARNING
     Codoc mismatches from documentation object 'counts,SNPhood-method':
     counts
       Code: function(object, ...)
       Docs: function(object, type, readGroup, dataset)
       Argument names in code not in docs:
         ...
       Argument names in docs not in code:
         type readGroup dataset
       Mismatches in argument names:
         Position: 2 Code: ... Docs: type



     So, what is the recommended way here? I could write an own "new"
     counts function, but I thought if a generics already exists, I
     should use it because this is exactly what my function does also...


     Thanks,
     Christian

     --
     ?????????????????????????
     Christian Arnold, PhD
     Staff Bioinformatician

     SCB Unit - Computational Biology
     Joint appointment Genome Biology
     Joint appointment European Bioinformatics Institute (EMBL-EBI)

     European Molecular Biology Laboratory (EMBL)
     Meyerhofstrasse 1; 69117, Heidelberg, Germany

     Email: christian.arnold at embl.de <mailto:christian.arnold at embl.de>
     Phone: +49(0)6221-387-8472 <tel:%2B49%280%296221-387-8472>
     Web: http://www.zaugg.embl.de/