diff --git a/R/lotri.R b/R/lotri.R index b35ff4f..66ca600 100644 --- a/R/lotri.R +++ b/R/lotri.R @@ -886,6 +886,10 @@ NULL #' it is equivalent to `cov=TRUE` with the additional ability to #' correct the matrix to be non-positive definite if needed. #' +#' @param rcm logical; if `TRUE`, the matrix will be reordered to +#' change the matrix to a banded matrix, which is easier to express +#' in `lotri` than a full matrix. +#' #' @inheritParams base::eval #' @inheritParams as.lotri #' diff --git a/R/lotriNearPD.R b/R/lotriNearPD.R index 9fd50fe..6c80b86 100644 --- a/R/lotriNearPD.R +++ b/R/lotriNearPD.R @@ -10,9 +10,40 @@ #' symmetry test. \emph{Beware} however that setting it \code{FALSE} #' for an \bold{a}symmetric input \code{x}, is typically nonsense! #' +#' @param do2eigen logical indicating if a `posdefify()` (like in the +#' package `sfsmisc`) eigen step should be applied to the result of +#' the Higham algorithm +#' +#' @seealso A first version of this (with non-optional \code{corr=TRUE}) +#' has been available as `sfsmisc::nearcor()` and +#' more simple versions with a similar purpose +#' `sfsmisc::posdefify()` +#' #' @return unlike the matrix package, this simply returns the nearest #' positive definite matrix #' +#' @author Jens \enc{Oehlschlägel}{Oehlschlaegel} donated a first +#' version to Matrix. Subsequent changes by the Matrix package +#' authors, later modifications to C++ by Matthew Fidler +#' +#' @details +#' +#' This implements the algorithm of Higham (2002), and then (if +#' \code{do2eigen} is true) forces positive definiteness using code from +#' `sfsmisc::posdefify()`. The algorithm of Knol and ten +#' Berge (1989) (not implemented here) is more general in that it +#' allows constraints to (1) fix some rows (and columns) of the matrix and +#' (2) force the smallest eigenvalue to have a certain value. +#' +#' Note that setting \code{corr = TRUE} just sets \code{diag(.) <- 1} +#' within the algorithm. +#' +#' Higham (2002) uses Dykstra's correction, but the version by Jens +#' \enc{Oehlschlägel}{Oehlschlaegel} did not use it (accidentally), +#' and still gave reasonable results; this simplification, now only +#' used if \code{doDykstra = FALSE}, +#' was active in \code{nearPD()} up to Matrix version 0.999375-40. +#' #' @examples #' #' set.seed(27) diff --git a/man/lotri.Rd b/man/lotri.Rd index 83f2981..65143b0 100644 --- a/man/lotri.Rd +++ b/man/lotri.Rd @@ -4,7 +4,7 @@ \alias{lotri} \title{Easily Specify block-diagonal matrices with lower triangular info} \usage{ -lotri(x, ..., cov = FALSE, envir = parent.frame(), default = "id") +lotri(x, ..., cov = FALSE, rcm = FALSE, envir = parent.frame(), default = "id") } \arguments{ \item{x}{list, matrix or expression, see details} @@ -33,6 +33,10 @@ concatenated then reapplied to this function.} it is equivalent to `cov=TRUE` with the additional ability to correct the matrix to be non-positive definite if needed.} +\item{rcm}{logical; if `TRUE`, the matrix will be reordered to +change the matrix to a banded matrix, which is easier to express +in `lotri` than a full matrix.} + \item{envir}{the \code{\link[base]{environment}} in which \code{expr} is to be evaluated. May also be \code{NULL}, a list, a data frame, a pairlist or an integer as specified to \code{\link[base]{sys.call}}.} diff --git a/man/lotriNearPD.Rd b/man/lotriNearPD.Rd index 659ca92..84a5346 100644 --- a/man/lotriNearPD.Rd +++ b/man/lotriNearPD.Rd @@ -28,9 +28,9 @@ lotriNearPD( resulting matrix should have the same diagonal (\code{\link{diag}(x)}) as the input matrix.} -\item{do2eigen}{logical indicating if a - \code{\link[sfsmisc]{posdefify}()} eigen step should be applied to - the result of the Higham algorithm.} +\item{do2eigen}{logical indicating if a `posdefify()` (like in the +package `sfsmisc`) eigen step should be applied to the result of +the Higham algorithm} \item{doDykstra}{logical indicating if Dykstra's correction should be used; true by default. If false, the algorithm is basically the @@ -69,19 +69,19 @@ With `ensureSymmetry` it makes sure it is symmetric by applying 0.5*(t(x) + x) b } \details{ This implements the algorithm of Higham (2002), and then (if - \code{do2eigen} is true) forces positive definiteness using code from - \code{\link[sfsmisc]{posdefify}}. The algorithm of Knol and ten - Berge (1989) (not implemented here) is more general in that it - allows constraints to (1) fix some rows (and columns) of the matrix and - (2) force the smallest eigenvalue to have a certain value. +\code{do2eigen} is true) forces positive definiteness using code from +`sfsmisc::posdefify()`. The algorithm of Knol and ten +Berge (1989) (not implemented here) is more general in that it +allows constraints to (1) fix some rows (and columns) of the matrix and +(2) force the smallest eigenvalue to have a certain value. - Note that setting \code{corr = TRUE} just sets \code{diag(.) <- 1} - within the algorithm. +Note that setting \code{corr = TRUE} just sets \code{diag(.) <- 1} +within the algorithm. - Higham (2002) uses Dykstra's correction, but the version by Jens - \enc{Oehlschlägel}{Oehlschlaegel} did not use it (accidentally), +Higham (2002) uses Dykstra's correction, but the version by Jens + \enc{Oehlschlägel}{Oehlschlaegel} did not use it (accidentally), and still gave reasonable results; this simplification, now only - used if \code{doDykstra = FALSE}, + used if \code{doDykstra = FALSE}, was active in \code{nearPD()} up to Matrix version 0.999375-40. } \examples{ @@ -129,11 +129,12 @@ nc <- lotriNearPD(pr) } \seealso{ A first version of this (with non-optional \code{corr=TRUE}) - has been available as \code{\link[sfsmisc]{nearcor}()}; and - more simple versions with a similar purpose - \code{\link[sfsmisc]{posdefify}()}, both from package \pkg{sfsmisc}. +has been available as `sfsmisc::nearcor()` and +more simple versions with a similar purpose +`sfsmisc::posdefify()` } \author{ -Jens \enc{Oehlschlägel}{Oehlschlaegel} donated a first version. - Subsequent changes by the Matrix package authors. +Jens \enc{Oehlschlägel}{Oehlschlaegel} donated a first + version to Matrix. Subsequent changes by the Matrix package + authors, later modifications to C++ by Matthew Fidler }