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

Hervé Pagès hpages at fredhutch.org
Wed Feb 18 20:52:54 CET 2015


Hi Michael,

On 02/18/2015 11:12 AM, Michael Lawrence wrote:
> 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.

If the proposal is to have R bring up a menu listing all of the
available methods, then the user will have to choose amongst 30+
methods every time s/he does ?length or ?findOverlaps. I think
this is probably overwhelming for most newbies. It's also confusing
to have so many entries to choose amongst when they are only taking
you to 2 or 3 different man pages. So I'd rather stick to a menu
listing the man pages rather than the methods. Don't know how hard
it would be to have R do this automatically though...

Thanks,
H.

>
> On Wed, Feb 18, 2015 at 10:50 AM, Hervé Pagès <hpages at fredhutch.org
> <mailto: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 <mailto: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 <mailto: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 <mailto:plijnzaad at jabber.org> ,
>                 philip.lijnzaad at gmail.com <mailto:philip.lijnzaad at gmail.com>
>                 P.O. Box 85060, 3508 AB Utrecht
>                 (Universiteitsweg 100, 3584 CG Utrecht)
>                 The Netherlands
>                 tel: +31 (0)8875 68464 <tel:%2B31%20%280%298875%2068464>
>
>                 ------------------------------__------------------------------
>                 ------------------
>
>                 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 <mailto:Bioc-devel at r-project.org>
>             mailing list
>             https://stat.ethz.ch/mailman/__listinfo/bioc-devel
>             <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 <mailto:hpages at fredhutch.org>
>     Phone: (206) 667-5791 <tel:%28206%29%20667-5791>
>     Fax: (206) 667-1319 <tel:%28206%29%20667-1319>
>
>

-- 
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