R/RcppExports.R

In baruuum/btoolbox: random toolbox

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

#' Minkowski distance between rows of two matrics
#' 
#' @param x numeric matrix of dimension \code{n} times \code{k}
#' @param y numeric matrix of dimension \code{m} times \code{k}
#' @param p the order of the norm
#' @return matrix of dimension \code{n} times {m} where the \eqn{(i,j)}th element is the Minkowski distance of order \code{p} between the \eqn{i}th row of \code{x} and the \eqn{j}th row of {y}
#' @export
row_pdist <- function(x, y, p) {
    .Call(`_btoolbox_row_pdist`, x, y, p)
}

#' Fast Euclidean distance between rows of two matrics
#' 
#' @param x numeric matrix of dimension \code{n} times \code{k}
#' @param y numeric matrix of dimension \code{m} times \code{k}
#' @param squared boolean, if \code{true} the squared distance is returned
#' @details This calculation should be much faster than using \code{row_pdist}. However, it is numerically less stable. Use at own risk.
#' @return matrix of dimension \code{n} times {m} where the \eqn{(i,j)}th element is the Euclidean between the \eqn{i}th row of \code{x} and the \eqn{j}th row of {y}
#' @export
frow_euc_dist <- function(x, y, squared = FALSE) {
    .Call(`_btoolbox_frow_euc_dist`, x, y, squared)
}

#' Cosine similarity between rows of two matrices
#' 
#' @param x numeric matrix of dimension \code{n} times \code{k}
#' @param y numeric matrix of dimension \code{m} times \code{k}
#' @param return_log boolean, if \code{true} returns the log of the cosine similarity
#' @return matrix of dimension \code{n} times {m} where the \eqn{(i,j)}th element is the cosine similarity between the \eqn{i}th row of \code{x} and the \eqn{j}th row of {y}
#' @export
row_cos_sim <- function(x, y, return_log = FALSE) {
    .Call(`_btoolbox_row_cos_sim`, x, y, return_log)
}

#' Fast calculation of cosine similarity between rows of two matrices
#' 
#' @param x numeric matrix of dimension \code{n} times \code{k}
#' @param y numeric matrix of dimension \code{m} times \code{k}
#' @return matrix of dimension \code{n} times {m} where the \eqn{(i,j)}th element is the cosine similarity between the \eqn{i}th row of \code{x} and the \eqn{j}th row of {y}
#' @details this code divides \code{x * y.t()} by the row-wise norms of both \code{x} and \code{y}. If the norms get extremely small, the results might be numerically unstable. Use at own risk.
#' @export
frow_cos_sim <- function(x, y) {
    .Call(`_btoolbox_frow_cos_sim`, x, y)
}

#' Entropy
#' 
#' Calculates the entropy of a vector \code{x}
#' 
#' @param x numeric or integer object
#' @param na_rm boolean; if true, \code{NA} values are dropped 
#'     from the object before calculating the entropy. Otherwise,
#'     function throws an error when \code{x} contains any \code{NA}
#'     values
#' @return returns the entropy of \code{x}
#' @details the function will renormalize \code{x} to sum to one
.entropy <- function(x, na_rm = FALSE) {
    .Call(`_btoolbox_entropy_R`, x, na_rm)
}

#' Mutual information
#' 
#' Calculates the mutual information of the joint distribution between two
#' variables arranged in a cross table
#' 
#' @param x a numeric or integer matrix
#' @return returns the mutual information of rows and columns of \code{x}
.mutual_info <- function(x) {
    .Call(`_btoolbox_mutual_info`, x)
}

#' Expected mutual information for cross table
#' 
#' Calculates the expected value of the mutual information of the rows
#' and columns of a cross table under the hypergeometric model of randomness
#' 
#' @param x a integer matrix
#' @return returns the expected mutual information of the rows and columns
#' @references Vinh et al. 2010. "Information Theoretic Measures for Clusterings Comparison: Variants, Properties, Normalization and Correction for Chance," \emph{Journal of Machine Learning Research} 11: 2837-2854.
.emi_int <- function(x) {
    .Call(`_btoolbox_emi_int`, x)
}

.sample_index_logp <- function(N, lpvec) {
    .Call(`_btoolbox_lsample_arma`, N, lpvec)
}

