From gavin.simpson at ucl.ac.uk  Sat Jan 21 20:28:09 2006
From: gavin.simpson at ucl.ac.uk (Gavin Simpson)
Date: Sat, 21 Jan 2006 19:28:09 +0000
Subject: [Rd] Bug in xy.coords() or documentation error?
In-Reply-To: <43D28668.1030805@stats.uwo.ca>
References: <1137866719.2523.33.camel@dsl-217-155-166-107.zen.co.uk>
	<971536df0601211012t19e45314ieb573d8acf71a32b@mail.gmail.com>
	<1137867712.2523.41.camel@dsl-217-155-166-107.zen.co.uk>
	<43D28668.1030805@stats.uwo.ca>
Message-ID: <1137871689.2523.56.camel@dsl-217-155-166-107.zen.co.uk>

On Sat, 2006-01-21 at 14:07 -0500, Duncan Murdoch wrote:
> On 1/21/2006 1:21 PM, Gavin Simpson wrote:
> > On Sat, 2006-01-21 at 13:12 -0500, Gabor Grothendieck wrote:
> >> This was discussed just recently.   This is a design
> >> error but the maintainers claim there are no cases of
> >> interest where it matters.
> > 
> > Thanks Gabor,
> > 
> > I must have missed that discussion whilst I was on vacation. If what you
> > say was the outcome of that discussion, it still means that the
> > documentation for xy.coords is in error, as you may *not* provide a
> > single argument 'x'.
> 
> You need to read the whole page.  You provide a single argument x by 
> setting y to NULL, not by leaving it missing (as the docs said in 
> earlier versions).
> 
> If you want to submit a patch to the docs, I'll take a look, but I don't 
> like the one below.  It has basically the same flaw as the current docs: 
>   you're providing two objects, not a single object.  Probably the 
> clearest thing to do is just to say "see below" after the current 
> wording, to point out that there are funny conventions here.

How about:

x, y: the x and y coordinates of a set of points. Alternatively, 'x' may
be a formula, list, time series or a matrix-like object with two
columns, in which case 'y' should be 'NULL', see Details below.

Or,

x, y: the x and y coordinates of a set of points. Alternatively, 'x' may
take different forms. If so, 'y' must be supplied as 'NULL'. See Details
below.

Or,

x, y: the x and y coordinates of a set of points. Alternatively, 'x' may
take different forms. See Details below.

I can provide you with a revised Rd file for xy.coords() if you think
any of the above are acceptable

All the best,

Gav

