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

[Hervé Pagès]

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/
>>
>>      _______________________________________________
>>      Bioc-devel at r-project.org <mailto:Bioc-devel at r-project.org> mailing
>>      list
>>      https://stat.ethz.ch/mailman/listinfo/bioc-devel
>>
>>
>

-- 
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 fredhutch.org
Phone:  (206) 667-5791
Fax:    (206) 667-1319