@@ -177,7 +177,6 @@ BPPARAM=NULL, workerID=1, asynchronousUpdates=FALSE, ...)

     warning(paste("scCoGAPS is deprecated, use the main function CoGAPS",

         "with the argument: distributed=\"single-cell\""))

     params@distributed <- "single-cell"

-    params@singleCell <- TRUE

     CoGAPS(

         data=data,

         params=params,

@@ -66,6 +66,10 @@ compiledWithOpenMPSupport <- function()

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

 #' CoGAPS) but only when the user is manually calling CoGAPS in parallel

 #' @param asynchronousUpdates enable asynchronous updating which allows for multi-threaded runs

+#' @param nSnapshots how many snapshots to take in each phase, setting this to 0 disables

+#' snapshots

+#' @param snapshotPhase which phase to take snapsjots in e.g. "equilibration", "sampling",

+#' "all"

 #' @param ... allows for overwriting parameters in params

 #' @return CogapsResult object

 #' @examples

@@ -83,7 +83,7 @@ compiledWithOpenMPSupport <- function()

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

 #' @importFrom methods new is

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

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

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

 checkpointInterval=0, checkpointInFile=NULL, transposeData=FALSE,

 BPPARAM=NULL, workerID=1, asynchronousUpdates=TRUE, nSnapshots=0,

 snapshotPhase='sampling', ...)

@@ -85,7 +85,8 @@ compiledWithOpenMPSupport <- function()

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

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

 checkpointInterval=0, checkpointInFile=NULL, transposeData=FALSE,

-BPPARAM=NULL, workerID=1, asynchronousUpdates=TRUE, nSnapshots=0, ...)

+BPPARAM=NULL, workerID=1, asynchronousUpdates=TRUE, nSnapshots=0,

+snapshotPhase='sampling', ...)

 {

     # pre-process inputs

     if (is(data, "character"))

@@ -112,6 +113,7 @@ BPPARAM=NULL, workerID=1, asynchronousUpdates=TRUE, nSnapshots=0, ...)

         "messages"=messages,

         "outputFrequency"=outputFrequency,

         "nSnapshots"=nSnapshots,

+        "snapshotPhase"=snapshotPhase,

         "checkpointOutFile"=checkpointOutFile,

         "checkpointInterval"=checkpointInterval,

         "checkpointInFile"=checkpointInFile,

@@ -85,7 +85,7 @@ compiledWithOpenMPSupport <- function()

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

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

 checkpointInterval=0, checkpointInFile=NULL, transposeData=FALSE,

-BPPARAM=NULL, workerID=1, asynchronousUpdates=TRUE, ...)

+BPPARAM=NULL, workerID=1, asynchronousUpdates=TRUE, nSnapshots=0, ...)

 {

     # pre-process inputs

     if (is(data, "character"))

@@ -111,6 +111,7 @@ BPPARAM=NULL, workerID=1, asynchronousUpdates=TRUE, ...)

         "nThreads"=nThreads,

         "messages"=messages,

         "outputFrequency"=outputFrequency,

+        "nSnapshots"=nSnapshots,

         "checkpointOutFile"=checkpointOutFile,

         "checkpointInterval"=checkpointInterval,

         "checkpointInFile"=checkpointInFile,

@@ -165,7 +165,7 @@ BPPARAM=NULL, workerID=1, asynchronousUpdates=TRUE, ...)

 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, ...)

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

 {

     warning(paste("scCoGAPS is deprecated, use the main function CoGAPS",

         "with the argument: distributed=\"single-cell\""))

@@ -207,7 +207,7 @@ BPPARAM=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, ...)

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

 {

     warning(paste("GWCoGAPS is deprecated, use the main function CoGAPS",

         "with the argument: distributed=\"genome-wide\""))

@@ -17,7 +17,7 @@ buildReport <- function()

 #' Check if package was built with checkpoints enabled

 #' @export

 #'

-#' @return true/false if check are enabled

+#' @return true/false if checkpoints are enabled

 #' @examples

 #' CoGAPS::checkpointsEnabled()

 checkpointsEnabled <- function()

@@ -25,6 +25,17 @@ checkpointsEnabled <- function()

     checkpointsEnabled_cpp()

 }

+#' Check if compiler supported OpenMP

+#' @export

+#'

+#' @return true/false if OpenMP was supported

+#' @examples

+#' CoGAPS::compiledWithOpenMPSupport()

