1\name{posdefify}
2\alias{posdefify}
3\title{Find a Close Positive Definite Matrix}
4\description{
5  From a matrix \code{m}, construct a \emph{"close"} positive definite
6  one.
7}
8\usage{
9posdefify(m, method = c("someEVadd", "allEVadd"),
10          symmetric = TRUE, eigen.m = eigen(m, symmetric= symmetric),
11          eps.ev = 1e-07)
12}
13\arguments{
14  \item{m}{a numeric (square) matrix.}
15  \item{method}{a string specifying the method to apply; can be abbreviated.}
16  \item{symmetric}{logical, simply passed to \code{\link{eigen}} (unless
17    \code{eigen.m} is specified); currently, we do not see any reason
18    for \emph{not} using \code{TRUE}.}
19  \item{eigen.m}{the \code{\link{eigen}} value decomposition of
20    \code{m}, can be specified in case it is already available.}
21  \item{eps.ev}{number specifying the tolerance to use, see Details
22    below.}
23}
24\details{
25  We form the eigen decomposition
26  \deqn{m = V \Lambda V'}{m = V L V'} where \eqn{\Lambda}{L} is the
27  diagonal matrix of eigenvalues, \eqn{\Lambda_{j,j} = \lambda_j}{L[j,j]
28    = l[j]}, with \emph{decreasing} eigenvalues \eqn{\lambda_1 \ge
29    \lambda_2 \ge \ldots \ge \lambda_n}{l[1] >= l[2] >= ... >= l[n]}.
30
31  When the smallest eigenvalue \eqn{\lambda_n}{l[n]} are less than
32  \code{Eps <- eps.ev * abs(lambda[1])}, i.e., negative or \dQuote{almost
33    zero}, some or all eigenvalues are replaced by \emph{positive}
34  (\code{>= Eps}) values,
35  \eqn{\tilde\Lambda_{j,j} = \tilde\lambda_j}{L~[j,j] = l~[j]}.
36  Then, \eqn{\tilde m = V \tilde\Lambda V'}{m~ = V L~ V'} is computed
37  and rescaled in order to keep the original diagonal (where that is
38  \code{>= Eps}).
39}
40\value{
41  a matrix of the same dimensions and the \dQuote{same} diagonal
42  (i.e. \code{\link{diag}}) as \code{m} but with the property to
43  be positive definite.
44}
45\author{Martin Maechler, July 2004}
46\note{As we found out, there are more sophisticated algorithms to solve
47  this and related problems.  See the references and the
48  \code{\link[Matrix]{nearPD}()} function in the \CRANpkg{Matrix} package.
49  We consider \code{nearPD()} to also be the successor of this package's \code{\link{nearcor}()}.
50}
51\references{
52  Section 4.4.2 of
53  Gill, P.~E., Murray, W. and Wright, M.~H. (1981)
54  \emph{Practical Optimization}, Academic Press.
55
56  Cheng, Sheung Hun and Higham, Nick (1998)
57  A Modified Cholesky Algorithm Based on a Symmetric Indefinite Factorization;
58  \emph{SIAM J. Matrix Anal.\ Appl.}, \bold{19}, 1097--1110.
59
60  Knol DL, ten Berge JMF (1989)
61  Least-squares approximation of an improper correlation matrix by a
62  proper one.
63  \emph{Psychometrika} \bold{54}, 53--61.
64
65  Highham (2002)
66  Computing the nearest correlation matrix - a problem from finance;
67  \emph{IMA Journal of Numerical Analysis} \bold{22}, 329--343.
68
69  Lucas (2001)
70  Computing nearest covariance and correlation matrices.  A thesis
71  submitted to the University of Manchester for the degree of Master of
72  Science in the Faculty of Science and Engeneering.
73}
74\seealso{\code{\link{eigen}} on which the current methods rely.
75  \code{\link[Matrix]{nearPD}()} in the \CRANpkg{Matrix} package.
76  (Further, the deprecated \code{\link{nearcor}()} from this package.)
77}
78\examples{
79 set.seed(12)
80 m <- matrix(round(rnorm(25),2), 5, 5); m <- 1+ m + t(m); diag(m) <- diag(m) + 4
81 m
82 posdefify(m)
83 1000 * zapsmall(m - posdefify(m))
84}
85\keyword{algebra}
86\keyword{array}
87