R/constructors.R

In ilyessr/conclus: ScRNA-seq Workflow CONCLUS - From CONsensus CLUSters To A Meaningful CONCLUSion

#' @description
#' Constructor of the class scRNAseq.
#'
#' @rdname constructors
#' @name constructors
#' @title constructors
NULL

#' singlecellRNAseq
#'
#' @usage
#' singlecellRNAseq(experimentName, countMatrix, species, outputDirectory,
#' tSNElist=list(new("Tsne")), dbscanlist=list(new("Dbscan")),
#' cellSimMat= matrix(nrow = 1, ncol = 1, dimnames = list("c1", "c1"),
#' data = 1), clustSimMat=matrix(nrow = 1, ncol = 1, dimnames = list("1", "1"),
#' data = 1), clustSimOrdered=factor(1), markgenlist=list(data.frame(
#' Gene = c("gene1"), mean_log10_fdr = c(NA), n_05 = c(NA), score = c(NA))),
#' clustMark=data.frame(geneName="gene1", clusters=NA), genesInf = data.frame(
#' uniprot_gn_symbol=c("symbol"), clusters="1", external_gene_name="gene",
#' go_id="GO1,GO2", mgi_description="description",
#' entrezgene_description="descr", gene_biotype="gene", chromosome_name="1",
#' Symbol="symbol", ensembl_gene_id="ENS", mgi_id="MGI", entrezgene_id="1",
#' uniprot_gn_id="ID"))
#' 
#' @param experimentName Character string representing the name of the
#' experiment.
#' @param countMatrix An integer matrix representing the raw count matrix with
#' reads or unique molecular identifiers (UMIs).
#' @param species Character string representing the species of interest.
#' Currently limited to "mouse" and "human". Other organisms can be added on
#' demand.
#' @param outputDirectory A character string of the path to the root output
#' folder.
#' @param tSNElist List of 'Tsne' objects representing the different tSNE
#' coordinates generated by CONCLUS.
#' @param dbscanlist List of 'Dbscan' objects representing the different
#' Dbscan clustering generated by CONCLUS.
#' @param cellSimMat A numeric Matrix defining how many times two cells have
#' been associated to the same cluster across the 84 solutions (by default) of
#' clustering.
#' @param clustSimMat A numeric matrix comparing the robustness of the consensus
#' clusters.
#' @param clustSimOrdered A factor representing the clusters ordered by
#' similarity.
#' @param markgenlist List of data.frames. Each data frame contains the ranked
#' genes of one cluster.
#' @param clustMark A data frame containing the top 10 (by default)
#' marker genes of each clusters.
#' @param genesInf A data frame containing informations of the markers
#' genes for each clusters.
#' 
#' @return Object of class scRNAseq
#'
#' @rdname constructors
#'
#' @examples
#' experimentName <- "Bergiers"
#' outputDirectory <- "YourOutputDirectory"
#'
#' ## Load the count matrix
#' countmatrixPath <- system.file("extdata/countMatrix.tsv", package="conclus")
#' countMatrix <- loadDataOrMatrix(file=countmatrixPath, type="countMatrix", 
#'                                 ignoreCellNumber=TRUE)
#'
#' ## Load the coldata
#' coldataPath <- system.file("extdata/colData.tsv", package="conclus")
#' columnsMetaData <- loadDataOrMatrix(file=coldataPath, type="coldata",
#'                                     columnID="cell_ID")
#'
#' ## Create the initial object
#' scr <- singlecellRNAseq(experimentName = experimentName,
#'                 countMatrix     = countMatrix,
#'                 species         = "mouse",
#'                 outputDirectory = outputDirectory)
#'
#' @aliases singlecellRNAseq
#' @seealso scRNAseq-class
#' @export singlecellRNAseq
singlecellRNAseq <- function(experimentName, countMatrix, species,
        outputDirectory, tSNElist=list(new("Tsne")),
        dbscanlist=list(new("Dbscan")), cellSimMat= matrix(nrow = 1, ncol = 1,
                dimnames = list("c1", "c1"), data = 1),
        clustSimMat=matrix(nrow = 1, ncol = 1, dimnames = list("1", "1"),
                data = 1),
        clustSimOrdered=factor(1),
        markgenlist=list(data.frame(Gene = c("gene1"), mean_log10_fdr = c(NA),
                        n_05 = c(NA), score = c(NA))),
        clustMark=data.frame(geneName="gene1", clusters=NA),
        genesInf = data.frame(uniprot_gn_symbol=c("symbol"), clusters="1",
                external_gene_name="gene", go_id="GO1,GO2",
                mgi_description="description", entrezgene_description="descr",
                gene_biotype="gene", chromosome_name="1", Symbol="symbol",
                ensembl_gene_id="ENS", mgi_id="MGI", entrezgene_id="1",
                uniprot_gn_id="ID")){


    new("scRNAseq",
            experimentName=experimentName,
            countMatrix=countMatrix,
            species=species,
            outputDirectory=outputDirectory,
            tSNEList=tSNElist,
            dbscanList=dbscanlist,
            cellsSimilarityMatrix=cellSimMat,
            clustersSimilarityMatrix=clustSimMat,
            clustersSimiliratyOrdered=clustSimOrdered,
            markerGenesList=markgenlist,
            topMarkers=clustMark,
            genesInfos=genesInf)
}


#' TsneCluster
#'
#' @usage
#' TsneCluster(name, pc, perplexity, coordinates)
#'
#' @param name A 'character' string representing the name of the tSNE
#' coordinates.
#' @param pc A 'numeric' value representing the number of principal components
#' used by CONCLUS to perfom a PCA before calculating the tSNE.
#' @param perplexity  A 'numeric' vector. Default: c(30, 40)
#' @param coordinates A 'numeric' matrix that contains the coordinates
#' of one tSNE solution.
#'
#' @return Object of class Tsne
#'
#' @rdname constructors
#'
#' @examples
#' mat <- matrix(seq_len(20), ncol=2)
#' colnames(mat) <- c("X", "Y")
#' TsneCluster(name = "test", pc = 30, perplexity = 4,
#' coordinates = mat)
#'
#' @aliases TsneCluster
#' @seealso Tsne-class
#' @export TsneCluster
TsneCluster <- function(name, pc, perplexity, coordinates){

    new("Tsne",
            name=name,
            pc=pc,
            perplexity=perplexity,
            coordinates=coordinates)
}


#' DbscanCluster
#'
#' @usage
#' DbscanCluster(name, epsilon, minPoints, clustering)
#'
#' @param name A 'character' string representing the name of the Dbscan
#' clustering.
#' @param epsilon A 'numeric' vector. The epsilon is the distance to consider
#' two points belonging to the same cluster. Default = c(1.3, 1.4, 1.5)
#' @param minPoints A 'numeric' value. The minPoints is the minimum number
#' of points to construct a cluster.
#' @param clustering A 'matrix' that contains the result of one DBSCAN
#' clustering solution.
#'
#' @return Object of class Dbscan
#'
#' @rdname constructors
#'
#' @examples
#' DbscanCluster("test", 0.5, 2, matrix(1:10))
#'
#' @aliases DbscanCluster
#' @seealso Dbscan-class
#' @export DbscanCluster
DbscanCluster <- function(name, epsilon, minPoints, clustering){

    new("Dbscan",
            name=name,
            epsilon=epsilon,
            minPoints=minPoints,
            clustering=clustering)
}