R/pval_sets.R

In LISTO: Performing Comprehensive Overlap Assessments

#' Calculate the p-value of intersection for two sets
#'
#' This function calculates the p-value of intersection for two sets.
#'
#' @details A thin wrapper around \code{stats::phyper}.
#'
#' @param a A character vector.
#' @param b A character vector.
#' @param n Set from which \code{a} and \code{b} are
#' selected.
#'
#' @return A numeric value in [0, 1] representing the p-value of intersection
#' for two sets.
#'
#' @examples
#' pvalSets2N(LETTERS[seq(4, 10)], LETTERS[seq(7, 15)], LETTERS)
#'
#' @export
#'
pvalSets2N <- function(a, b, n){
    na <- length(a)
    nb <- length(b)
    nShared <- length(intersect(a, b))
    nn <- length(n)
    return (phyper(nShared - 1,
                   na,
                   nn - na,
                   nb,
                   lower.tail=FALSE))
}

#' Compute the p-value of intersection of two subsets of sets M and N
#'
#' This function computes the p-value of intersection of two subsets
#' of sets M and N.
#'
#' @details A thin wrapper around \code{pvalCounts2MN}.
#'
#' @inheritParams pvalSets2N
#' @param m Set from which \code{a} is selected.
#' @param n Set from which \code{b} is selected.
#'
#' @return A numeric value in [0, 1] representing the p-value of intersection
#' of two subsets of sets M and N.
#'
#' @examples
#' pvalSets2MN(LETTERS[seq(4, 10)],
#' LETTERS[seq(7, 15)],
#' LETTERS[seq(19)],
#' LETTERS[seq(6, 26)])
#'
#' @export
#'
pvalSets2MN <- function(a, b, m, n){
    if (length(setdiff(a, m)))
        stop('`a` must be a subset of `m`.')
    if (length(setdiff(b, n)))
        stop('`b` must be a subset of `n`.')
    return(pvalCounts2MN(length(intersect(m, n)),
                         length(intersect(a, n)),
                         length(intersect(b, m)),
                         length(intersect(a, b))
    ))
}

#' Compute the p-value of intersection of three subsets
#'
#' This function computes the p-value of intersection of three subsets.
#'
#' @details A thin wrapper around \code{pvalCounts3N}.
#'
#' @inheritParams pvalSets2N
#' @param c A character vector.
#' @param n Set from which \code{a}, \code{b} and \code{c} are
#' selected.
#'
#' @return A numeric value in [0, 1] representing the p-value of intersection
#' of three subsets.
#'
#' @examples
#' pvalSets3N(LETTERS[seq(4, 10)],
#' LETTERS[seq(7, 15)],
#' LETTERS[seq(19)],
#' LETTERS)
#'
#' @export
#'
pvalSets3N <- function(a, b, c, n){
    if (length(setdiff(a, n)))
        stop('`a` must be a subset of `n`.')
    if (length(setdiff(b, n)))
        stop('`b` must be a subset of `n`.')
    if (length(setdiff(c, n)))
        stop('`c` must be a subset of `n`.')
    return(pvalCounts3N(length(a),
                        length(b),
                        length(c),
                        length(n),
                        length(Reduce(intersect, list(a, b, c)))))
}