R/check.stopping.R

In kridsadakorn/ipcaps2: Iterative Pruning to Capture Population Structure version 2

#' (Internal function) Check whether the IPCAPS2 process meets the stopping
#' criterion.
#'
#' @param eigen.value A vector of Eigenvalues return from \code{svd} ($d),
#' \code{rARPACK::svds} ($d),  \code{eigen} ($values) or \code{rARPACK::eigs} ($values).
#' @param threshold A threshold or a cutoff to stop the IPCAPS2 process. Also see
#' \code{\link{ipcaps2}} (the parameter \code{threshold}).
#'
#' @return A list containing \code{status}, \code{eigen.value}, \code{eigen.fit},
#' \code{threshold}, and \code{no.significant.PC} as explained below:
#' \itemize{
#' \item \code{$status} is either \code{0} representing that the criterion is
#' not met, or \code{1} representing that the criterion is met.
#' \item \code{$eigen.value} is a vector of Eigenvalues as the input parameter.
#' \item \code{$eigen.fit} is a vector of EigenFit values.
#' \item \code{$threshold} is a threashold as the input parameter.
#' \item \code{$no.significant.PC} is an estimated number of sinificant
#' principal components (PC).
#' }
#'
#' @include parallelization.R

check.stopping <- function(eigen.value, threshold)
{
  eigen.fit.vec <- cal.eigen.fit(eigen.value)
  eigen.fit <- max(eigen.fit.vec)
  no.significant.PC <-
    length(eigen.fit.vec[seq(1, which(eigen.fit.vec ==
                                        eigen.fit)[1])])
  if (no.significant.PC < 3)
  {
    no.significant.PC <- 3
  }

  ret <-
    list(
      status = 0,
      eigen.value = eigen.value,
      eigen.fit = eigen.fit,
      threshold = threshold,
      no.significant.PC = no.significant.PC
    )

  if (eigen.fit < threshold)
  {
    # case of status = 1, no more spliting, stopping criteria are met
    ret <-
      list(
        status = 1,
        eigen.value = eigen.value,
        eigen.fit = eigen.fit,
        threshold = threshold
      )
  }
  return(ret)
}