R/RcppExports.R

In neuroconductor-releases/LESYMAP: Lesion to Symptom Mapping in R

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

#' @title Fast Brunner-Munzel tests (v1)
#'
#' @description
#' Takes a binary matrix of voxels and a vector of behavior
#' and runs Brunner-Munzel tests on each voxel.
#' This is a fast function, but may produce infinite values
#' for perfectly separated group. Use BMfast2 which avoids
#' this problem.
#'
#' @param X binary matrix ov voxlels (columns) for all
#' subjects (rows)
#' @param y vector of behavioral scores.
#'
#' @return List with two vectors:
#' - statistic - BM values
#' - dfbm - degrees of freedom
#'
#' @author Dorian Pustina
#'
#' /@export
BMfast <- function(X, y) {
    .Call('_LESYMAP_BMfast', PACKAGE = 'LESYMAP', X, y)
}

#' @title Fast Brunner-Munzel tests (v2)
#'
#' @description
#' Takes a binary matrix of voxels and a vector of behavior
#' and runs Brunner-Munzel tests on each voxel.
#' This is a fast function that corrects for infinite values
#' with a similar approach as the nparcomp package.
#'
#' @param X binary matrix of voxels (columns) for all
#' subjects (rows)
#' @param y vector of behavioral scores.
#' @param computeDOF (true) chooses whether to compute degrees
#' of freedom. Set to false to save time during permutations.
#'
#' @return List with two vectors:
#' \itemize{
#' \item\code{statistic} - BM values
#' \item\code{dfbm} - degrees of freedom
#' }
#'
#' @examples
#' set.seed(1234)
#' lesmat = matrix(rbinom(40,1,0.2), ncol=2)
#' set.seed(1234)
#' behavior = rnorm(20)
#' test = LESYMAP::BMfast2(lesmat, behavior)
#' test$statistic[,1] # -2.0571825 -0.8259754
#' test$dfbm[,1] # 16.927348  7.563432
#'
#' @author Dorian Pustina
#'
#' @export
BMfast2 <- function(X, y, computeDOF = TRUE) {
    .Call('_LESYMAP_BMfast2', PACKAGE = 'LESYMAP', X, y, computeDOF)
}

#' @title Fast Brunner-Munzel tests (v2) - dual matrix
#'
#' @description
#' Takes a binary matrix of voxels and a matrix of
#' behavioral scores, one for each voxel, then runs Brunner-Munzel
#' tests on each voxel with the repective behavior column.
#' Function mostly used to estimate score biases with
#' full brain simulations.
#' This is a fast function that corrects for infinite values
#' with a similar approach as the nparcomp package.
#'
#' @param X binary matrix of voxels (columns) for all
#' subjects (rows)
#' @param Y matrix of voxel specific behavioral scores.
#' Must be of same dimensions as X.
#' @param computeDOF (true) chooses whether to compute degrees
#' of freedom. Set to false to save time during permutations.
#'
#' @return List with two vectors:
#' \itemize{
#' \item\code{statistic} - BM values
#' \item\code{dfbm} - degrees of freedom
#' }
#'
#' @examples
#' set.seed(1234)
#' lesmat = matrix(rbinom(60,1,0.2), ncol=2)
#' set.seed(12345)
#' behavior = cbind( rnorm(30) )
#' set.seed(123456)
#' behavior = cbind ( behavior, rnorm(30) )
#' test = LESYMAP::BMfast2_dualmatrix(lesmat, behavior)
#' test$statistic[,1] # -3.6804016  0.6097458
#'
#' @author Dorian Pustina
#'
#' @export
BMfast2_dualmatrix <- function(X, Y, computeDOF = FALSE) {
    .Call('_LESYMAP_BMfast2_dualmatrix', PACKAGE = 'LESYMAP', X, Y, computeDOF)
}

