[Bioc-devel] Proper way of documenting a BiocGenerics generics with extended prototypes
Hervé Pagès
hpages at fredhutch.org
Mon Sep 21 19:41:11 CEST 2015
On 09/21/2015 10:39 AM, Hervé Pagès wrote:
> 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")
function(object, ...) standardGeneric("parameters")
^^^^^^^^^^
of course...
H.
> )
>
> 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
More information about the Bioc-devel
mailing list