#' Transform adjacency matrix to dyad-list
#' 
#' Transforms an adjacency matrix of dimension \code{n} times \code{n}
#' to a \code{choose(n, 2)} times \code{4} dyad-list.
#' 
#' @param x numeric or integer matrix
#' @param symmetric boolean indicating whether whether x is symmetric or not
#' @return dyad-list
#' @details The first column of the returned object contains identifiers
#' for the rows of the adjacency matrix \code{x}, \code{i}, 
#' the second column contains identifiers for the columns, \code{j},
#' the third column contains the tie from \code{i} to \code{j}, and the 
#' fourth column contains the tie from \code{j} to \code{i}.
.adj_to_dyad_C <- function(x, symmetric) {
    .Call(`_btoolbox_adj_to_dyad_C`, x, symmetric)
}

#' Symmetrize elements of Matrix
#' 
#' @param x_ matrix object
#' @param upper_to_lower if TRUE, copies the upper triangle
#'     (except the diagonals) into the lower triangle; otherwise, 
#'     copies the lower triangle into the upper.
#' @return symmetrized version of \code{x}
.symmetrize_square_matC <- function(x_, upper_to_lower) {
    .Call(`_btoolbox_symmetrize`, x_, upper_to_lower)
}

#' Sum within-partition weights of adjacency matrix
#' 
#' @param x adjacency matrix (may be weighted)
#' @param p integer vector indicating the partition membership of each node
#' @return returns the sum of the within-partition elements
#' @export
adj_sum_partition <- function(x, p) {
    .Call(`_btoolbox_adj_sum_partition`, x, p)
}

#' Tie reciprocity
#' 
#' Creates a vector of the same length as an edge list indicating whether a tie is reciprocated
#' 
#' @param x numeric or integer matrix
#' @return length \code{nrow(x)} vector of zeros (not reciprocated) and ones (reciprocated)
.is_reciproc <- function(x) {
    .Call(`_btoolbox_recip_arma`, x)
}

#' Generate Simulation-based CIs from Ordered Logit Model
#' 
#' @param mu estimated regression coefficients; regression parameters, followed by cutpoints
#' @param Sigma variance-covariance of mu
#' @param X matrix of values at which predictions should be made
#' @param level confidence level
#' @param n_sim number of simulation draws
#' @return simulation-based CIs
.sim_ci_ologit <- function(mu, Sigma, X, level, n_sim) {
    .Call(`_btoolbox_sim_ci_ologit`, mu, Sigma, X, level, n_sim)
}

#' Generate Simulation-based CIs from Multinomial Logit Model
#' 
#' @param mu estimated regression coefficients of the model; 
#'     matrix of dimension \code{L - 1} times \code{K}, 
#'     where \code{L} is the number of outcomes and \code{K} 
#'     is the number of predictors
#' @param Sigma variance-covariance of mu; matrix of dimensions
#'     \code{(L - 1) * K} times \code{(L - 1) * K}
#' @param X matrix of values at which predictions should be made
#' @param level confidence level
#' @param n_sim number of simulation draws
#' @return simulation-based CIs
.sim_ci_mlogit <- function(mu, Sigma, X, level, n_sim) {
    .Call(`_btoolbox_sim_ci_mlogit`, mu, Sigma, X, level, n_sim)
}

#' Update sparse affiliation network with new data
#' 
#' Updates a affiliation network stored in sparse format with new data of an ego-centric network
#' 
#' @param x the affiliation network to be updated; must be a \code{sparseMatrix} of the \code{Matrix} package
#' @param y an integer vector containing the indices of groups to be updated
#' @param update_diag boolean; if \code{true} updates the diagonal elements
#' @param normalize boolean; if \code{true} contribution of each ego to the elements in the affiliation are weighted by the inverse of ties ego holds
#' @return returns the updated affiliation matrix \code{x}.
#' @details Given \code{x}, the function takes new data on a set of affiliations connected to the same unit and updates the affiliation accordingly. If \code{y} contains the indices \code{1,6,12}, for example, the affiliation network is updated by adding one count to the entries \code{(1, 6), (6, 1), (1, 12), (12, 1), (6, 12), (12, 6)}.
.update_aff_mat <- function(x, y, update_diag = FALSE, normalize = FALSE) {
    .Call(`_btoolbox_update_aff_mat`, x, y, update_diag, normalize)
}

