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

[pinard at iro.umontreal.ca]

Hi, people.

xy.coords() does not behave like its documentation says, when given some
matrices.   ?xy.coords says:

     If 'y' is 'NULL' and 'x' is a [...] formula [...] list [...]
     time series [...] matrix with two columns [...]

     In any other case, the 'x' argument is coerced to a vector and
     returned as *y* component [...]

Now, consider this short transcript:

======================================================================>
> as.vector(rbind(1, 2, 3))
[1] 1 2 3
> as.vector(cbind(1, 2, 3))
[1] 1 2 3
> xy.coords(rbind(1, 2, 3))
$x
[1] 1 2 3

$y
[1] 1 2 3

$xlab
[1] "Index"

$ylab
NULL

> xy.coords(cbind(1, 2, 3))
$x
[1] 1

$y
[1] 2

$xlab
[1] "[,1]"

$ylab
[1] "[,2]"

======================================================================<

A 3 x 1 matrix and a 1 x 3 matrix both fall in the "In any other case"
category, but it seems that only the 3 x 1 is really "coerced to a vector".

The R code for xy.coord() suggests that the documentation should read
"matrix with at least two columns" instead of "matrix with two columns".

As a user, I was really expecting the coercion to a vector to happen.
What triggered me into exploring this problem is the fact that plot()
showed a single point where I was expecting many.  If you decide that
the code is right and the documentation is wrong, then I would suggest
that the code be a bit more friendly, by at least issuing some warning
if more than two columns are given to a matrix.

Another problem in the same area: the documentation lies about how the
function acts when given a data.frame.  From the code, a data.frame is
processed as if it was a matrix.  From the documentation, while the
data.frame is not mentioned explicitely, it is implied in the paragraph
explaining how a list is processed (because a data.frame is a list).
Some reconciliation is needed here as well.

--please do not edit the information below--

Version:
 platform = i686-pc-linux-gnu
 arch = i686
 os = linux-gnu
 system = i686, linux-gnu
 status = Under development (unstable)
 major = 2
 minor = 4.0
 year = 2006
 month = 06
 day = 01
 svn rev = 38258
 language = R
 version.string = R version 2.4.0 Under development (unstable) (2006-06-01 r38258)

Locale:
LC_CTYPE=fr_CA.UTF-8;LC_NUMERIC=C;LC_TIME=fr_CA.UTF-8;LC_COLLATE=fr_CA.UTF-8;LC_MONETARY=fr_CA.UTF-8;LC_MESSAGES=fr_CA.UTF-8;LC_PAPER=fr_CA.UTF-8;LC_NAME=C;LC_ADDRESS=C;LC_TELEPHONE=C;LC_MEASUREMENT=fr_CA.UTF-8;LC_IDENTIFICATION=C

Search Path:
 .GlobalEnv, package:methods, package:stats, package:utils, package:datasets, fp.etc, package:graphics, package:grDevices, Autoloads, package:base

-- 
François Pinard   http://pinard.progiciels-bpi.ca