> 
> > If the intention is to keep the current behaviour - which is fine - then
> > the documentation should be changed, perhaps along the lines of:
> > 
> >     x, y: the x and y coordinates of a set of points. Alternatively, a
> >           single object 'x' can be provided if 'y = NULL' is also  
> >           supplied.
> > 
> > 'object' might not be correct here - is a formula an 'object'?
> 
> Sure, why not?
> 
> Duncan Murdoch
> 
> > 
> > Cheers,
> > 
> > Gav
> > 
> >> On 1/21/06, Gavin Simpson <gavin.simpson at ucl.ac.uk> wrote:
> >>> Hi,
> >>>
> >>> I noticed the following problem with xy.coords() in R 2.2.1-patched
> >>> (version info at the foot of this email) and R 2.3.0 unstable
> >>> (subversion no: r37123):
> >>>
> >>>> xy.coords(x = matrix(1:20, ncol = 2))
> >>> Error in xy.coords(x = matrix(1:20, ncol = 2)) :
> >>>        argument "y" is missing, with no default
> >>>> xy.coords(x = matrix(1:20, ncol = 2), y = NULL)
> >>> $x
> >>>  [1]  1  2  3  4  5  6  7  8  9 10
> >>>
> >>> $y
> >>>  [1] 11 12 13 14 15 16 17 18 19 20
> >>>
> >>> $xlab
> >>> [1] "[,1]"
> >>>
> >>> $ylab
> >>> [1] "[,2]"
> >>>
> >>> And:
> >>>
> >>>> xy.coords(x = data.frame(x = 1:10, y = 1:10))
> >>> Error in xy.coords(x = data.frame(x = 1:10, y = 1:10)) :
> >>>        argument "y" is missing, with no default
> >>>> xy.coords(x = data.frame(x = 1:10, y = 1:10), y = NULL)
> >>> $x
> >>>  [1]  1  2  3  4  5  6  7  8  9 10
> >>>
> >>> $y
> >>>  [1]  1  2  3  4  5  6  7  8  9 10
> >>>
> >>> $xlab
> >>> [1] "x"
> >>>
> >>> $ylab
> >>> [1] "y"
> >>>
> >>> ... for example.
> >>>
> >>> ?xy.coords states:
> >>>
> >>>    x, y: the x and y coordinates of a set of points. Alternatively, a
> >>>          single argument 'x' can be provided.
> >>>
> >>> Given that, I would have thought the above examples would have worked
> >>> without explicitly passing y = NULL to xy.coords(). However, ?xy,coords
> >>> later states:
> >>>
> >>>    If 'y' is 'NULL' and 'x' is a
> >>>
> >>> and the examples all illustrate the use of NULL passed as y.
> >>>
> >>> Is this a documentation error and a single argument x is not allowed, or
> >>> is this a bug in the code? Either way, ?xy.coords contradicts itself as
> >>> one would expect to be able to pass only x given the statement above.
> >>>
> >>> If this is a bug in the code, a potential workaround appears to be to
> >>> change the first line of xy.coords from:
> >>>
> >>>   if (is.null(y)) {
> >>>
> >>> to
> >>>
> >>>   if (missing(y) || is.null(y)) {
> >>>
> >>> but I haven't tested this on anything other than my two examples.
> >>>
> >>> I will file a bug report if my observation is correct - but given all
> >>> the erroneous bug reports lately, I thought I'd try my luck here where
> >>> an error on my part would not cause the maintainers of the bug tracker
> >>> any extra work.
> >>>
> >>>> version
> >>>         _
> >>> platform i686-pc-linux-gnu
> >>> arch     i686
> >>> os       linux-gnu
> >>> system   i686, linux-gnu
> >>> status   Patched
> >>> major    2
> >>> minor    2.1
> >>> year     2006
> >>> month    01
> >>> day      18
> >>> svn rev  37123
> >>> language R
> >>>> sessionInfo()
> >>> R version 2.2.1, 2006-01-18, i686-pc-linux-gnu
> >>>
> >>> attached base packages:
> >>> [1] "methods"   "stats"     "graphics"  "grDevices"
> >>> [5] "utils"     "datasets"  "base"
> >>>
> >>> All the best,
> >>>
> >>> Gav
> >>>
> >>> --
> >>> %~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%
> >>> Gavin Simpson                     [T] +44 (0)20 7679 5522
> >>> ENSIS Research Fellow             [F] +44 (0)20 7679 7565
> >>> ENSIS Ltd. & ECRC                 [E] gavin.simpsonATNOSPAMucl.ac.uk
> >>> UCL Department of Geography       [W] http://www.ucl.ac.uk/~ucfagls/cv/
> >>> 26 Bedford Way                    [W] http://www.ucl.ac.uk/~ucfagls/
> >>> London.  WC1H 0AP.
> >>> %~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%
> >>>
> >>> ______________________________________________
> >>> R-devel at r-project.org mailing list
> >>> https://stat.ethz.ch/mailman/listinfo/r-devel
> >>>
> 
-- 
%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%
Gavin Simpson                     [T] +44 (0)20 7679 5522
ENSIS Research Fellow             [F] +44 (0)20 7679 7565
ENSIS Ltd. & ECRC                 [E] gavin.simpsonATNOSPAMucl.ac.uk
UCL Department of Geography       [W] http://www.ucl.ac.uk/~ucfagls/cv/
26 Bedford Way                    [W] http://www.ucl.ac.uk/~ucfagls/
London.  WC1H 0AP.
%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%



[Rd] Bug in xy.coords() or documentation error?
Gavin Simpson