+compiledWithOpenMPSupport <- function()

+{

+    compiledWithOpenMPSupport_cpp()

+}

+

 #' CoGAPS Matrix Factorization Algorithm

 #' @export 

 #'

@@ -86,6 +97,15 @@ BPPARAM=NULL, workerID=1, asynchronousUpdates=TRUE, ...)

     params <- getValueOrRds(params)

     validObject(params)

+    # check OpenMP support

+    if (!compiledWithOpenMPSupport())

+    {

+        if (asynchronousUpdates & nThreads > 1)

+            warning("requesting multi-threaded version of CoGAPS but compiler did not support OpenMP")

+        asynchronousUpdates = FALSE

+        nThreads = 1

+    }

+

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

     allParams <- list("gaps"=params,

         "nThreads"=nThreads,

@@ -54,6 +54,7 @@ checkpointsEnabled <- function()

 #' 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

 #' CoGAPS) but only when the user is manually calling CoGAPS in parallel

+#' @param asynchronousUpdates enable asynchronous updating which allows for multi-threaded runs

 #' @param ... allows for overwriting parameters in params

 #' @return CogapsResult object

 #' @examples

@@ -71,11 +71,15 @@ checkpointsEnabled <- function()

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

 #' @importFrom methods new is

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

-outputFrequency=2500, uncertainty=NULL, checkpointOutFile="gaps_checkpoint.out",

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

 checkpointInterval=0, checkpointInFile=NULL, transposeData=FALSE,

 BPPARAM=NULL, workerID=1, asynchronousUpdates=TRUE, ...)

 {

     # pre-process inputs

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

+        dataName <- data

+    else

+        dataName <- deparse(substitute(data))

     data <- getValueOrRds(data)

     data <- convertDataToMatrix(data)

     params <- getValueOrRds(params)

@@ -95,7 +99,8 @@ BPPARAM=NULL, workerID=1, asynchronousUpdates=TRUE, ...)

         "BPPARAM"=BPPARAM,

         "outputToFile"=NULL,

         "workerID"=workerID,

-        "asynchronousUpdates"=asynchronousUpdates

+        "asynchronousUpdates"=asynchronousUpdates,

+        "dataName"=dataName

     )

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

     allParams <- getDimNames(data, allParams)

@@ -73,7 +73,7 @@ checkpointsEnabled <- function()

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

 outputFrequency=2500, uncertainty=NULL, checkpointOutFile="gaps_checkpoint.out",

 checkpointInterval=0, checkpointInFile=NULL, transposeData=FALSE,

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

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

 {

     # pre-process inputs

     data <- getValueOrRds(data)

@@ -94,7 +94,8 @@ BPPARAM=NULL, workerID=1, ...)

         "transposeData"=transposeData,

         "BPPARAM"=BPPARAM,

         "outputToFile"=NULL,

-        "workerID"=workerID

+        "workerID"=workerID,

+        "asynchronousUpdates"=asynchronousUpdates

     )

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

     allParams <- getDimNames(data, allParams)

@@ -140,6 +140,8 @@ outputFrequency=500, uncertainty=NULL, checkpointOutFile="gaps_checkpoint.out",

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

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

 {

+    warning(paste("scCoGAPS is deprecated, use the main function CoGAPS",

+        "with the argument: distributed=\"single-cell\""))

     params@distributed <- "single-cell"

     params@singleCell <- TRUE

     CoGAPS(

@@ -180,6 +182,8 @@ outputFrequency=500, uncertainty=NULL, checkpointOutFile="gaps_checkpoint.out",

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

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

 {

+    warning(paste("GWCoGAPS is deprecated, use the main function CoGAPS",

+        "with the argument: distributed=\"genome-wide\""))

     params@distributed <- "genome-wide"

     CoGAPS(

         data=data,

@@ -111,7 +111,7 @@ BPPARAM=NULL, workerID=1, ...)

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

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

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

-        dispatchFunc <- cogaps_cpp_from_file # data is a file path

+        dispatchFunc <- cogaps_from_file_cpp # data is a file path

     # run cogaps

     startupMessage(data, allParams)

@@ -71,8 +71,8 @@ checkpointsEnabled <- function()

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

 #' @importFrom methods new is

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

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

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

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

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

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

 {

     # pre-process inputs

@@ -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

+}

@@ -14,6 +14,17 @@ buildReport <- function()

     getBuildReport_cpp()

 }

+#' Check if package was built with checkpoints enabled

+#' @export

+#'

+#' @return true/false if check are enabled

+#' @examples

+#' CoGAPS::checkpointsEnabled()

+checkpointsEnabled <- function()

+{

+    checkpointsEnabled_cpp()

+}

+

 #' CoGAPS Matrix Factorization Algorithm

 #' @export 

 #'

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

     )

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

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

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

     if (is(data, "character"))

     {

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

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

         {

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

             data <- readRDS(data)

@@ -101,12 +101,15 @@ whichMatrixFixed='N', takePumpSamples=FALSE, outputToFile=NULL, workerID=1, ...)

     )

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

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

-    if (is(data, "character") & tools::file_ext(data) == "rds")

+    # if rds was passed, we first read it in before any processings

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

     {

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

-        data <- readRDS(data)

-        gapsCat(allParams, "done\n")

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

+        {

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

+            data <- readRDS(data)

+            gapsCat(allParams, "done\n")

+        }

     }

     # convert data if needed

@@ -101,6 +101,14 @@ whichMatrixFixed='N', takePumpSamples=FALSE, outputToFile=NULL, workerID=1, ...)

     )

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

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

