R/matrix-utils.R

Defines functions correct_positive_definite_simplified correct_positive_definite

Documented in correct_positive_definite

#' Positive definite matrices
#'
#' \code{correct_positive_definite} verifies that a given covariance matrix
#' is indeed positive definite by checking that all eigenvalues are positive.
#' If the given covariance matrix is not positive definite,
#' \code{correct_positive_definite} tries to modify the underlying correlation matrices
#' genetic_corrmat and full_corrmat in order to obtain a positive definite
#' covariance matrix.
#'
#' This function can be used to verify that a given covariance matrix
#' is positive definite. It calculates all eigenvalues in order to
#' investigate whether they are all positive. This property is necessary
#' for the covariance matrix to be used as a Gaussian covariance matrix.
#' It is especially useful to check whether any covariance matrix obtained
#' by \code{\link{construct_covmat_multi}} is positive definite.
#' If the given covariance matrix is not positive definite, \code{correct_positive_definite}
#' tries to modify the underlying correlation matrices (called \code{genetic_corrmat} and
#' \code{full_corrmat} in \code{\link{construct_covmat}} or \code{\link{construct_covmat_multi}}) by
#' multiplying all off-diagonal entries in the correlation matrices by a given number.
#'
#' @param covmat A symmetric and numeric matrix. If the covariance matrix
#' should be corrected, it must have a number of attributes, such as
#' \code{attr(covmat,"fam_vec")}, \code{attr(covmat,"n_fam")},
#' \code{attr(covmat,"add_ind")}, \code{attr(covmat,"h2")},
#' \code{attr(covmat,"genetic_corrmat")}, \code{attr(covmat,"full_corrmat")}
#' and \code{attr(covmat,"phenotype_names")}. Any covariance matrix
#' obtained by \code{\link{construct_covmat}}, \code{\link{construct_covmat_single}}
#' or \code{\link{construct_covmat_multi}} will have these attributes by default.
#' @param correction_val A positive number representing the amount by which
#' \code{genetic_corrmat} and \code{full_corrmat} will be changed, if some
#' eigenvalues are non-positive. That is, correction_val is the number that will be
#' multiplied to all off_diagonal entries in \code{genetic_corrmat} and \code{full_corrmat}.
#' Defaults to 0.99.
#' @param correction_limit A positive integer representing the upper limit for the correction
#' procedure. Defaults to 100.
#'
#' @return If \code{covmat} is a symmetric and numeric matrix and all eigenvalues are
#' positive, \code{correct_positive_definite} simply returns \code{covmat}. If some
#' eigenvalues are not positive and \code{correction_val} is a positive number,
#' \code{correct_positive_definite} tries to convert \code{covmat} into a positive definite
#' matrix. If \code{covmat} has attributes \code{add_ind}, \code{h2},
#' \code{genetic_corrmat}, \code{full_corrmat} and \code{phenotype_names},
#' \code{correct_positive_definite} computes a new covariance matrix using slightly
#' modified correlation matrices \code{genetic_corrmat} and \code{full_corrmat}.
#' If the correction is performed successfully, i.e. if the new covariance matrix
#' is positive definite,the new covariance matrix is returned.
#' Otherwise, \code{correct_positive_definite} returns the original covariance matrix.
#'
#' @examples
#' ntrait <- 2
#' genetic_corrmat <- matrix(0.6, ncol = ntrait, nrow = ntrait)
#' diag(genetic_corrmat) <- 1
#' full_corrmat <- matrix(-0.25, ncol = ntrait, nrow = ntrait)
#' diag(full_corrmat) <- 1
#' h2_vec <- rep(0.6, ntrait)
#' cov <- construct_covmat(fam_vec = c("m", "f"),
#'   genetic_corrmat = genetic_corrmat,
#'   h2 = h2_vec,
#'   full_corrmat = full_corrmat)
#' cov
#' correct_positive_definite(cov)
#'
#' @seealso \code{\link{construct_covmat}}, \code{\link{construct_covmat_single}} and
#' \code{\link{construct_covmat_multi}}.
#'
#' @export
correct_positive_definite = function(covmat, correction_val = .99, correction_limit = 100) {

  # Checking that covmat is symmetric
  if (!isSymmetric.matrix(covmat)) stop("The covariance matrix covmat must be symmetric!")
  # and numeric
  if (!is.numeric(covmat)) stop("The covariance matrix covmat must be numeric!")

  # Checking whether all eigenvalues are positive
  if (any(eigen(covmat)$values < 0)) {

    message("The specified covariance matrix is not positive definite. \n")
  }else{

    return(covmat)
  }

  # If some eigenvalues are negative, correction_val must be specified,
  # it must be numeric and positive in order to correct the covariance matrix.
  if (!is.numeric(correction_val) && !is.integer(correction_val)) stop("correction_val must be numeric!")
  if (correction_val <= 0) stop("correction_val must be positive!")

  # In addition, covmat must have several attributes holding the
  # family members (fam_vec or n_fam), a logical add_ind as well as
  # a numeric value or numeric matrix h2 and numeric matrices
  # genetic_corrmat and full_corrmat in order to change
  # the correlation matrix.
  if (is.null(attr(covmat,"add_ind")) || is.null(attr(covmat,"h2")) ||
     is.null(attr(covmat,"genetic_corrmat")) || is.null(attr(covmat,"full_corrmat"))) {

    warning("The required attributes are missing... The covariance matrix could not be corrected!")
    return(covmat)
  }

  # If the covariance matrix is for a single phenotype, it is not
  # possible to correct the covariance matrix.
  if (length(attr(covmat,"h2")) == 1) {
    warning("The covariance matrix cannot be corrected...")
    return(covmat)
  }

  # Furthermore, correction_limit must be a positive number
  if (!is.numeric(correction_limit)) stop("correction_limit must be numeric!")
  if (correction_limit <= 0) stop("Correction limit must be positive!")

  message("Trying to correct the covariance matrix...\n")

  # The covariance matrix will be modified at most correction_limit times.
  n <- 0
  # Storing the old covariance matrix
  old_covmat <- covmat

  # We also extract the vectors holding the family members
  fam_vec <- setdiff(attr(covmat,"fam_vec"), c("g","o"))
  #n_fam <- attr(covmat,"n_fam")[stringr::str_detect(names(attr(covmat,"n_fam")), "^[^go]")]

  while (any(eigen(covmat)$values < 0) && n <= correction_limit) {

    # Changing the correlation matrices slightly by
    # multiplying all entries by correction_val.
    genetic_corrmat <- attr(covmat,"genetic_corrmat")*correction_val
    diag(genetic_corrmat) <- 1
    full_corrmat <- attr(covmat,"full_corrmat")*correction_val
    diag(full_corrmat) <- 1
    # Computing a new covariance matrix
    covmat <- construct_covmat(fam_vec = fam_vec,
                               n_fam = NULL,
                               add_ind = attr(covmat,"add_ind"),
                               genetic_corrmat = genetic_corrmat,
                               full_corrmat = full_corrmat,
                               h2 = attr(covmat,"h2"),
                               phen_names = attr(covmat,"phenotype_names"))
    # Updating
    n <- n + 1
  }

  # If the matrix has been modified correction_limit times,
  # the correction step is aborted
  if (n > correction_limit) {
    message("The covariance matrix could not be corrected. Consider revisiting it.\n")
    return(old_covmat)
  }

  message(paste0("The correction was performed successfully! All off-diagonal entries are corrected by", round(correction_val^n,digits = 3),".\n"))

  return(covmat)
}

