[Bioc-devel] Documentation of GenomicRanges::follow etc. very hard to find

Wed Feb 18 20:12:13 CET 2015

Great. I was just wondering whether we could make the job of the developer
easier by having R find the methods, instead of needing to add aliases to
every method man page.

On Wed, Feb 18, 2015 at 10:50 AM, Hervé Pagès <hpages at fredhutch.org> wrote:

> Hi,
>
> Philip makes a very good point. This is exactly the reason why,
> a few months ago, I started to alias method man pages with the
> symbol of the generic. For example I've done it for findOverlaps
> and all the intra- and inter- range methods (shift, resize, flank,
> range, reduce, etc...). So after loading the GenomicRanges
> package, if you do ?reduce, you are presented the list of man pages
> that document a "reduce" method (there is one in IRanges and one in
> GenomicRanges) and you can select the one you want. If you do
> ?findOverlaps after loading the GenomicAlignments package, you get
> to choose between 3 man pages.
>
> I've not done this in a systematic way yet but this is the long
> term plan. In the mean time, I just did it for the "precede", "follow",
> "nearest", "distance", and "distanceToNearest" in GenomicRanges.
> This is in GenomicRanges 1.19.38 (BioC devel). More will follow...
>
> Cheers,
> H.
>
>
> On 02/18/2015 09:35 AM, James W. MacDonald wrote:
>
>> I agree with Michael. In my opinion, the help pages for S4 methods are
>> painfully obscure, and expecting anybody (let alone a newbie) to figure
>> out
>> that they need to do something like method?"follow,GenomicRanges,
>> GenomicRanges" in order to get the help page for a method is a high hurdle
>> indeed.
>>
>> In fact, I can't remember the last time I actually tried to find a help
>> page for an S4 method. I much prefer traversing the methods tree using
>> showMethods(), and tracking down the method that will dispatch on whatever
>> object I have in hand, rather than trying to figure out what incredibly
>> unintuitive combination of names, quotes, question marks (and the required
>> order thereof) is required to get the help page.
>>
>> Best,
>>
>> Jim
>>
>>
>>
>> On Wed, Feb 18, 2015 at 9:10 AM, Michael Lawrence <
>> lawrence.michael at gene.com
>>
>>> wrote:
>>>
>>
>>  I guess this is really an argument for having _all_ method man pages be
>>> aliased with the symbol of the generic. I wonder if R should just be made
>>> smarter and bring up a menu whenever help is requested on a generic,
>>> listing all of the available methods, with the default method as the
>>> default selection.
>>>
>>> On Wed, Feb 18, 2015 at 8:38 AM, Philip Lijnzaad <
>>> p.lijnzaad at umcutrecht.nl
>>>
>>>>
>>>>  wrote:
>>>
>>>  On 02/18/2015 05:13 PM, Martin Morgan wrote:
>>>>
>>>>  On 02/18/2015 08:05 AM, Philip Lijnzaad wrote:
>>>>>
>>>>>
>>>>>>      Dear all,
>>>>>>      looking up the documentation on functions like follow() and
>>>>>> precede() is
>>>>>>      very hard, since they are only documented under the topic
>>>>>> "nearest-methods",
>>>>>>      which currently (GenomicRanges package 1.18.4) can only be found
>>>>>> using the
>>>>>>      ?? operator (and having found the name of the topic, most newbies
>>>>>> are still
>>>>>>
>>>>>>
>>>>> FWIW
>>>>>
>>>>>  method?"follow<tab>
>>>>>>
>>>>>
>>>>> shows
>>>>>
>>>>> ANY,SummarizedExperiment
>>>>> GenomicRanges,GenomicRanges
>>>>> GenomicRanges,missing
>>>>> SummarizedExperiment,ANY
>>>>> SummarizedExperiment,SummarizedExperiment
>>>>> Ranges,RangesORmissing
>>>>>
>>>>> suggesting, e.g.,
>>>>>
>>>>>  method?"follow,GenomicRanges,GenomicRanges"
>>>>>>
>>>>>
>>>>>
>>>>>  Hi Martin, thanks for the feedback. To be honest, your solution
>>>> involves
>>>> more typing, and is not newbie-friendly since the
>>>> newbie doesn't now anything about "methods". S/he simply types ?follow
>>>>
>>> and
>>>
>>>> gets back an answer (from the IRanges docu),
>>>> and subsequently thing "oh well, follow() doesn't know about strands,
>>>> and
>>>> then gets stuck). My request is simply to add the plain \alias{}es, i.e.
>>>> just like we have for findOverlaps and the methods described in
>>>> inter-range-methods.Rd. Or what would be the argument against that?
>>>>
>>>> Cheers,
>>>>
>>>>
>>>> Philip
>>>>
>>>> --
>>>> Philip Lijnzaad, PhD
>>>> Molecular Cancer Research
>>>> University Medical Center (UMC), Utrecht
>>>> Stratenum room 2.211
>>>> IM: plijnzaad at jabber.org , philip.lijnzaad at gmail.com
>>>> P.O. Box 85060, 3508 AB Utrecht
>>>> (Universiteitsweg 100, 3584 CG Utrecht)
>>>> The Netherlands
>>>> tel: +31 (0)8875 68464
>>>>
>>>> ------------------------------------------------------------
>>>> ------------------
>>>>
>>>> De informatie opgenomen in dit bericht kan vertrouwelijk zijn en is
>>>> uitsluitend bestemd voor de geadresseerde. Indien u dit bericht
>>>> onterecht
>>>> ontvangt, wordt u verzocht de inhoud niet te gebruiken en de afzender
>>>> direct
>>>> te informeren door het bericht te retourneren. Het Universitair Medisch
>>>> Centrum Utrecht is een publiekrechtelijke rechtspersoon in de zin van de
>>>> W.H.W.
>>>> (Wet Hoger Onderwijs en Wetenschappelijk Onderzoek) en staat
>>>>
>>> geregistreerd
>>>
>>>> bij
>>>> de Kamer van Koophandel voor Midden-Nederland onder nr. 30244197.
>>>>
>>>> Denk s.v.p aan het milieu voor u deze e-mail afdrukt.
>>>>
>>>> ------------------------------------------------------------
>>>> ------------------
>>>>
>>>> This message may contain confidential information and ...{{dropped:11}}
>>>>
>>>
>>> _______________________________________________
>>> 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
>

	[[alternative HTML version deleted]]