+    if (is(data, "character") & 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)

@@ -140,12 +140,14 @@ whichMatrixFixed='N', takePumpSamples=FALSE, outputToFile=NULL, workerID=1, ...)

 #' @return CogapsResult object

 #' @importFrom methods new

 #' @examples

+#' \dontrun{

 #' data(GIST)

 #' params <- new("CogapsParams")

 #' params <- setDistributedParams(params, nSets=2)

 #' params <- setParam(params, "nIterations", 100)

 #' 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,

@@ -188,12 +190,14 @@ whichMatrixFixed='N', takePumpSamples=FALSE, outputToFile=NULL, workerID=1, ...)

 #' @return CogapsResult object

 #' @importFrom methods new

 #' @examples

+#' \dontrun{

 #' data(GIST)

 #' params <- new("CogapsParams")

 #' params <- setDistributedParams(params, nSets=2)

 #' params <- setParam(params, "nIterations", 100)

 #' 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,

@@ -60,16 +60,16 @@ buildReport <- function()

 #' @examples

 #' # Running from R object

 #' data(GIST)

-#' resultA <- CoGAPS(GIST.data_frame, nIterations=100)

+#' resultA <- CoGAPS(GIST.data_frame, nIterations=25)

 #'

 #' # Running from file name

 #' gist_path <- system.file("extdata/GIST.mtx", package="CoGAPS")

-#' resultB <- CoGAPS(gist_path, nIterations=100)

+#' resultB <- CoGAPS(gist_path, nIterations=25)

 #'

 #' # Setting Parameters

 #' params <- new("CogapsParams")

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

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

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

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

 #' @importFrom methods new is

 #' @importFrom SummarizedExperiment assay

 #' @importFrom utils packageVersion

@@ -141,7 +141,11 @@ whichMatrixFixed='N', takePumpSamples=FALSE, outputToFile=NULL, workerID=1, ...)

 #' @importFrom methods new

 #' @examples

 #' data(GIST)

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

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

+#' params <- setDistributedParams(params, nSets=2)

+#' params <- setParam(params, "nIterations", 100)

+#' 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,

@@ -185,7 +189,11 @@ whichMatrixFixed='N', takePumpSamples=FALSE, outputToFile=NULL, workerID=1, ...)

 #' @importFrom methods new

 #' @examples

 #' data(GIST)

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

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

+#' params <- setDistributedParams(params, nSets=2)

+#' params <- setParam(params, "nIterations", 100)

+#' 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,

@@ -147,7 +147,7 @@ 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', outputToFile=NULL, workerID=1, ...)

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

 {

     params@distributed <- "single-cell"

     params@singleCell <- TRUE

@@ -169,6 +169,7 @@ whichMatrixFixed='N', outputToFile=NULL, workerID=1, ...)

         sampleNames=sampleNames,

         fixedPatterns=fixedPatterns,

         whichMatrixFixed=whichMatrixFixed,

+        takePumpSamples=takePumpSamples,

         outputToFile=outputToFile,

         workerID=workerID,

         ...

