@@ -2,6 +2,7 @@

 S3method(plot,CogapsResult)

 export(CoGAPS)

+export(CogapsParams)

 export(GWCoGAPS)

 export(binaryA)

 export(buildReport)

@@ -11,10 +12,12 @@ export(checkpointsEnabled)

 export(findConsensusMatrix)

 export(getClusteredPatterns)

 export(getCorrelationToMeanPattern)

+export(getFeatureLoadings)

 export(getMeanChiSq)

 export(getOriginalParameters)

 export(getParam)

 export(getRetinaSubset)

+export(getSampleFactors)

 export(getSubsets)

 export(getUnmatchedPatterns)

 export(getVersion)

@@ -25,6 +28,7 @@ export(reconstructGene)

 export(scCoGAPS)

 export(setAnnotationWeights)

 export(setDistributedParams)

+export(setFixedPatterns)

 export(setParam)

 exportClasses(CogapsParams)

 exportClasses(CogapsResult)

@@ -49,19 +49,7 @@ checkpointsEnabled <- function()

 #' @param transposeData T/F for transposing data while reading it in - useful

 #' for data that is stored as samples x genes since CoGAPS requires data to be

 #' genes x samples

-#' @param subsetIndices set of indices to use from the data

-#' @param subsetDim which dimension (1=rows, 2=cols) to subset

 #' @param BPPARAM BiocParallel backend 

-#' @param geneNames vector of names of genes in data

-#' @param sampleNames vector of names of samples in data

-#' @param fixedPatterns fix either 'A' or 'P' matrix to these values, in the

-#' context of distributed CoGAPS (GWCoGAPS/scCoGAPS), the first phase is

-#' skipped and fixedPatterns is used for all sets - allowing manual pattern

-#' matching, as well as fixed runs of standard CoGAPS

-#' @param whichMatrixFixed either 'A' or 'P', indicating which matrix is fixed

-#' @param takePumpSamples whether or not to take PUMP samples

-#' @param outputToFile name of a file to save the output to, will create 4 files

-#' of the form "filename_nPatterns_[Amean, Asd, Pmean, Psd].extension"

 #' @param workerID if calling CoGAPS in parallel the worker ID can be specified,

 #' only worker 1 prints output and each worker outputs when it finishes, this

 #' is not neccesary when using the default parallel methods (i.e. distributed

@@ -82,17 +70,18 @@ checkpointsEnabled <- function()

 #' params <- setParam(params, "nPatterns", 3)

 #' resultC <- CoGAPS(GIST.data_frame, params, nIterations=25)

 #' @importFrom methods new is

-#' @importFrom SummarizedExperiment assay

-#' @importFrom utils packageVersion

-CoGAPS <- function(data, params=new("CogapsParams"), nThreads=1,

-messages=TRUE, outputFrequency=500, uncertainty=NULL,

-checkpointOutFile="gaps_checkpoint.out", checkpointInterval=1000,

-checkpointInFile=NULL, transposeData=FALSE, subsetIndices=NULL, subsetDim=0,

-BPPARAM=NULL, geneNames=NULL, sampleNames=NULL, fixedPatterns=NULL,

-whichMatrixFixed='N', takePumpSamples=FALSE, outputToFile=NULL, workerID=1, ...)

+CoGAPS <- function(data, params=new("CogapsParams"), nThreads=1, messages=TRUE,

+outputFrequency=500, uncertainty=NULL, checkpointOutFile="gaps_checkpoint.out",

+checkpointInterval=1000, checkpointInFile=NULL, transposeData=FALSE,

+BPPARAM=NULL, workerID=1, ...)

 {

-    # store all parameters in a list and parse parameters from ...

+    # pre-process inputs

+    data <- getValueOrRds(data)

+    data <- convertDataToMatrix(data)

+    params <- getValueOrRds(params)

     validObject(params)

+

+    # store all parameters in a list and parse parameters from ...

     allParams <- list("gaps"=params,

         "nThreads"=nThreads,

         "messages"=messages,

@@ -100,48 +89,24 @@ whichMatrixFixed='N', takePumpSamples=FALSE, outputToFile=NULL, workerID=1, ...)

         "checkpointOutFile"=checkpointOutFile,

         "checkpointInterval"=checkpointInterval,

         "checkpointInFile"=checkpointInFile,

+        "geneNames"=NULL, # the gene/sample names in the params object are kept

+        "sampleNames"=NULL, # as a reference, these are the values actually used

         "transposeData"=transposeData,

-        "subsetIndices"=subsetIndices,

-        "subsetDim"=subsetDim,

         "BPPARAM"=BPPARAM,

-        "fixedPatterns"=fixedPatterns,

-        "whichMatrixFixed"=whichMatrixFixed,

-        "takePumpSamples"=takePumpSamples,

-        "outputToFile"=outputToFile,

+        "outputToFile"=NULL,

         "workerID"=workerID

     )

     allParams <- parseExtraParams(allParams, list(...))

