[Bioc-devel] Documentation of GenomicRanges::follow etc. very hard to find
Michael Lawrence
lawrence.michael at gene.com
Wed Feb 18 22:26:56 CET 2015
By default, the menu could collapse the methods by man page, so there would
not be an imposing number of choices. Another idea (for extreme cases like
length) would be to have aliases that do not appear in the index, in the
same way that \keyword{internal} hides entire man pages. Maybe \alias*{} to
match LaTeX conventions.
On Wed, Feb 18, 2015 at 12:29 PM, Martin Morgan <mtmorgan at fredhutch.org>
wrote:
> On 02/18/2015 11:52 AM, Hervé Pagès wrote:
>
>> 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
>>
>
> maybe the proverbial newbie is using the graphical interface provided by
> help.start() (maybe through RStudio) and choosing the 'Search Engine &
> Keywords' link, where entering findOverlaps returns something approximating
> helpful (man pages on which findOverlaps methods are defined, Hervé's
> suggestion, I think, though for installed rather than loaded packages)
> whereas entering length does not (man pages on which length is defined, but
> there are too many man pages! This would discourage me as a newbie [it
> discourages me as an experienced user!]). Certainly we'd (Michael ;)) would
> like to avoid creating that kind of tangle.
>
> If my FWIW were targeted at a newbie I might have been better expressed it
> as
>
> > ?"follow<tab>
>
> Completion is limited to loaded packages; somehow enumerating all
> documented methods is not too overwhelming (well, moderately overwhelming;
> is my 'GRanges' a 'GenomiceRanges' or a 'Ranges' or an 'ANY'??). Of course
> a more automatic solution would be great, or in lieu of that the careful
> manual curation suggested by the original post / realized by Hervé.
>
> Martin
>
>
>
> 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>
>>>
>>>
>>>
>>
>
> --
> Computational Biology / Fred Hutchinson Cancer Research Center
> 1100 Fairview Ave. N.
> PO Box 19024 Seattle, WA 98109
>
> Location: Arnold Building M1 B861
> Phone: (206) 667-2793
>
[[alternative HTML version deleted]]
More information about the Bioc-devel
mailing list