@@ -190,7 +191,7 @@ 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', outputToFile=NULL, workerID=1, ...)

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

 {

     params@distributed <- "genome-wide"

     CoGAPS(

@@ -211,6 +212,7 @@ whichMatrixFixed='N', outputToFile=NULL, workerID=1, ...)

         sampleNames=sampleNames,

         fixedPatterns=fixedPatterns,

         whichMatrixFixed=whichMatrixFixed,

+        takePumpSamples=takePumpSamples,

         outputToFile=outputToFile,

         workerID=workerID,

         ...

@@ -48,6 +48,7 @@ buildReport <- function()

 #' 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,

@@ -77,7 +78,7 @@ 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', outputToFile=NULL, workerID=1, ...)

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

 {

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

     validObject(params)

@@ -94,6 +95,7 @@ whichMatrixFixed='N', outputToFile=NULL, workerID=1, ...)

         "BPPARAM"=BPPARAM,

         "fixedPatterns"=fixedPatterns,

         "whichMatrixFixed"=whichMatrixFixed,

+        "takePumpSamples"=takePumpSamples,

         "outputToFile"=outputToFile,

         "workerID"=workerID

     )

@@ -43,7 +43,10 @@ buildReport <- function()

 #' @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

+#' @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 outputToFile name of a file to save the output to, will create 4 files

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

@@ -38,12 +38,19 @@ buildReport <- 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 matchedPatterns manually matched patterns for distributed CoGAPS

+#' @param fixedPatterns fix either 'A' or 'P' matrix to these values

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

 #' @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

+#' CoGAPS) but only when the user is manually calling CoGAPS in parallel

 #' @param ... allows for overwriting parameters in params

 #' @return CogapsResult object

 #' @examples

@@ -65,9 +72,9 @@ buildReport <- function()

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

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

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

-checkpointInFile=NULL, transposeData=FALSE, subsetData=NULL, BPPARAM=NULL,

-geneNames=NULL, sampleNames=NULL, fixedPatterns=NULL, whichMatrixFixed='N',

-outputToFile=NULL, ...)

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

+BPPARAM=NULL, geneNames=NULL, sampleNames=NULL, fixedPatterns=NULL,

+whichMatrixFixed='N', outputToFile=NULL, workerID=1, ...)

 {

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

     validObject(params)

@@ -79,14 +86,24 @@ outputToFile=NULL, ...)

         "checkpointInterval"=checkpointInterval,

         "checkpointInFile"=checkpointInFile,

         "transposeData"=transposeData,

-        "subsetData"=subsetData,

-        "bpBackend"=BPPARAM,

+        "subsetIndices"=subsetIndices,

+        "subsetDim"=subsetDim,

+        "BPPARAM"=BPPARAM,

         "fixedPatterns"=fixedPatterns,

         "whichMatrixFixed"=whichMatrixFixed,

         "outputToFile"=outputToFile,

+        "workerID"=workerID

     )

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

+    # 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

     checkInputs(data, uncertainty, allParams)

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

@@ -94,10 +111,7 @@ outputToFile=NULL, ...)

     # check if we're running from a checkpoint

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

     {

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

-            stop("checkpoints not supported for distributed cogaps")

-        else

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

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

     }

     # determine which function to call cogaps algorithm

@@ -110,19 +124,7 @@ outputToFile=NULL, ...)

     # run cogaps

     startupMessage(data, allParams)

     gapsReturnList <- dispatchFunc(data, allParams, uncertainty)

-

-    # convert list to CogapsResult object

-    return(new("CogapsResult",

-        Amean       = gapsReturnList$Amean,

-        Asd         = gapsReturnList$Asd,

-        Pmean       = gapsReturnList$Pmean,

-        Psd         = gapsReturnList$Psd,

-        meanChiSq   = gapsReturnList$meanChiSq,

-        geneNames   = gapsReturnList$geneNames,

-        sampleNames = gapsReturnList$sampleNames,

-        diagnostics = append(gapsReturnList$diagnostics,

-            list("params"=allParams$gaps, "version"=utils::packageVersion("CoGAPS")))

-    ))

+    return(createCogapsResult(gapsReturnList, allParams))

 }

 #' Single Cell CoGAPS

@@ -138,14 +140,34 @@ outputToFile=NULL, ...)

 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,

-geneNames=NULL, sampleNames=NULL, matchedPatterns=NULL, ...)

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

+BPPARAM=NULL, geneNames=NULL, sampleNames=NULL, fixedPatterns=NULL,