-

-    # if rds was passed, we first read it in before any processing

-    if (is(data, "character"))

-    {

-        if (tools::file_ext(data) == "rds")

-        {

-            gapsCat(allParams, "reading RDS file...")

-            data <- readRDS(data)

-            gapsCat(allParams, "done\n")

-        }

-    }

-

-    # convert data if needed

-    if (is(data, "data.frame"))

-        data <- data.matrix(data)

-    else if (is(data, "SummarizedExperiment"))

-        data <- SummarizedExperiment::assay(data, "counts")

-    else if (is(data, "SingleCellExperiment"))

-        data <- SummarizedExperiment::assay(data, "counts")

-

-    # check that inputs are valid, then read the gene/sample names from the data

+    allParams <- getDimNames(data, allParams)

     checkInputs(data, uncertainty, allParams)

-    allParams <- getNamesFromData(data, allParams, geneNames, sampleNames)

-   

+

     # check if we're running from a checkpoint

     if (!is.null(allParams$checkpointInFile))

     {

         gapsCat(allParams, "Running CoGAPS from a checkpoint\n")

     }

-    # determine which function to call cogaps algorithm

+    # determine function to call cogaps algorithm

     dispatchFunc <- cogaps_cpp # default

     if (!is.null(allParams$gaps@distributed))

         dispatchFunc <- distributedCogaps # genome-wide or single-cell cogaps

@@ -170,12 +135,10 @@ whichMatrixFixed='N', takePumpSamples=FALSE, outputToFile=NULL, workerID=1, ...)

 #' params <- setParam(params, "nPatterns", 3)

 #' result <- scCoGAPS(t(GIST.matrix), params, BPPARAM=BiocParallel::SerialParam())

 #' }

-scCoGAPS <- function(data, params=new("CogapsParams"), nThreads=1,

-messages=TRUE, outputFrequency=500, uncertainty=NULL,

-checkpointOutFile="gaps_checkpoint.out", checkpointInterval=1000,

-checkpointInFile=NULL, transposeData=FALSE, subsetIndices=NULL, subsetDim=0,

-BPPARAM=NULL, geneNames=NULL, sampleNames=NULL, fixedPatterns=NULL,

-whichMatrixFixed='N', takePumpSamples=FALSE, outputToFile=NULL, workerID=1, ...)

+scCoGAPS <- function(data, params=new("CogapsParams"), nThreads=1, messages=TRUE,

+outputFrequency=500, uncertainty=NULL, checkpointOutFile="gaps_checkpoint.out",

+checkpointInterval=1000, checkpointInFile=NULL, transposeData=FALSE,

+BPPARAM=NULL, workerID=1, ...)

 {

     params@distributed <- "single-cell"

     params@singleCell <- TRUE

@@ -190,15 +153,7 @@ whichMatrixFixed='N', takePumpSamples=FALSE, outputToFile=NULL, workerID=1, ...)

         checkpointInterval=checkpointInterval,

         checkpointInFile=checkpointInFile,

         transposeData=transposeData,

-        subsetIndices=subsetIndices,

-        subsetDim=subsetDim,

         BPPARAM=BPPARAM,

-        geneNames=geneNames,

-        sampleNames=sampleNames,

-        fixedPatterns=fixedPatterns,

-        whichMatrixFixed=whichMatrixFixed,

-        takePumpSamples=takePumpSamples,

-        outputToFile=outputToFile,

         workerID=workerID,

         ...

     )

@@ -220,12 +175,10 @@ whichMatrixFixed='N', takePumpSamples=FALSE, outputToFile=NULL, workerID=1, ...)

 #' params <- setParam(params, "nPatterns", 3)

 #' result <- GWCoGAPS(GIST.matrix, params, BPPARAM=BiocParallel::SerialParam())

 #' }

-GWCoGAPS <- function(data, params=new("CogapsParams"), nThreads=1,

-messages=TRUE, outputFrequency=500, uncertainty=NULL,

-checkpointOutFile="gaps_checkpoint.out", checkpointInterval=1000,

-checkpointInFile=NULL, transposeData=FALSE, subsetIndices=NULL, subsetDim=0,

-BPPARAM=NULL, geneNames=NULL, sampleNames=NULL, fixedPatterns=NULL,

-whichMatrixFixed='N', takePumpSamples=FALSE, outputToFile=NULL, workerID=1, ...)

