[Rd] xy.coords(MATRIX) bug in code or documentation (PR#8937)

[Duncan Murdoch]

On 6/5/2006 5:30 AM, maechler at stat.math.ethz.ch wrote:
>>>>>> "FrPi" == François Pinard <pinard at iro.umontreal.ca>
>>>>>>     on Sun,  4 Jun 2006 06:27:53 +0200 (CEST) writes:
> 
>     FrPi> Hi, people.
>     FrPi> xy.coords() does not behave like its documentation says, when given some
>     FrPi> matrices.   ?xy.coords says:
> 
>     FrPi> If 'y' is 'NULL' and 'x' is a [...] formula [...] list [...]
>     FrPi> time series [...] matrix with two columns [...]
> 
>     FrPi> In any other case, the 'x' argument is coerced to a vector and
>     FrPi> returned as *y* component [...]
> 
>     FrPi> Now, consider this short transcript:
> 
>     FrPi> ======================================================================>
>     >> as.vector(rbind(1, 2, 3))
>     FrPi> [1] 1 2 3
>     >> as.vector(cbind(1, 2, 3))
>     FrPi> [1] 1 2 3
>     >> xy.coords(rbind(1, 2, 3))
>     FrPi> $x
>     FrPi> [1] 1 2 3
> 
>     FrPi> $y
>     FrPi> [1] 1 2 3
> 
>     FrPi> $xlab
>     FrPi> [1] "Index"
> 
>     FrPi> $ylab
>     FrPi> NULL
> 
>     >> xy.coords(cbind(1, 2, 3))
>     FrPi> $x
>     FrPi> [1] 1
> 
>     FrPi> $y
>     FrPi> [1] 2
> 
>     FrPi> $xlab
>     FrPi> [1] "[,1]"
> 
>     FrPi> $ylab
>     FrPi> [1] "[,2]"
> 
>     FrPi> ======================================================================<
> 
>     FrPi> A 3 x 1 matrix and a 1 x 3 matrix both fall in the "In
>     FrPi> any other case" category, but it seems that only the 3 x 1
>     FrPi> is really "coerced to a vector".
> 
> yes. So you are right: There's a bug
> 
>     FrPi> The R code for xy.coord() suggests that the documentation should read
>     FrPi> "matrix with at least two columns" instead of "matrix with two columns".
> 
>     FrPi> As a user, I was really expecting the coercion to a
>     FrPi> vector to happen.  What triggered me into exploring
>     FrPi> this problem is the fact that plot() showed a single
>     FrPi> point where I was expecting many.  If you decide that
>     FrPi> the code is right and the documentation is wrong, then
>     FrPi> I would suggest that the code be a bit more friendly,
>     FrPi> by at least issuing some warning if more than two
>     FrPi> columns are given to a matrix.
> 
> I agree.  
> 
> I'm not sure what the change should be -- and am asking for useR
> feedback here :
> 
> 1) give an error in the case of a matrix (or data.frame) with '> 2' columns
> 2) give a warning, and use the first 2 columns -- as it happens now
> 3) silently coerce to vector -- as the current documentation claims.
> 
> The most clean would be "1)", but given back compatibility, etc,
> my tendency would go into the direction of "2)".

I think the current behaviour is reasonable, and shouldn't lead to 
warnings when executed.  If you meant a warning in the man page, that 
would be fine.	

I'm not so sure about some undocumented behaviour for formulas:

x <- 1:10
y <- 11:20
z <- 21:30
xy.coords(y ~ x+z)

will set the x column to the sum of x+z.  That's not the usual way 
formulas are handled.  I'd be happier with picking out one column, or 
generating an error, instead.

I think the error message might have been the intention, because there's 
a test

  if (inherits(x, "formula") && length(x) == 3)

but length(y ~ x+z) is 3.  I think the test should be

  if (inherits(x, "formula") && length(x) == 3 && length(x[[2]]) == 1 && 
length(x[[3]]) == 1)

Duncan Murdoch
> 
> 
>     FrPi> Another problem in the same area: the documentation lies about how the
>     FrPi> function acts when given a data.frame.  From the code, a data.frame is
>     FrPi> processed as if it was a matrix.  From the documentation, while the
>     FrPi> data.frame is not mentioned explicitely, it is implied in the paragraph
>     FrPi> explaining how a list is processed (because a data.frame is a list).
>     FrPi> Some reconciliation is needed here as well.
> 
> Yes; in this case, I propose to just amend the documentation
> explainining that data.frames are treated "as matrices".
> 
> Thanks a lot, Francois, for your careful reading and
> careful report!
>    [ Though I do slightly mind the word "lies" since
>      I do value the 9th commandment..
>      Not telling the truth *accidentally* is not "lying" ] 
> 
> Martin Maechler, ETH Zurich
> 
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel