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

[maechler at stat.math.ethz.ch]

>>>>> "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)".


    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