+whichMatrixFixed='N', outputToFile=NULL, workerID=1, ...)

 {

     params@distributed <- "single-cell"

     params@singleCell <- TRUE

-    CoGAPS(data, params, nThreads, messages, outputFrequency, uncertainty,

-        checkpointOutFile, checkpointInterval, checkpointInFile, transposeData,

-        BPPARAM, geneNames, sampleNames, matchedPatterns, ...)

+    CoGAPS(

+        data=data,

+        params=params,

+        nThreads=nThreads,

+        messages=messages,

+        outputFrequency=outputFrequency,

+        uncertainty=uncertainty,

+        checkpointOutFile=checkpointOutFile,

+        checkpointInterval=checkpointInterval,

+        checkpointInFile=checkpointInFile,

+        transposeData=transposeData,

+        subsetIndices=subsetIndices,

+        subsetDim=subsetDim,

+        BPPARAM=BPPARAM,

+        geneNames=geneNames,

+        sampleNames=sampleNames,

+        fixedPatterns=fixedPatterns,

+        whichMatrixFixed=whichMatrixFixed,

+        outputToFile=outputToFile,

+        workerID=workerID,

+        ...

+    )

 }

 #' Genome Wide CoGAPS

@@ -161,11 +183,31 @@ geneNames=NULL, sampleNames=NULL, matchedPatterns=NULL, ...)

 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,

-geneNames=NULL, sampleNames=NULL, matchedPatterns=NULL, ...)

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

+BPPARAM=NULL, geneNames=NULL, sampleNames=NULL, fixedPatterns=NULL,

+whichMatrixFixed='N', outputToFile=NULL, workerID=1, ...)

 {

     params@distributed <- "genome-wide"

-    CoGAPS(data, params, nThreads, messages, outputFrequency, uncertainty,

-        checkpointOutFile, checkpointInterval, checkpointInFile, transposeData,

-        BPPARAM, geneNames, sampleNames, matchedPatterns, ...)

+    CoGAPS(

+        data=data,

+        params=params,

+        nThreads=nThreads,

+        messages=messages,

+        outputFrequency=outputFrequency,

+        uncertainty=uncertainty,

+        checkpointOutFile=checkpointOutFile,

+        checkpointInterval=checkpointInterval,

+        checkpointInFile=checkpointInFile,

+        transposeData=transposeData,

+        subsetIndices=subsetIndices,

+        subsetDim=subsetDim,

+        BPPARAM=BPPARAM,

+        geneNames=geneNames,

+        sampleNames=sampleNames,

+        fixedPatterns=fixedPatterns,

+        whichMatrixFixed=whichMatrixFixed,

+        outputToFile=outputToFile,

+        workerID=workerID,

+        ...

+    )

 }

\ No newline at end of file

@@ -65,8 +65,8 @@ buildReport <- function()

 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,

-geneNames=NULL, sampleNames=NULL, matchedPatterns=NULL,

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

+geneNames=NULL, sampleNames=NULL, fixedPatterns=NULL, whichMatrixFixed='N',

 outputToFile=NULL, ...)

 {

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

@@ -79,82 +79,33 @@ outputToFile=NULL, ...)

         "checkpointInterval"=checkpointInterval,

         "checkpointInFile"=checkpointInFile,

         "transposeData"=transposeData,

+        "subsetData"=subsetData,

         "bpBackend"=BPPARAM,

-        "matchedPatterns"=matchedPatterns,

+        "fixedPatterns"=fixedPatterns,

+        "whichMatrixFixed"=whichMatrixFixed,

         "outputToFile"=outputToFile,

-        "whichMatrixFixed"=NULL # internal parameter

     )

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

-    # check file extension

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

-        stop("unsupported file extension for data")

-

-    # enforce the use of explicit subsets with manual pattern matching

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

-        stop("must provide explicit subsets when doing manual pattern matching")

-

-    # check uncertainty matrix

-    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))

-        stop("unsupported file extension for uncertainty")

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

-        stop("uncertainty must be a matrix unless data is a file path")

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

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

-

-    # check single cell parameter

-    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$gaps@distributed) & allParams$nThreads > 1)

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

-

-    # convert data to matrix

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

-        data <- data

-    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")

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

-        checkDataMatrix(data, uncertainty, allParams$gaps)

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

+    checkInputs(data, uncertainty, allParams)