#' A simplied version of correct_positive_definite
#'
#' multiplies off-diagonal elements of a matrix with a correction value until all eigen values are positive or correction limit is reached.
#'
#' @param covmat Covariance matrix that needs to be positive definite
#' @param correction_limit The maximum number of times to correct off-diagonal elements
#' @param correction_val The value to multiply on the off-diagnoal elements.
#'
#' @return Returns list with the corrected covmat and number of iterations used to achieve positive definite.
#' @noRd

correct_positive_definite_simplified = function(covmat, correction_limit = 100, correction_val = 0.99) {
  eigen_val = eigen(covmat)

  if ( any(eigen_val$values < 0) ) {
    og_diag = diag(covmat)
    n = 0

    while (any(eigen(covmat)$values < 0) & n <= correction_limit ) {
      covmat = covmat*correction_val
      diag(covmat) = og_diag
      n = n + 1
    }

    # Bug fix: this used to re-check `eigen_val` here, i.e. the *original*
    # eigenvalues computed before the while loop ever ran - which are
    # guaranteed to still contain a negative value (that's the only reason
    # this branch was entered), making this check unconditionally TRUE. In
    # practice this meant the function always stop()'d whenever correction
    # was needed at all, even when the while loop above had already
    # succeeded - the correction machinery could never actually return a
    # corrected matrix. `n > correction_limit` (mirroring
    # correct_positive_definite()'s equivalent check) correctly detects
    # whether the loop exited because it converged or because it hit the
    # iteration limit.
    if (n > correction_limit) stop("Unable to enforce a positive definite covariance matrix.")
    return(list(covmat = covmat, nitr = n))
  } else {
    return(list(covmat = covmat, nitr = 0))
  }
}

Try the LTFGRS package in your browser

Any scripts or data that you put into this service are public.

LTFGRS documentation built on Nov. 20, 2026, 5:10 p.m.