R devel - May 2005 - documenation for arrows() is backwards (PR#7839)

Full_Name: Michael Hoffman
Version: 2.1.0
OS: Linux (Fedora Core 3, kernel 2.6.11-1.14_FC3)
Submission from: (NULL) (193.62.199.8)


help(arrows) says:

"""
     arrows(x0, y0, x1, y1, length = 0.25, angle = 30, code = 2,
            col = par("fg"), lty = NULL, lwd = par("lwd"),
xpd = NULL)

...

     If 'code=2' an arrowhead is drawn at '(x0[i],y0[i])' and if
     'code=1' an arrowhead is drawn at '(x1[i],y1[i])'.  If
'code=3' a
     head is drawn at both ends of the arrow.  Unless 'length = 0',
     when no head is drawn.
"""

If you do:

plot(c(-1, 1), c(-1, 1), col=0)
arrows(x0=0, y0=0, x1=0, y1=1, code=2)

it is pretty clear that the arrowhead is drawn at x1, y1 with code=2. If you
switch to code=1, the arrowhead is drawn at x0, y0. Either the documentation or
the function is incorrect.

hoffman.mm+R-project.org@ebi.ac.uk writes:
> Full_Name: Michael Hoffman
> Version: 2.1.0
> OS: Linux (Fedora Core 3, kernel 2.6.11-1.14_FC3)
> Submission from: (NULL) (193.62.199.8)
> 
> 
> help(arrows) says:
> 
> """
>      arrows(x0, y0, x1, y1, length = 0.25, angle = 30, code = 2,
>             col = par("fg"), lty = NULL, lwd =
par("lwd"), xpd = NULL)
> 
> ...
> 
>      If 'code=2' an arrowhead is drawn at '(x0[i],y0[i])'
and if
>      'code=1' an arrowhead is drawn at '(x1[i],y1[i])'.  If
'code=3' a
>      head is drawn at both ends of the arrow.  Unless 'length = 0',
>      when no head is drawn.
> """
> 
> If you do:
> 
> plot(c(-1, 1), c(-1, 1), col=0)
> arrows(x0=0, y0=0, x1=0, y1=1, code=2)
> 
> it is pretty clear that the arrowhead is drawn at x1, y1 with code=2. If
you
> switch to code=1, the arrowhead is drawn at x0, y0. Either the
documentation or
> the function is incorrect.
One way to decide is to compare with Splus. Now that doesn't have a
'code' argument and the arguments are named x1,y1,x2,y2 (I wonder why
R wanted to be different here?), but they do put the arrowheads at the
*to* end, which does seem to be the sensible thing to do. 

Arguably, using 'code=2' as the default is a bit weird, but changing
it could be quite painful. I.e., we should fix the docs.

BTW, the docs also might say that code=0 makes arrows behave like
segments(). It is also a bit strange that the code argument isn't
vectorized, which might have been useful. 

-- 
   O__  ---- Peter Dalgaard             Blegdamsvej 3  
  c/ /'_ --- Dept. of Biostatistics     2200 Cph. N   
 (*) \(*) -- University of Copenhagen   Denmark      Ph: (+45) 35327918
~~~~~~~~~~ - (p.dalgaard@biostat.ku.dk)             FAX: (+45) 35327907

hoffman.mm+R-project.org@ebi.ac.uk writes:
^^^^^^^^^^^^^^^^^^^^^^^^

Let me point out that I for one do not consider it good netiquette to
use fake or mangled email addresses on bug reports! I get enough mail
from the Mailer Daemon as it is.

-- 
   O__  ---- Peter Dalgaard             Blegdamsvej 3  
  c/ /'_ --- Dept. of Biostatistics     2200 Cph. N   
 (*) \(*) -- University of Copenhagen   Denmark      Ph: (+45) 35327918
~~~~~~~~~~ - (p.dalgaard@biostat.ku.dk)             FAX: (+45) 35327907

Peter Dalgaard wrote:
> hoffman.mm+R-project.org@ebi.ac.uk writes:
> 
> 
>>Full_Name: Michael Hoffman
>>Version: 2.1.0
>>OS: Linux (Fedora Core 3, kernel 2.6.11-1.14_FC3)
>>Submission from: (NULL) (193.62.199.8)
>>
>>
>>help(arrows) says:
>>
>>"""
>>     arrows(x0, y0, x1, y1, length = 0.25, angle = 30, code = 2,
>>            col = par("fg"), lty = NULL, lwd =
par("lwd"), xpd = NULL)
>>
>>...
>>
>>     If 'code=2' an arrowhead is drawn at
'(x0[i],y0[i])' and if
>>     'code=1' an arrowhead is drawn at '(x1[i],y1[i])'. 
If 'code=3' a
>>     head is drawn at both ends of the arrow.  Unless 'length =
0',
>>     when no head is drawn.
>>"""
>>
>>If you do:
>>
>>plot(c(-1, 1), c(-1, 1), col=0)
>>arrows(x0=0, y0=0, x1=0, y1=1, code=2)
>>
>>it is pretty clear that the arrowhead is drawn at x1, y1 with code=2. If
you
>>switch to code=1, the arrowhead is drawn at x0, y0. Either the
documentation or
>>the function is incorrect.
> 
> 
> One way to decide is to compare with Splus. Now that doesn't have a
> 'code' argument and the arguments are named x1,y1,x2,y2 (I wonder
why
> R wanted to be different here?), but they do put the arrowheads at the
> *to* end, which does seem to be the sensible thing to do. 
> 
> Arguably, using 'code=2' as the default is a bit weird, 
An argument for the current encoding is that it encodes arrowhead end in 
the bits of code:  00 = no arrowhead, 01 = arrowhead at origin, 10 = 
arrowhead at destination, 11 = arrowhead at both.

 > but changing
 > it could be quite painful. I.e., we should fix the docs.

Yes, definitely.
> BTW, the docs also might say that code=0 makes arrows behave like
> segments(). It is also a bit strange that the code argument isn't
> vectorized, which might have been useful. 
Yes, that would be a reasonable change.

Duncan