[Rd] Inaccurate documentation for qr.R and qr.Q (PR#8347)

[sims@Princeton.EDU]

This is a multi-part message in MIME format.
--------------060805080907030400090708
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit

The documentation in QR.Auxiliaries {base} states

|qr.Q| returns part or all of *Q*, the order-nrow(X) orthogonal 
(unitary) transformation represented by |qr|. If |complete| is |TRUE|, 
*Q* has |nrow(X)| columns. If |complete| is |FALSE|, *Q* has |ncol(X)| 
columns. When |Dvec| is specified, each column of *Q* is multiplied by 
the corresponding value in |Dvec|.
|qr.R| returns *R*, the upper triangular matrix such that |X == Q %*% R|.

This last statement is true if there has been no pivoting, but if the 
LAPACK=TRUE option is turned on or the x matrix is complex, there is 
likely to be pivoting, and in that case Q %*% R is X with columns 
reordered by the pivot.  qr.X does return the original x matrix in 
either case, but a naive user who uses R alone (e.g. thinking that 
solve(R,crossprod(Q ,y)) will give ols estimates) could be misled.

Example:

 > x <- matrix(c(1,2,3,3,6,8),ncol=2)
 > qrlin <- qr(x)
 > qrla <- qr(x,LAPACK=TRUE)
 > qr.Q(qrlin) %*% qr.R(qrlin)
     [,1] [,2]
[1,]    1    3
[2,]    2    6
[3,]    3    8
 > qr.Q(qrla) %*% qr.R(qrla)
     [,1] [,2]
[1,]    3    1
[2,]    6    2
[3,]    8    3
 > qr.Q(qrla) %*% qr.R(qrla)[,qrla$pivot]
     [,1] [,2]
[1,]    1    3
[2,]    2    6
[3,]    3    8

--------------060805080907030400090708
Content-Type: text/x-vcard; charset=utf-8;
 name="sims.vcf"
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment;
 filename="sims.vcf"

begin:vcard
fn:Chris Sims
n:Sims;Chris
org:Princeton University;Department of Economics
adr:;;Fisher Hall;Princeton;NJ;08544-1021;USA
email;internet:sims at princeton.edu
tel;work:609 258 4033
tel;fax:609 258 6419
x-mozilla-html:FALSE
url:http://www.princeton.edu/~sims
version:2.1
end:vcard


--------------060805080907030400090708--