R devel - Nov 2007 - ?eigen documentation suggestion

from ?eigen

symmetric: if 'TRUE', the matrix is assumed to be symmetric (or
          Hermitian if complex) and only its lower triangle is used. If
          'symmetric' is not specified, the matrix is inspected for
          symmetry.


I think that could mislead a naive reader as it suggests that, with
symmetric=TRUE,
the result of eigen() (vectors and values) depends only on the lower-triangular
values,
and thus not on the values on the diagonal (that's not true for the
eigenvalues).

I suggest that changing it to 

"... and only its lower triangle is used when computing the
eigenvectors."

would be more accurate, perhaps even with a reminder about the trace - sum of
eigenvalues
relationship.

Dan

>>>>> "DD" == Dan Davison <davison at
stats.ox.ac.uk>
>>>>>     on Thu, 29 Nov 2007 11:34:18 +0000 writes:
    DD> from ?eigen
    DD> symmetric: if 'TRUE', the matrix is assumed to be symmetric
(or
    DD> Hermitian if complex) and only its lower triangle is used. If
    DD> 'symmetric' is not specified, the matrix is inspected for
    DD> symmetry.


    DD> I think that could mislead a naive reader as it suggests that, with
symmetric=TRUE,
    DD> the result of eigen() (vectors and values) depends only on the
lower-triangular values,
    DD> and thus not on the values on the diagonal (that's not true for
the eigenvalues).

Well, that all depends on what you think when you read 
"lower triangle".

For many of us, this can include the diagonal or not, and we
don't know if it is not specified further.

?lower.tri  -- shows the option to include the diagonal.

Consequently, I'd suggest to replace

       "only its lower triangle is used"
with   "only its lower triangle (diagonal included) is used"

Martin Maechler, ETH Zurich

    DD> I suggest that changing it to 

    DD> "... and only its lower triangle is used when computing the
eigenvectors."

    DD> would be more accurate, perhaps even with a reminder about the trace
- sum of eigenvalues
    DD> relationship.

    DD> Dan

    DD> ______________________________________________
    DD> R-devel at r-project.org mailing list
    DD> https://stat.ethz.ch/mailman/listinfo/r-devel