+GWCoGAPS <- function(data, params=new("CogapsParams"), nThreads=1, messages=TRUE,

+outputFrequency=500, uncertainty=NULL, checkpointOutFile="gaps_checkpoint.out",

+checkpointInterval=1000, checkpointInFile=NULL, transposeData=FALSE,

+BPPARAM=NULL, workerID=1, ...)

 {

     params@distributed <- "genome-wide"

     CoGAPS(

@@ -239,16 +192,8 @@ whichMatrixFixed='N', takePumpSamples=FALSE, outputToFile=NULL, workerID=1, ...)

         checkpointInterval=checkpointInterval,

         checkpointInFile=checkpointInFile,

         transposeData=transposeData,

-        subsetIndices=subsetIndices,

-        subsetDim=subsetDim,

         BPPARAM=BPPARAM,

-        geneNames=geneNames,

-        sampleNames=sampleNames,

-        fixedPatterns=fixedPatterns,

-        whichMatrixFixed=whichMatrixFixed,

-        takePumpSamples=takePumpSamples,

-        outputToFile=outputToFile,

         workerID=workerID,

         ...

     )

-}

\ No newline at end of file

+}

@@ -26,8 +26,8 @@ workerID)

     else

         allParams$sampleNames <- allParams$sampleNames[subsetIndices]

-    allParams$subsetIndices <- subsetIndices

-    allParams$subsetDim <- ifelse(genomeWide, 1, 2)

+    allParams$gaps@subsetIndices <- subsetIndices

+    allParams$gaps@subsetDim <- ifelse(genomeWide, 1, 2)

     allParams$workerID <- workerID

     # call CoGAPS

@@ -226,6 +226,7 @@ corcut <- function(allPatterns, cut, minNS)

 #' @return list with all CoGAPS output

 stitchTogether <- function(result, allParams)

 {

+    print("stiching together...")

     if (allParams$gaps@distributed == "genome-wide")

     {

         consensus <- result[[1]]@sampleFactors

@@ -4,13 +4,14 @@

 #' @description combines retina subsets from extdata directory

 #' @param n number of subsets to use

 #' @return matrix of RNA counts

+#' @examples

+#' retSubset <- getRetinaSubset()

+#' dim(retSubset)

 #' @importFrom rhdf5 h5read

 getRetinaSubset <- function(n=1)

 {

     if (!(n %in% 1:4))

-    {

         stop("invalid number of subsets requested")

-    }

     subset_1_path <- system.file("extdata/retina_subset_1.h5", package="CoGAPS")

     subset_2_path <- system.file("extdata/retina_subset_2.h5", package="CoGAPS")

@@ -66,6 +67,35 @@ supported <- function(file)

     return(tools::file_ext(file) %in% c("tsv", "csv", "mtx", "gct"))

 }

+#' checks if file is rds format

+#' @keywords internal

+#'

+#' @param file path to file

+#' @return TRUE if file is .rds, FALSE if not

+#' @importFrom tools file_ext

+isRdsFile <- function(file)

+{

+    if (is.null(file))

+        return(FALSE)

+    if (length(file) == 0)

+        return(FALSE)

+    if (!is(file, "character"))

+        return(FALSE)

+    return(tools::file_ext(file) == ".rds")

+}

+

+#' get input that might be an RDS file

+#' @keywords internal

+#'

+#' @param input some user input

+#' @return if input is an RDS file, read it - otherwise return input

+getValueOrRds <- function(input)

+{

+    if (isRdsFile(input))

+        return(readRDS(input))

+    return(input)

+}

+

 #' get number of rows from supported file name or matrix

 #' @keywords internal

 #'

@@ -114,9 +144,7 @@ ncolHelper <- function(data)

 getGeneNames <- function(data, transpose)

 {

     if (transpose)

-    {

         return(getSampleNames(data, FALSE))

-    }

     names <- NULL

     if (is(data, "character"))

@@ -127,16 +155,13 @@ getGeneNames <- function(data, transpose)

             "gct" = suppressWarnings(gsub("\"", "", as.matrix(data.table::fread(data, select=1))))

         )

     }

-    else if (is(data, "matrix") | is(data, "data.frame"))

+    else

     {

         names <- rownames(data)

     }

     if (is.null(names))

-    {

-        nGenes <- nrowHelper(data)

-        return(paste("Gene", 1:nGenes, sep="_"))

-    }

+        return(paste("Gene", 1:nrowHelper(data), sep="_"))

     return(names)

 }

@@ -146,9 +171,7 @@ getGeneNames <- function(data, transpose)

 getSampleNames <- function(data, transpose)

 {

     if (transpose)

-    {

         return(getGeneNames(data, FALSE))

-    }

     names <- NULL

     if (is(data, "character"))

@@ -159,16 +182,13 @@ getSampleNames <- function(data, transpose)

             "gct" = suppressWarnings(colnames(data.table::fread(data, skip=2, nrows=1))[-1:-2])

         )

     }

-    else if (is(data, "matrix") | is(data, "data.frame"))

+    else

     {

         names <- colnames(data)

     }

     if (is.null(names))

-    {

-        nSamples <- ncolHelper(data)

-        return(paste("Sample", 1:nSamples, sep="_"))

-    }

+        return(paste("Sample", 1:ncolHelper(data), sep="_"))

     return(names)

 }