#' @title Fast Brunner-Munzel tests (v2) with permutations
#'
#' @description
#' Takes a binary matrix of voxels and a vector of behavior
#' and runs Brunner-Munzel tests on each voxel.
#' This is a fast function that corrects for infinite values
#' with a similar approach as the nparcomp package.
#' It calculates p-values by running permutations of each
#' voxel and using the ratio of times the real BM score
#' exceeds the permuted BM score.
#'
#'
#' @param X binary matrix ov voxlels (columns) for all
#' subjects (rows)
#' @param y vector of behavioral scores.
#' @param computeDOF (default true) chooses whether to compute
#' degrees of freedom. Set to false to save time during permutations.
#' @param npermBM (default 20000) number of permutations to run at each
#' voxel
#' @param alternative (default 1) integer to select the tail of
#' pvalues. 1-greater, 2-less, 3-two.sided
#'
#' @return List with these objects:
#' \itemize{
#' \item\code{statistic} - BM values
#' \item\code{dfbm} - degrees of freedom
#' \item\code{pvalue} - permutation-based probability value
#' }
#'
#' @examples
#' set.seed(1234)
#' lesmat = matrix(rbinom(40,1,0.2), ncol=2)
#' set.seed(1234)
#' behavior = rnorm(20)
#' test = LESYMAP::BMperm(lesmat, behavior, alternative=3)
#' test$statistic[,1] # -2.0571825 -0.8259754
#' test$dfbm[,1] # 16.927348  7.563432
#' test$pvalue[,1] # 0.1427929 0.4102795
#'
#' @author Dorian Pustina
#'
#' @export
BMperm <- function(X, y, computeDOF = TRUE, npermBM = 20000L, alternative = 1L) {
    .Call('_LESYMAP_BMperm', PACKAGE = 'LESYMAP', X, y, computeDOF, npermBM, alternative)
}

#' @title TTfast
#'
#' @description
#' Compiled fast t-tests on matrices. Takes a binary matrix
#' X with zero and non-zero values, and a matrix Y of
#' continuous values. Computes the t-test on each Y column
#' using the respective X column to define the two groups.
#' If Y is a matrix with one column, that column is used
#' to test with grouping derived from every column in X.
#' This function is used in LESYMAP with a binarized X
#' matrix derived from lesioned voxels in the brain.
#'
#' @param X binary matrix of voxels (columns) for all
#' subjects (rows).
#' @param Y matrix of behavioral scores of same size as X
#' or a matrix with a single column.
#' @param computeDOF (default=true) chooses whether to compute
#' degrees of freedom. Set to false to save time during
#' permutations.
#' @param varEqual (default=true) chooses whether to compute
#' Student t-scores (true) or Welch d-scores (false). The
#' only difference is the assumption on variance which for
#' t-scores must be satisfied. This assumption is often
#' violated in some voxels, and the use of Welch
#' (varEqual=false) is recommended for more accurate results.
#'
#' @return List with two vectors:
#' \itemize{
#' \item\code{statistic} - Student T or Welch D
#' \item\code{df} - degrees of freedom
#' }
#'
#' @examples
#' set.seed(1234)
#' lesmat = matrix(rbinom(60,1,0.2), ncol=2)
#' set.seed(12345)
#' behavior = cbind( rnorm(30) )
#' set.seed(123456)
#' behavior = cbind ( behavior, rnorm(30) )
#' test = LESYMAP::TTfast(lesmat, behavior)
#' test$statistic[,1] # -2.359317  1.040766
#'
#' @author Dorian Pustina
#'
#' @export
TTfast <- function(X, Y, computeDOF = TRUE, varEqual = TRUE) {
    .Call('_LESYMAP_TTfast', PACKAGE = 'LESYMAP', X, Y, computeDOF, varEqual)
}

#' @title Fast linear regressions
#'
#' @description
#' Takes a matrix of voxels and a vector of behavior
#' and runs fast regressions for each voxel. Covariates
#' can be defined (i.e. age) to find the effect of each
#' voxel on behavior within the context of other predictive
#' factors.
#'
#' @param X matrix of voxlels (columns) for all
#' subjects (rows).
#' @param y vector of behavioral scores.
#' @param covariates matrix with one or more columns.
#' Must be of same length as behavior. This variable
#' should always be set, and the next argument can tell
#' if covariates should be used or not.
#' @param hascovar logical to tell whether covariates
#' should be used.
#'
#' @return List with:
#' \itemize{
#' \item\code{statistic} - regression t-score
#' \item\code{n} - number of subjects
#' \item\code{kxfm} - degrees of freedom.
#' }
#'
#' @examples
#' set.seed(1234)
#' lesmat = matrix(rbinom(40,1,0.2), ncol=2)
#' set.seed(1234)
#' behavior = rnorm(20)
#' test = LESYMAP::regresfast(lesmat, behavior, as.matrix(behavior), hascovar=FALSE)
#' test$statistic[,1] # 0.6915683 1.1434760
#' test$kxmat # 2
#'
#' @author Dorian Pustina
#'
#' @export
regresfast <- function(X, y, covariates, hascovar = FALSE) {
    .Call('_LESYMAP_regresfast', PACKAGE = 'LESYMAP', X, y, covariates, hascovar)
}