R/RcppExports.R

In baruuum/relabelKL: Relabeling MCMC Output

# Generated by using Rcpp::compileAttributes() -> do not edit by hand
# Generator token: 10BE3573-1514-4C36-9D1C-5A225CD40393

#' Relabel membership vector by minimizing KL-algorithm (log-scale)
#' 
#' Relabels the membership vectors of a mixed membership model or 
#' mixed membership stochastic blockmodel, using the KL-algorithm
#' proposed by Stephens (2000).
#' 
#' @param lphi cube of length \code{S}, each element of which is a 
#'     matrix of dimension N times K, where N is the number of individuals 
#'     and K is the number of extreme types (or classes).
#' @param renormalize if \code{true}, renormalizes the rows of each slice of \code{lphi}
#' @param maxit the number of maximum iterations to run, defaults to 100.
#' @param nthreads number of threads to use in parallel processing
#' @param verbose if TRUE, number of iterations and corresponding KL-distance 
#'     values are printed. 
#' @return The function returns a Rcpp::List of three elements. 
#'     1) A cube, \code{permuted}, of the same dimensions as \code{phi} but 
#'     with the labels permuted; 2) \code{perms} is a \code{S} times \code{K} 
#'     matrix containing the permutations necessary to produce \code{permuted} 
#'     from \code{phi} (i.e., the mapping from \code{phi} to \code{permuted});
#'     and 3) the number of iterations run.
#' @details OpenMP is enabled if available. Due to overhead, the inner-most
#'     loop is parallelized only if the number of latent classes/types
#'     is larger than 3.
relabel_kl_log <- function(lphi, renormalize = FALSE, maxit = 100L, nthreads = 0L, verbose = TRUE) {
    .Call('_relabelKL_relabel_kl_log', PACKAGE = 'relabelKL', lphi, renormalize, maxit, nthreads, verbose)
}

#' Relabel membership vector by minimizing KL-algorithm to true labels
#' 
#' Relabels the membership vectors of a mixed membership model or 
#' mixed membership stochastic blockmodel, by minimizing the KL-divergence
#' to a priori known true labels, where probabilities are entered on the
#' log-scale.
#' 
#' @param lphi cube of length \code{S}, each slice of which is a matrix of 
#'   dimension \code{N} times \code{K}, and where \code{N} is the number of 
#'   individuals and K is the number of extreme types (or classes). 
#'   Elements of \code{lphi} should be log-probabilities.
#' @param lphi_true a \code{N} times \code{K} matrix containing the "true"
#'   values of latent-class/mixed-membership probabilities on the log-scale
#' @param renormalize whether to renormalize the rows of \code{lphi}
#' @param nthreads number of threads to use if OPENMP is enabled
#' @param verbose if true, KL-divergence from true labels is calculated
#'   and printed before and after relabeling
#' @return Returns a Rcpp::List with two elements: 1) A arma::cube, 
#'   \code{permuted}, of the same dimensions as \code{phi} but 
#'   with the labels permuted; 2) \code{perms} is a \code{S} times \code{K} 
#'   matrix containing the permutations necessary to produce \code{permuted} 
#'   from \code{phi} (i.e., the mapping from \code{phi} to \code{permuted})
#' @details OpenMP is enabled if available. Due to overhead, the inner-most
#'     loop is parallelized only if the number of latent classes/types
#'     is larger than 3.
relabel_true_log <- function(lphi, lphi_true, renormalize = FALSE, nthreads = 0L, verbose = FALSE) {
    .Call('_relabelKL_relabel_true_log', PACKAGE = 'relabelKL', lphi, lphi_true, renormalize, nthreads, verbose)
}

#' Log of the sum of exponential
#'
#' @param x a vector
#' @return log of the sum of exponentiated elements in \code{x}
lse <- function(x) {
    .Call('_relabelKL_lse', PACKAGE = 'relabelKL', x)
}

#' Logarithm of sum of exponentials 
#'
#' @param x any object that allows iterators
#' @return returns the log of the sum of exponentiated elements of \code{x}
NULL

#' KL Divergence between two distributions (log-scale)
#'
#' Calculates the KL-divergence of the target to the true distribution, where 
#' both distributions are entered on the logarithm scale.
#'
#' @param lp the "true" distribution on the log-scale (has to be an arma object)
#' @param lq the "target" distribution on the log-scale (has to be an arma object)
#' @return Returns the KL-divergence of \code{lq} from \code{lp}
NULL

#' Generate permutations
#'
#' Generates a matrix all possible permutations of N objects
#'
#' @param N integer of number of elements
#' @return matrix of all possible permutations of length \code{N}.
#'         Returns a matrix of dimension n! times \code{N}
NULL

#' Permute vector
#'
#' Permutes a row or column vector in a specified order
#' 
#' @param x vector to permute
#' @param order new order (indices have to start from 0)
#' @return \code{x} permuted in order \code{order}
NULL

#' Permute rows or columns of matrix
#'
#' Permutes the rows or the columns of a matrix in a specified order
#' 
#' @param x matrix to permute
#' @param order new order (indices have to start from 0)
#' @param dim if 0, columns are permuted; otherwise, rows are permuted
#' @return \code{x} permuted in order \code{order}
NULL