R devel - Jun 2006 - xy.coords(MATRIX) bug in code or documentation (PR#8937)

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

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

[Martin Maechler]
> Thanks a lot, Francois, for your careful reading and careful report!
Thanks for being receptive! :-)
>    FrPi> Another problem in the same area: the documentation lies
>    FrPi> about how the function acts when given a data.frame.  From
>    FrPi> the code, a data.frame is processed as if it was a matrix.
>    FrPi> From the documentation, while the data.frame is not mentioned
>    FrPi> explicitely, it is implied in the paragraph explaining how
>    FrPi> a list is processed (because a data.frame is a list).  Some
>    FrPi> reconciliation is needed here as well.
>   [ Though I do slightly mind the word "lies" since
>     I do value the 9th commandment..
>     Not telling the truth *accidentally* is not "lying" ]
Of course.  You know, I merely forgot a smiley, there.  You are right in 
that we should try a bit to spare the extreme susceptibility of some 
people!  On the other hand, there should be limits to the feeling that 
we are always walking on eggs while writing to R-help or R-devel, some 
comfort and happiness is needed, after all. :-)
>Yes; in this case, I propose to just amend the documentation
>explainining that data.frames are treated "as matrices".
Let me add a small comment about data.frames.  It would be a bit awkward 
if a data.frame had two columns "y" and "x" (in that order)
and if they
were interpreted differently after matrix coercion.  I guess the problem 
would not exist if data.frames were really interpreted as lists, the
"x"
and "y" columns could even appear anywhere (untested).

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

>>>>> "FrPi" == Fran?ois Pinard <pinard at
iro.umontreal.ca>
>>>>>     on Mon, 5 Jun 2006 08:11:20 -0400 writes:
    FrPi> [Martin Maechler]
    >> Thanks a lot, Francois, for your careful reading and
    >> careful report!

    FrPi> Thanks for being receptive! :-)

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

    >> [ Though I do slightly mind the word "lies" since I do
    >> value the 9th commandment..  Not telling the truth
    >> *accidentally* is not "lying" ]

    FrPi> Of course.  You know, I merely forgot a smiley, there.
    FrPi> You are right in that we should try a bit to spare the
    FrPi> extreme susceptibility of some people!  On the other
    FrPi> hand, there should be limits to the feeling that we
    FrPi> are always walking on eggs while writing to R-help or
    FrPi> R-devel, some comfort and happiness is needed, after
    FrPi> all. :-)

    >> Yes; in this case, I propose to just amend the
    >> documentation explainining that data.frames are treated
    >> "as matrices".

    FrPi> Let me add a small comment about data.frames.  It
    FrPi> would be a bit awkward if a data.frame had two columns
    FrPi> "y" and "x" (in that order) and if they were
    FrPi> interpreted differently after matrix coercion.  I
    FrPi> guess the problem would not exist if data.frames were
    FrPi> really interpreted as lists, the "x" and "y"
columns
    FrPi> could even appear anywhere (untested).

you are right, but, as I now checked.
in  S  xy.coords() also behaves as it does now in R,
BTW, in both respects {data.frames and ">2-column"  matrices and
d.f.s}

Hence --- for back compatibility reasons -- I now tend to agree
with Duncan Murdoch, and would not change xy.coords() behavior
at all, but simply amend the documentation.

Martin

[Martin Maechler]
>Hence --- for back compatibility reasons -- I now tend to agree
>with Duncan Murdoch, and would not change xy.coords() behavior
>at all, but simply amend the documentation.
It's fine, thanks a lot.

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