@@ -236,9 +256,6 @@ parseExtraParams <- function(allParams, extraParams)

 #' @return throws an error if data has problems

 checkDataMatrix <- function(data, uncertainty, params)

 {

-    if (!is(data, "matrix") & !is(data, "data.frame")

-    & !is(data, "SummarizedExperiment") & !is(data, "SingleCellExperiment"))

-        stop("unsupported object type of CoGAPS")

     if (any(is.na(data)))

         stop("NA values in data")

     if (!all(apply(data, 2, is.numeric)))

@@ -260,9 +277,6 @@ checkDataMatrix <- function(data, uncertainty, params)

 #' @return throws an error if inputs are invalid

 checkInputs <- function(data, uncertainty, allParams)

 {

-    if (is(data, "character") & !supported(data))

-        stop("unsupported file extension for data")

-

     if (is(data, "character") & !is.null(uncertainty) & !is(uncertainty, "character"))

         stop("uncertainty must be same data type as data (file name)")

     if (is(uncertainty, "character") & !supported(uncertainty))

@@ -272,34 +286,16 @@ checkInputs <- function(data, uncertainty, allParams)

     if (!is.null(uncertainty) & allParams$gaps@sparseOptimization)

         stop("must use default uncertainty when enabling sparseOptimization")

-    if (!(allParams$whichMatrixFixed %in% c("A", "P", "N")))

-        stop("Invalid choice of fixed matrix, must be 'A' or 'P'")

-    if (!is.null(allParams$fixedPatterns) & allParams$whichMatrixFixed == "N")

-        stop("fixedPatterns passed without setting whichMatrixFixed")

-    if (allParams$whichMatrixFixed %in% c("A", "P") & is.null(allParams$fixedPatterns))

-        stop("whichMatrixFixed is set without passing fixedPatterns")

-

     if (!is.null(allParams$gaps@distributed))

     {

         if (allParams$gaps@distributed == "single-cell" & !allParams$gaps@singleCell)

             warning("running single-cell CoGAPS with singleCell=FALSE")

-        if (!is.null(allParams$fixedPatterns) & is.null(allParams$gaps@explicitSets))

-            warning("doing manual pattern matching with using explicit subsets")

         if (allParams$nThreads > 1)

             stop("can't run multi-threaded and distributed CoGAPS at the same time")

         if (!is.null(allParams$checkpointInFile))

             stop("checkpoints not supported for distributed cogaps")

-        if (allParams$gaps@distributed == "single-cell" & allParams$whichMatrixFixed == "P")

-            stop("can't fix P matrix when running single-cell CoGAPS")

-        if (allParams$gaps@distributed == "genome-wide" & allParams$whichMatrixFixed == "A")

-            stop("can't fix A matrix when running genome-wide CoGAPS")

     }

-    if (!(allParams$subsetDim %in% c(0,1,2)))

-        stop("invalid subset dimension")

-    if (allParams$subsetDim > 0 & is.null(allParams$subsetIndices))

-        stop("subsetDim provided without subsetIndices")

-

     if (!is(data, "character"))

         checkDataMatrix(data, uncertainty, allParams$gaps)

 }

@@ -309,38 +305,72 @@ checkInputs <- function(data, uncertainty, allParams)

 #'

 #' @param data data matrix

 #' @param allParams list of all parameters

-#' @param geneNames vector of names of genes in data

-#' @param sampleNames vector of names of samples in data

 #' @return list of all parameters with added gene names

-getNamesFromData <- function(data, allParams, geneNames, sampleNames)

+getDimNames <- function(data, allParams)

 {

-    # get gene/sample names

-    if (is.null(geneNames))

+    # get user supplied names

+    geneNames <- allParams$gaps@geneNames

+    sampleNames <- allParams$gaps@sampleNames

+

+    # if user didn't supply any names, pull from data set or use default labels

+    if (is.null(allParams$gaps@geneNames))

         geneNames <- getGeneNames(data, allParams$transposeData)

-    if (is.null(sampleNames))

+    if (is.null(allParams$gaps@sampleNames))

         sampleNames <- getSampleNames(data, allParams$transposeData)

+    # get the number of genes/samples

     nGenes <- ifelse(allParams$transposeData, ncolHelper(data), nrowHelper(data))

     nSamples <- ifelse(allParams$transposeData, nrowHelper(data), ncolHelper(data))

-    if (allParams$subsetDim == 1)

+    # handle any subsetting

+    if (allParams$gaps@subsetDim == 1)

     {

-        nGenes <- length(allParams$subsetIndices)

-        geneNames <- geneNames[allParams$subsetIndices]

+        nGenes <- length(allParams$gaps@subsetIndices)

+        geneNames <- geneNames[allParams$gaps@subsetIndices]

     }

-    else if (allParams$subsetDim == 2)

+    else if (allParams$gaps@subsetDim == 2)

     {

-        nSamples <- length(allParams$subsetIndices)

-        sampleNames <- sampleNames[allParams$subsetIndices]

+        nSamples <- length(allParams$gaps@subsetIndices)

+        sampleNames <- sampleNames[allParams$gaps@subsetIndices]

     }    

+    # check that names align with expected number of genes/samples

     if (length(geneNames) != nGenes)

         stop("incorrect number of gene names given")

     if (length(sampleNames) != nSamples)

         stop("incorrect number of sample names given")

+    # store processed gene/sample names directly in allParams list

+    # this is an important distinction - allParams@gaps contains the

+    # gene/sample names originally passed by the user, allParams contains

+    # the procseed gene/sample names to be used when labeling the result

     allParams$geneNames <- geneNames

     allParams$sampleNames <- sampleNames

-

     return(allParams)

+}

+

+#' convert any acceptable data input to a numeric matrix

+#' @keywords internal

+#'

+#' @description convert supported R objects containing the data to a

+#' numeric matrix, if data is a file name do nothing. Exits with an error

+#' if data is not a supported type.

+#' @param data data input

+#' @return data matrix

+#' @importFrom methods is

+#' @importFrom SummarizedExperiment assay

+convertDataToMatrix <- function(data)

+{

+    if (is(data, "character") & !supported(data))

+        stop("unsupported file extension for data")

+    else if (is(data, "matrix") | is(data, "character"))

+        return(data)

+    else if (is(data, "data.frame"))

+        return(data.matrix(data))

+    else if (is(data, "SummarizedExperiment"))

+        return(SummarizedExperiment::assay(data, "counts"))

+    else if (is(data, "SingleCellExperiment"))

+        return(SummarizedExperiment::assay(data, "counts"))

+    else

+        stop("unsupported data type")

 }

\ No newline at end of file

@@ -28,6 +28,16 @@

 #' the rows (cols) to use for weighted sampling

 #' @slot samplingWeight [distributed parameter] weights associated with 

 #' samplingAnnotation

+#' @slot subsetIndices set of indices to use from the data

+#' @slot subsetDim which dimension (1=rows, 2=cols) to subset

+#' @slot geneNames vector of names of genes in data

+#' @slot sampleNames vector of names of samples in data

+#' @slot fixedPatterns fix either 'A' or 'P' matrix to these values, in the

+#' context of distributed CoGAPS (GWCoGAPS/scCoGAPS), the first phase is

+#' skipped and fixedPatterns is used for all sets - allowing manual pattern

+#' matching, as well as fixed runs of standard CoGAPS

+#' @slot whichMatrixFixed either 'A' or 'P', indicating which matrix is fixed

+#' @slot takePumpSamples whether or not to take PUMP samples

 #' @importClassesFrom S4Vectors character_OR_NULL

 setClass("CogapsParams", slots = c(

     nPatterns = "numeric",

@@ -46,7 +56,14 @@ setClass("CogapsParams", slots = c(

     maxNS = "numeric",

     explicitSets = "ANY",

     samplingAnnotation = "character_OR_NULL",

-    samplingWeight = "numeric"

+    samplingWeight = "ANY",

+    subsetIndices="ANY",

+    subsetDim="numeric",

+    geneNames="character_OR_NULL",

+    sampleNames="character_OR_NULL",

+    fixedPatterns="ANY",

+    whichMatrixFixed="character",

+    takePumpSamples="logical"

 ))

 #' constructor for CogapsParams

@@ -70,7 +87,7 @@ setMethod("initialize", "CogapsParams",

         if (!is.null(list(...)$maxNS))

             stop("maxNS must be set after CogapsParams are intialized")

         if (!is.null(distributed))

-            if (distributed == "none")

+            if (distributed == "none") # allows it to be a pure string parameter

                 distributed <- NULL

         .Object@distributed <- distributed

@@ -89,7 +106,14 @@ setMethod("initialize", "CogapsParams",

         .Object@maxNS <- .Object@minNS + .Object@nSets

         .Object@explicitSets <- NULL

         .Object@samplingAnnotation <- NULL

-        .Object@samplingWeight <- integer(0)

+        .Object@samplingWeight <- NULL

+        .Object@subsetIndices <- NULL

+        .Object@subsetDim <- 0

+        .Object@geneNames <- NULL

+        .Object@sampleNames <- NULL

+        .Object@fixedPatterns <- NULL

+        .Object@whichMatrixFixed <- 'N'

+        .Object@takePumpSamples <- FALSE

         .Object <- callNextMethod(.Object, ...)

         .Object

@@ -104,42 +128,60 @@ setValidity("CogapsParams",

             "number of patterns must be an integer greater than zero"

         if (object@nIterations <= 0 | object@nIterations %% 1 != 0)

             "number of iterations must be an integer greater than zero"

-        if (object@alphaA  <= 0 | object@alphaP <= 0)

+        if (object@alphaA <= 0 | object@alphaP <= 0)

             "alpha parameter must be greater than zero"

-        if (object@maxGibbsMassA  <= 0 | object@maxGibbsMassP <= 0)

+        if (object@maxGibbsMassA <= 0 | object@maxGibbsMassP <= 0)

             "maxGibbsMass must be greater than zero"

         if (object@seed <= 0 | object@seed %% 1 != 0)

             "random seed must be an integer greater than zero"

-        if (object@minNS <= 1 | object@minNS %% 1 != 0)

-            "minNS must be an integer greater than one"

-        if (object@nSets <= 1 | object@nSets %% 1 != 0)

-            "minNS must be an integer greater than one"

-        if (!is.null(object@explicitSets) & length(object@explicitSets) != object@nSets)

-            "nSets doesn't match length of explicitSets"

-        if (length(unique(object@samplingAnnotation)) != length(object@samplingWeight))

-            "samplingWeight has mismatched size with amount of distinct annotations"

-        if (object@cut > object@nPatterns)

-            "cut must be less than or equal to nPatterns"

-        # check type of explicitSets

-        if (!is.null(object@explicitSets) & !is(object@explicitSets, "list"))

-            "explicitSets must be a list of numeric or character"

-        isNum <- sapply(object@explicitSets, function(s) is(s, "numeric"))

-        isChar <- sapply(object@explicitSets, function(s) is(s, "charcater"))

-        if (!is.null(object@explicitSets) & !(all(isNum) | all(isChar)))

-            "explicitSets must be a list of numeric or character"

+        if (!(object@whichMatrixFixed %in% c("A", "P", "N")))

+            stop("Invalid choice of fixed matrix, must be 'A' or 'P'")

+        if (!is.null(object@fixedPatterns) & object@whichMatrixFixed == "N")

+            stop("fixedPatterns passed without setting whichMatrixFixed")

+        if (object@whichMatrixFixed %in% c("A", "P") & is.null(object@fixedPatterns))

+            stop("whichMatrixFixed is set without passing fixedPatterns")

-        if (!is.null(object@explicitSets) & length(object@explicitSets) != object@nSets)

-            "wrong number of sets given"

-        if (length(object@samplingWeight) & is.null(names(object@samplingWeight)))

-            "samplingWeight must be a named vector"

-

-        if (!is.null(object@explicitSets) & !is.null(object@samplingAnnotation))

-            "explicitSets and samplingAnnotation/samplingWeight are both set"

+        if (!(object@subsetDim %in% c(0,1,2)))

+            stop("invalid subset dimension")

+        if (object@subsetDim > 0 & is.null(object@subsetIndices))

+            stop("subsetDim provided without subsetIndices")

         if (!is.null(object@distributed))

+        {

             if (!(object@distributed %in% c("genome-wide", "single-cell")))

                 "distributed method must be either 'genome-wide' or 'single-cell'"

+            if (!is.null(object@fixedPatterns) & is.null(object@explicitSets))

+                "doing manual pattern matching without using explicit subsets"

+            if (object@distributed == "single-cell" & object@whichMatrixFixed == "P")

+                "can't fix P matrix when running single-cell CoGAPS"

+            if (object@distributed == "genome-wide" & object@whichMatrixFixed == "A")

+                "can't fix A matrix when running genome-wide CoGAPS"

+            if (object@minNS <= 1 | object@minNS %% 1 != 0)

+                "minNS must be an integer greater than one"

+            if (object@nSets <= 1 | object@nSets %% 1 != 0)

+                "minNS must be an integer greater than one"

+            if (length(unique(object@samplingAnnotation)) != length(object@samplingWeight))

+                "samplingWeight has mismatched size with amount of distinct annotations"

+            if (object@cut > object@nPatterns)

+                "cut must be less than or equal to nPatterns"

+            if (length(object@samplingWeight) & is.null(names(object@samplingWeight)))

+                "samplingWeight must be a named vector"

+

+            if (!is.null(object@explicitSets))

+            {

+                if (!is(object@explicitSets, "list"))

+                    "explicitSets must be a list"

+                if (length(object@explicitSets) != object@nSets)

+                    "nSets doesn't match length of explicitSets"

+                if (!is.null(object@samplingAnnotation))

+                    "explicitSets and samplingAnnotation/samplingWeight are both set"

+                isNum <- sapply(object@explicitSets, function(s) is(s, "numeric"))

+                isChar <- sapply(object@explicitSets, function(s) is(s, "character"))

+                if (!all(isNum) & !all(isChar))

+                    "explicitSets must be a list of numeric or character"

+            }

+        }

     }

 )

@@ -194,6 +236,23 @@ minNS=NULL, maxNS=NULL)

 setGeneric("setAnnotationWeights", function(object, annotation, weights)

     {standardGeneric("setAnnotationWeights")})

+#' set the fixed patterns for either the A or the P matrix

+#' @export

+#' @docType methods

+#' @rdname setFixedPatterns-methods

+#'

+#' @description these parameters are interrelated so they must be set together

+#' @param object an object of type CogapsParams

+#' @param fixedPatterns values for either the A or P matrix

+#' @param whichMatrixFixed either 'A' or 'P' indicating which matrix is fixed

+#' @return the modified params object

+#' @examples

+#' params <- new("CogapsParams")

+#' data(GIST)

+#' params <- setFixedPatterns(params, getSampleFactors(GIST.result), 'P')

+setGeneric("setFixedPatterns", function(object, fixedPatterns, whichMatrixFixed)

+    {standardGeneric("setFixedPatterns")})

+

 #' get the value of a parameter

 #' @export

 #' @docType methods

@@ -41,7 +41,8 @@ sampleNames, diagnostics=NULL, ...)

     patternNames <- paste("Pattern", 1:ncol(Amean), sep="_")

     if (length(geneNames) != nrow(.Object@featureLoadings))

-        stop("number of gene names doesn't match data size")

+        stop("number of gene names doesn't match data size, ",

+            length(geneNames), " != ", nrow(.Object@featureLoadings))

     if (length(sampleNames) != nrow(.Object@sampleFactors))

         stop("number of sample names doesn't match data size")

@@ -82,6 +83,32 @@ setValidity("CogapsResult",

 ################################### GENERICS ###################################

+#' return featureLoadings matrix from CogapsResult object

+#' @export

+#' @docType methods

+#' @rdname getFeatureLoadings-methods

+#'

+#' @param object an object of type CogapsResult

+#' @return featureLoadings matrix

+#' @examples

+#' data(GIST)

+#' getFeatureLoadings(GIST.result)

+setGeneric("getFeatureLoadings", function(object)

+    {standardGeneric("getFeatureLoadings")})

+

+#' return sampleFactors matrix from CogapsResult object

+#' @export

+#' @docType methods

+#' @rdname getSampleFactors-methods

+#'

+#' @param object an object of type CogapsResult

+#' @return sampleFactors matrix

+#' @examples

+#' data(GIST)

+#' getSampleFactors(GIST.result)

+setGeneric("getSampleFactors", function(object)

+    {standardGeneric("getSampleFactors")})

+

 #' return chi-sq of final matrices

 #' @export

 #' @docType methods

@@ -1,3 +1,17 @@

+#' CogapsParams constructor

+#' @export

+#'

+#' @description create a CogapsParams object

+#' @param ... parameters for the initialization method

+#' @return CogapsParams object

+#' @examples

+#' params <- CogapsParams(nPatterns=10)

+#' params

+CogapsParams <- function(...)

+{

+    new("CogapsParams", ...)

+}

+

 setMethod("show", signature("CogapsParams"),

 function(object)

 {

@@ -59,11 +73,15 @@ function(object, whichParam, value)

     }

     else if (whichParam %in% c("nSets", "cut", "minNS", "maxNS"))

     {

-        stop("please set this parameter with setDistributedParams")

+        stop("please set \'", whichParam, "\' with setDistributedParams")

     }

     else if (whichParam %in% c("samplingAnnotation", "samplingWeight"))

     {

-        stop("please set this parameter with setAnnotationWeights")

+        stop("please set \'", whichParam, "\' with setAnnotationWeights")

+    }

+    else if (whichParam %in% c("fixedPatterns", "whichMatrixFixed"))

+    {

+        stop("please set \'", whichParam, "\' with setFixedPatterns")

     }

     else if (whichParam == "nPatterns")

     {

@@ -116,6 +134,18 @@ function(object, annotation, weights)

     return(object)

 })

+#' @rdname setFixedPatterns-methods

+#' @aliases setFixedPatterns

+setMethod("setFixedPatterns", signature(object="CogapsParams"),

+function(object, fixedPatterns, whichMatrixFixed)

+{

+    object@fixedPatterns <- fixedPatterns

+    object@whichMatrixFixed <- whichMatrixFixed

+

+    validObject(object)

+    return(object)

+})

+

 #' @rdname getParam-methods

 #' @aliases getParam

 setMethod("getParam", signature(object="CogapsParams"),

@@ -4,6 +4,7 @@

 #' @param returnList list from cogaps_cpp

 #' @param allParams list of all parameters

 #' @return CogapsResult object

+#' @importFrom utils packageVersion

 createCogapsResult <- function(returnList, allParams)

 {

     res <- new("CogapsResult",

@@ -57,6 +58,22 @@ plot.CogapsResult <- function(x, ...)

         lty=1, cex=0.8, col=colors, bty="y", ncol=5)

 }

+#' @rdname getFeatureLoadings-methods

+#' @aliases getFeatureLoadings

+setMethod("getFeatureLoadings", signature(object="CogapsResult"),

+function(object)

+{

+    object@featureLoadings

+})

+

+#' @rdname getSampleFactors-methods

+#' @aliases getSampleFactors

+setMethod("getSampleFactors", signature(object="CogapsResult"),

+function(object)

+{

+    object@sampleFactors

+})

+

 #' @rdname getMeanChiSq-methods

 #' @aliases getMeanChiSq

 setMethod("getMeanChiSq", signature(object="CogapsResult"),

@@ -7,11 +7,8 @@

 CoGAPS(data, params = new("CogapsParams"), nThreads = 1,

   messages = TRUE, outputFrequency = 500, uncertainty = NULL,

   checkpointOutFile = "gaps_checkpoint.out", checkpointInterval = 1000,

-  checkpointInFile = NULL, transposeData = FALSE,

-  subsetIndices = NULL, subsetDim = 0, BPPARAM = NULL,

-  geneNames = NULL, sampleNames = NULL, fixedPatterns = NULL,

-  whichMatrixFixed = "N", takePumpSamples = FALSE,

-  outputToFile = NULL, workerID = 1, ...)

+  checkpointInFile = NULL, transposeData = FALSE, BPPARAM = NULL,

+  workerID = 1, ...)

 }

 \arguments{

 \item{data}{File name or R object (see details for supported types)}

@@ -40,28 +37,8 @@ contained in this file}

 for data that is stored as samples x genes since CoGAPS requires data to be

 genes x samples}

-\item{subsetIndices}{set of indices to use from the data}

-

-\item{subsetDim}{which dimension (1=rows, 2=cols) to subset}

-

 \item{BPPARAM}{BiocParallel backend}

-\item{geneNames}{vector of names of genes in data}

-

-\item{sampleNames}{vector of names of samples in data}

-

-\item{fixedPatterns}{fix either 'A' or 'P' matrix to these values, in the

-context of distributed CoGAPS (GWCoGAPS/scCoGAPS), the first phase is

-skipped and fixedPatterns is used for all sets - allowing manual pattern

-matching, as well as fixed runs of standard CoGAPS}

-

-\item{whichMatrixFixed}{either 'A' or 'P', indicating which matrix is fixed}

-

-\item{takePumpSamples}{whether or not to take PUMP samples}

-

-\item{outputToFile}{name of a file to save the output to, will create 4 files

-of the form "filename_nPatterns_[Amean, Asd, Pmean, Psd].extension"}

-

 \item{workerID}{if calling CoGAPS in parallel the worker ID can be specified,

 only worker 1 prints output and each worker outputs when it finishes, this

 is not neccesary when using the default parallel methods (i.e. distributed

@@ -51,5 +51,22 @@ the rows (cols) to use for weighted sampling}

 \item{\code{samplingWeight}}{[distributed parameter] weights associated with 

 samplingAnnotation}

+

+\item{\code{subsetIndices}}{set of indices to use from the data}

+

+\item{\code{subsetDim}}{which dimension (1=rows, 2=cols) to subset}

+

+\item{\code{geneNames}}{vector of names of genes in data}

+

+\item{\code{sampleNames}}{vector of names of samples in data}

+

+\item{\code{fixedPatterns}}{fix either 'A' or 'P' matrix to these values, in the

+context of distributed CoGAPS (GWCoGAPS/scCoGAPS), the first phase is

+skipped and fixedPatterns is used for all sets - allowing manual pattern

+matching, as well as fixed runs of standard CoGAPS}

+

+\item{\code{whichMatrixFixed}}{either 'A' or 'P', indicating which matrix is fixed}

+

+\item{\code{takePumpSamples}}{whether or not to take PUMP samples}

 }}

new file mode 100755

@@ -0,0 +1,21 @@

+% Generated by roxygen2: do not edit by hand

+% Please edit documentation in R/methods-CogapsParams.R

+\name{CogapsParams}

+\alias{CogapsParams}

+\title{CogapsParams constructor}

+\usage{

+CogapsParams(...)

+}

+\arguments{

+\item{...}{parameters for the initialization method}

+}

+\value{

+CogapsParams object

+}

+\description{

+create a CogapsParams object

+}

+\examples{

+params <- CogapsParams(nPatterns=10)

+params

+}

@@ -7,11 +7,8 @@

 GWCoGAPS(data, params = new("CogapsParams"), nThreads = 1,

   messages = TRUE, outputFrequency = 500, uncertainty = NULL,

   checkpointOutFile = "gaps_checkpoint.out", checkpointInterval = 1000,

-  checkpointInFile = NULL, transposeData = FALSE,

-  subsetIndices = NULL, subsetDim = 0, BPPARAM = NULL,

-  geneNames = NULL, sampleNames = NULL, fixedPatterns = NULL,

-  whichMatrixFixed = "N", takePumpSamples = FALSE,

-  outputToFile = NULL, workerID = 1, ...)

+  checkpointInFile = NULL, transposeData = FALSE, BPPARAM = NULL,

+  workerID = 1, ...)

 }

 \arguments{

 \item{data}{File name or R object (see details for supported types)}