#' Update sparse affiliation network with new data in list format
#' 
#' Updates a affiliation network stored in sparse format with new data of a list of ego-centric network data
#' 
#' @param x the affiliation network to be updated; must be a \code{sparseMatrix} of the \code{Matrix} package
#' @param y a \code{Rcpp::List} object consisting of integer vectors with indices of groups to be updated
#' @param update_diag boolean; if \code{true} updates the diagonal elements
#' @param normalize boolean; if \code{true} contribution of each ego to the elements in the affiliation are weighted by the inverse of ties ego holds
#' @param verbose boolean; if \code{true} shows progress text
#' @return returns the updated affiliation matrix \code{x}.
.update_aff_list <- function(x, y, update_diag = FALSE, normalize = FALSE, verbose = FALSE) {
    .Call(`_btoolbox_update_aff_list`, x, y, update_diag, normalize, verbose)
}

#' Spectral Decomposition of Affiliation matrix
#' 
#' @param x sparse affiliation matrix
#' @param k number of (largest) eigenpairs to extract
#' @param check_dang check whether there are dangling nodes 
#' @param check_sym check whether \code{x} is symmetric
#' @param set_diag_zero if \code{true}, sets the diagonals of \code{x} to zero
#' @return returns the \code{k} largest eigenvalue-eigen vector pairs of the affiliation matrix
.adj_eigen <- function(x, k, check_dang, check_sym, set_diag_zero) {
    .Call(`_btoolbox_adj_eigen`, x, k, check_dang, check_sym, set_diag_zero)
}

#' Spectral Decomposition of Affiliation Matrix After Symmetric Normalization
#' 
#' @param x sparse affiliation matrix
#' @param k number of (largest) eigenpairs to extract
#' @param check_dang check whether there are dangling nodes 
#' @param check_sym check whether \code{x} is symmetric
#' @param set_diag_zero if \code{true}, sets the diagonals of \code{x} to zero
#' @return returns the \code{k} largest eigenvalue-eigen vector pairs of the normalized affiliation matrix
#' @details the normalized adjacency matrix is \eqn{D^{-1/2}AD^{-1/2}}, where \eqn{D^{-1/2}} is the square-root of the diagonal matrix containing the degrees of \eqn{A}.
.adj_eigen_norm <- function(x, k, check_dang, check_sym, set_diag_zero) {
    .Call(`_btoolbox_adj_eigen_norm`, x, k, check_dang, check_sym, set_diag_zero)
}

#' Spectral Decomposition of (Left) Normalized Adjacency Matrix
#'
#' @param x sparse affiliation matrix
#' @param k number of (largest) eigenpairs to extract
#' @param check_dang check whether there are dangling nodes
#' @param check_sym check whether \code{x} is symmetric
#' @param set_diag_zero if \code{true}, sets the diagonals of \code{x} to zero
#' @return returns the \code{k} (largest) eigenvalue-eigen vector pairs of the (left) normalized adjacency matrix
#' @details the (left) normalized adjacency matrix is defined as \eqn{A' = D^{-1}A}, where \eqn{D} is the diagonal matrix containing the degrees of \eqn{A}.
.adj_eigen_left_norm <- function(x, k, check_dang, check_sym, set_diag_zero) {
    .Call(`_btoolbox_adj_eigen_left_norm`, x, k, check_dang, check_sym, set_diag_zero)
}

#' Spectral Decomposition of Laplacian Matrix Associated with Affiliation Network
#' 
#' @param x sparse affiliation matrix
#' @param k number of (smallest) eigenpairs to extract
#' @param check_dang check whether there are dangling nodes 
#' @param check_sym check whether \code{x} is symmetric
#' @param set_diag_zero if \code{true}, sets the diagonals of \code{x} to zero
#' @return returns the \code{k} smallest eigenvalue-eigen vector pairs of Laplacian
.lap_eigen <- function(x, k, check_dang, check_sym, set_diag_zero) {
    .Call(`_btoolbox_lap_eigen`, x, k, check_dang, check_sym, set_diag_zero)
}

#' Components of \code{sparse} adjacency matrix
#' 
#' Determines the components of a graph from a \code{sparse} (possibly weighted) adjacency matrix using depth-first search
#' 
#' @param x, a \code{sparse} adjacency matrix
#' @returns a integer vector with component membership of each node
#' @details indices of the component vector starts from 1 and not 0.
components_sp <- function(x) {
    .Call(`_btoolbox_components_sp`, x)
}

#' Check whether graph is connected using the associated \code{sparse} adjacency matrix
#' 
#' @param x a \code{sparse} adjacency matrix
#' @returns \code{true} if graph is connected, \code{false} otherwise
is_connected_sp <- function(x) {
    .Call(`_btoolbox_is_connected_sp`, x)
}

