pMatrix.R

#' @title Compute Partial TAI or TDI Values 
#' @description This function computes the partial \code{\link{TAI}} or \code{\link{TDI}} 
#' values for each single gene in a PhyloExpressionSet or DivergenceExpressionSet object.
#'
#' In detail, each gene gets a \emph{TAI contribution profile} or \emph{TDI contribution profile}. 
#'
#' \deqn{TAI_{is} = f_{is} * ps_i}
#'
#' or
#'
#' \deqn{TDI_{is} = f_{is} * ps_i}
#'
#' where \eqn{TAI_{is}} or \eqn{TDI_{is}} is the partial TAI or TDI value of gene i, 
#' \eqn{f_{is} = e_{is} / \sum e_{is}} and \eqn{ps_i} is the phylostratum or divergence-stratum of gene i.
#' @param ExpressionSet a standard PhyloExpressionSet or DivergenceExpressionSet object.
#' @details The partial TAI or TDI matrix can be used to perform different cluster analyses
#' and also gives an overall impression of the contribution of each gene to the global \code{\link{TAI}} or \code{\link{TDI}} pattern.
#' @return a numeric matrix storing the partial TAI or TDI values for each gene in the 
#' corresponding PhyloExpressionSet or DivergenceExpressionSet. 
#' @references 
#' Domazet-Loso T and Tautz D. 2010. "A phylogenetically based transcriptome age index mirrors ontogenetic divergence patterns". Nature (468): 815-818.
#' @author Hajk-Georg Drost
#' @examples
#' 
#' 
#' # read standard phylotranscriptomics data
#' data(PhyloExpressionSetExample)
#' data(DivergenceExpressionSetExample)
#'
#' # example PhyloExpressionSet
#' PTM_ps <- pMatrix(PhyloExpressionSetExample)
#'
#' # example DivergenceExpressionSet
#' PTM_ds <- pMatrix(DivergenceExpressionSetExample)
#'
#' # boxplot of the pMatrix
#' boxplot(pMatrix(PhyloExpressionSetExample),outline = FALSE)
#' 
#' # boxplot of the pMatrix using log2 transformed expression levels
#' boxplot(pMatrix(tf(PhyloExpressionSetExample,log2)))
#'  
#' 
#' @export

pMatrix <- function(ExpressionSet)
{
        
        is.ExpressionSet(ExpressionSet)
        
        nCols <- dim(ExpressionSet)[2]
        nRows <- dim(ExpressionSet)[1]
        pTAIMatrix <- matrix(nrow = nRows,ncol = nCols - 2)
        
        pTAIMatrix <- cpp_pMatrix(as.matrix(dplyr::select(ExpressionSet, 3:ncol(ExpressionSet))), as.vector(unlist(dplyr::select(ExpressionSet, 1))))
        
        colnames(pTAIMatrix) <- names(ExpressionSet)[3:nCols]
        rownames(pTAIMatrix) <- unlist(dplyr::select(ExpressionSet, 2))
        
        return(pTAIMatrix)
        
}