R/CellScabbard-class.R

In BrainSABER: Brain Span Atlas in Biobase Expressionset R toolset

#' The CellScabbard class
#'
#' The main class used by the \pkg{BrainSABER} package to hold single cell 
#' expression data, relevant gene data, and similarity matrices.
#' CellScabbard extends the 
#' [SummarizedExperiment::SummarizedExperiment-class] class.
#'
#' This class is initialized from a matrix of gene expression values and
#' associated metadata.  Methods that operate on CellScabbard objects
#' comprise the BrainSABER workflow.
#'
#' @field dataSetId A character vector of length 1, containing the column name
#'     of the user's data used to trim the data to match AIBSARNA.
#' @field AIBSARNAid A character vector of length 1, containing the column name
#'     of AIBSARNA used to trim AIBSARNA to match the user's data
#' @field relevantGenes A [SummarizedExperiment::SummarizedExperiment-class] 
#'     containing a subset of data from AIBSARNA. Generated by the 
#'     \pkg{BrainSABER} workflow.
#' @field similarityScores  A \code{data.frame} containing similarity
#'     scores. Generated by the \pkg{BrainSABER} workflow.
#' @field similarityDFs A \code{list} containing similarity data frames with
#'     age, structure, and similarity scores sorted in decreasing order.
#'     Generated by the \pkg{BrainSABER} workflow.
#' @field similarityMatrices A [SummarizedExperiment::Assays-class] object 
#'     containing similarity matrices, with identical dimensions, for each 
#'     sample in phenoData. Generated by the \pkg{BrainSABER} workflow.
#' @field UNDmatrices A [SummarizedExperiment::Assays-class] object containing
#'     identical-dimension UND matrices for each sample in phenoData.
#'     Generated by the \pkg{BrainSABER} workflow.
#' @name CellScabbard
#' @rdname CellScabbard
#' @aliases CellScabbard-class
#' @exportClass CellScabbard
#' @import SummarizedExperiment
.CellScabbard <- 
    setClass( "CellScabbard",
            contains="SummarizedExperiment",
            slots = representation(
                dataSetId = "character",
                AIBSARNAid = "character",
                relevantGenes = "SummarizedExperiment",
                similarityScores = "data.frame",
                similarityDFs = "list",
                similarityMatrices = "SimpleList",
                UNDmatrices = "SimpleList"
            )
    )

#' Creates a new CellScabbard object.
#'
#' @param exprsData expression data matrix for an experiment
#' @param phenoData a data frame containing attributes of individual
#'     cells
#' @param featureData a data frame containing attributes of features
#'     (e.g. genes)
#' @param AIBSARNA an instance of the AIBSARNA dataset, built using the 
#'     \code{buildAIBSARNA()} function
#' @param autoTrim If TRUE (default), automatically trim user data to match
#'     AIBSARNA using the column names of AIBSARNA and featureData (or rownames
#'     of exprsData, if featureData is not supplied) which produce the most 
#'     matched identifiers.  Also automatically fills the relevantGenes slot,
#'     using the same column names.  The column names are stored in the 
#'     dataSetId and AIBSARNAid slots.
#' @return a new CellScabbard object
#' @import SummarizedExperiment
#' @importFrom data.table CJ
#' @examples
#' # construct example data set
#' AIBSARNA <- buildAIBSARNA(mini = TRUE)
#'
#' # get a random sample of 3 genes
#' totalGenes <- nrow(AIBSARNA)
#' gene_idx <- sample.int(totalGenes, 3)
#' sample_idx <- c(1,3,5)
#' 
#' # Subset AIBSARNA
#' exprs <- assay(AIBSARNA)[gene_idx, sample_idx]
#' fd <- rowData(AIBSARNA)[gene_idx, ]
#' pd <- colData(AIBSARNA)[sample_idx, ]
#' 
#' # construct a CellScabbard data set
#' myGenes <- CellScabbard(exprsData = exprs, phenoData = pd, featureData = fd, 
#'                         AIBSARNA = AIBSARNA, autoTrim = TRUE)
#' @export
#'
CellScabbard <- function( exprsData,
                            phenoData = NULL,
                            featureData = NULL,
                            AIBSARNA = NULL,
                            autoTrim = TRUE)
{
    if (!is(exprsData, "matrix")){
        stop("Error: argument exprsData must be a matrix")
    }
    se <- SummarizedExperiment(assays = list(exprs = exprsData),
                               rowData = featureData,
                               colData = phenoData)
    if(autoTrim) {
        # find optimal id pairing
        df <- as.data.frame(CJ(
            dataSetId = colnames(as.data.frame(rowData(se))),
            AIBSARNAid = colnames(as.data.frame(rowData(AIBSARNA)))
        ))
        scores <- rep_len(0, length.out = length(df$dataSetId))
        df <- cbind(df, scores)
        dfidx <- 0
        # get the lengths of results of getExternalVector to see how many genes
        # match for each combination
        for (i in colnames(rowData(se))) {
            for (j in colnames(rowData(AIBSARNA))) {
                if (j != "row_num") {
                    df$scores[dfidx] <-
                        length(
                            getExternalVector(
                                dataSet = se,
                                index = 1,
                                AIBSARNA = AIBSARNA,
                                dataSetId = i,
                                AIBSARNAid = j
                            )
                        )
                }
            }
        }
        df <- df[order(df$scores, decreasing = TRUE),]
        relgenes <-
            getRelevantGenes(
                data = se,
                dataSetId = df$dataSetId[1],
                AIBSARNA = AIBSARNA,
                AIBSARNAid = df$AIBSARNAid[1]
            )
        trimSe <-
            getTrimmedExternalSet(
                dataSet = se,
                dataSetId = df$dataSetId[1],
                AIBSARNA = AIBSARNA,
                AIBSARNAid = df$AIBSARNAid[1]
            )
        
        .CellScabbard(trimSe, dataSetId = df$dataSetId[1],
                      AIBSARNAid = df$AIBSARNAid[1], relevantGenes = relgenes)
    } else {
        .CellScabbard(se)
    }
}