#' Sum within-partition weights of sparse adjacency matrix
#' 
#' @param x adjacency matrix (may be weighted)
#' @param p integer vector indicating the partition membership of each node
#' @return returns the sum of the within-partition elements
#' @export
adj_sum_partition_sp <- function(x, p) {
    .Call(`_btoolbox_adj_sum_partition_sp`, x, p)
}

#' Unit test for btb::arm::quantile 
#' 
#' @param N number of quantiles to test
#' @param prec precision
#' @return returns \code{true} if test passes
.unit_test_arm_quantile <- function(N = 10L, prec = 1e-8) {
    .Call(`_btoolbox_unit_test_arm_quantile`, N, prec)
}

#' Unit test for \code{softmax} and \code{log_softmax} code
#' 
#' @param N length of vector to test
#' @param prec precision for testing equality
#' @return returns \code{true} if all tests pass
.unit_test_arm_softmax <- function(N = 30L, prec = 1e-8) {
    .Call(`_btoolbox_unit_test_arm_softmax`, N, prec)
}

#' Unit test for btb::arm::mvrnorm 
#' 
#' Usese random draws and compares result with quantiles of chi-squared distribution
#' 
#' @param N number of draws to use in test
#' @param K dimension of draws
#' @param prec precision to test for equality
#' @return returns \code{true} if test passes
.unit_test_arm_rmvnorm <- function(N = 1e6L, K = 4L, prec = 0.005) {
    .Call(`_btoolbox_unit_test_arm_rmvnorm`, N, K, prec)
}

#' Unit test for btb::arm::mvrnorm (single draws)
#' 
#' Usese random draws and compares result with quantiles of chi-squared distribution
#' 
#' @param N number of draws to use in test
#' @param K dimension of draws
#' @param prec precision to test for equality
#' @details tested separately as code is different
#' @return returns \code{true} if test passes
.unit_test_arm_rmvnorm_1 <- function(N = 1e6L, K = 4L, prec = 0.005) {
    .Call(`_btoolbox_unit_test_arm_rmvnorm_1`, N, K, prec)
}

#' Logarithm of cumulative sum of exponentials
#' 
#' Stable calculation of \code{log(cumsum(exp(x)))} of a numeric 
#' or integer object \code{x}
#' 
#' @param x numeric or integer object in either vector or matrix form
#' @return the logarithm of the cumulative sum of exponentials in \code{x}
#' @details if \code{x} is a matrix, accumulation is done by column. 
#'     If \code{x} is an array of dimension \eqn{r \times c \times d}, 
#'     accumulation is along the columns of each submatrix of dimension
#'     \eqn{r \times c}.
#' @export 
log_accu_exp <- function(x) {
    .Call(`_btoolbox_log_accu_exp_R`, x)
}

#' Running average over numeric vector
#' 
#' Calculates the running average (moving average) over a numeric vector
#' 
#' @param x numeric vector
#' @param w size of window
#' @return running average of vector \code{x} with window \code{w}
.run_mean <- function(x, w = 1L) {
    .Call(`_btoolbox_run_mean_R`, x, w)
}

#' Medians of columns of matrix
#' 
#' @param x a numeric matrix
#' @returns a vector with the medians of \code{x}'s columns
#' @export
colMedians <- function(x) {
    .Call(`_btoolbox_colMedians`, x)
}

#' Medians of rows of matrix
#' 
#' @param x a numeric matrix
#' @returns a vector with the medians of \code{x}'s rows
#' @export
rowMedians <- function(x) {
    .Call(`_btoolbox_rowMedians`, x)
}

#' Double-center a matrix
#' 
#' Centers a matrix so that both the rows and the columns sum to zero
#' 
#' @param x a numeric matrix
#' @return returns the doubly-centered version of \code{x}
#' @export
double_center <- function(x) {
    .Call(`_btoolbox_double_center`, x)
}

#' Create agreement matrix
#' 
#' Creates an agreement matrix by comparing either the row or the columns of a matrix
#' 
#' @param x an integer matrix
#' @param dim dimension across which agreement should be calculated (0 = columns, 1 = rows)
#' @param missing integer indicating missing value (defaults to 99)
#' @return returns the agreement matrix
#' @details Let \eqn{X} be a \eqn{n\times k} matrix. If comparison across rows is demended (i.e., \code{dim = "row"}, the function returns a \eqn{n\times n} matrix where the \eqn{(i,j)}th element is the number of columns on which the \eqn{i}th and the \eqn{j}th row agree by having the same value.
.agreement_mat <- function(x, dim, missing = 999999L) {
    .Call(`_btoolbox_agreement_mat`, x, dim, missing)
}