@@ -165,9 +165,9 @@ recodeClusterZ <- function(sce, from, to, altExpName = "featureSubset") {

     new.clusters <- plyr::mapvalues(celdaClusters(sce,

                                                   altExpName = altExpName),

                                     from, to)

-    new.clusters <- factor(new.clusters, levels = 

+    new.clusters <- factor(new.clusters, levels =

                              sort(as.numeric(unique(new.clusters))))

-    

+

     celdaClusters(sce, altExpName = altExpName) <- new.clusters

     return(sce)

 }

@@ -218,9 +218,9 @@ recodeClusterY <- function(sce, from, to, altExpName = "featureSubset") {

     new.clusters <- plyr::mapvalues(celdaModules(sce,

                                                   altExpName = altExpName),

                                   from, to)

-    new.clusters <- factor(new.clusters, levels = 

+    new.clusters <- factor(new.clusters, levels =

                              sort(as.numeric(unique(new.clusters))))

-  

+

     celdaModules(sce, altExpName = altExpName) <- plyr::mapvalues(

         celdaModules(sce, altExpName = altExpName), from, to)

     return(sce)

@@ -26,13 +26,17 @@

 #' should be considered different batches. Default NULL.

 #' @param background A numeric matrix of counts or a

 #' \linkS4class{SingleCellExperiment} with the matrix located in the assay

-#' slot under \code{assayName}. It should have the same structure as \code{x}

-#' except it contains the matrix of empty droplets instead of cells. When

-#' supplied, empirical distribution of transcripts from these empty droplets

+#' slot under \code{assayName}. It should have the same data format as \code{x}

+#' except it contains the empty droplets instead of cells. When supplied,

+#' empirical distribution of transcripts from these empty droplets

 #' will be used as the contamination distribution. Default NULL.

 #' @param bgAssayName Character. Name of the assay to use if \code{background}

 #' is a \linkS4class{SingleCellExperiment}. Default to same as

 #' \code{assayName}.

+#' @param bgBatch Numeric or character vector. Batch labels for

+#' \code{background}. Its unique values should be the same as those in

+#' \code{batch}, such that each batch of cells have their corresponding batch

+#' of empty droplets as background, pointed by this parameter. Default to NULL.

 #' @param maxIter Integer. Maximum iterations of the EM algorithm. Default 500.

 #' @param convergence Numeric. The EM algorithm will be stopped if the maximum

 #' difference in the contamination estimates between the previous and

@@ -150,6 +154,7 @@ setMethod("decontX", "SingleCellExperiment", function(x,

                                                       batch = NULL,

                                                       background = NULL,

                                                       bgAssayName = NULL,

+                                                      bgBatch = NULL,

                                                       maxIter = 500,

                                                       delta = c(10, 10),

                                                       estimateDelta = TRUE,

@@ -163,8 +168,16 @@ setMethod("decontX", "SingleCellExperiment", function(x,

   countsBackground <- NULL

   if (!is.null(background)) {

     # Remove cells with the same ID between x and the background matrix

-    background <- .checkBackground(x = x, background = background,

-                                   logfile = logfile, verbose = verbose)

+    # Also update bgBatch when background is updated and bgBatch is not null

+    temp <- .checkBackground(x = x,

+                             background = background,

+                             bgBatch = bgBatch,

+                             logfile = logfile,

+                             verbose = verbose)

+

+    background <- temp$background

+    bgBatch <- temp$bgBatch

+

     if (is.null(bgAssayName)) {

       bgAssayName <- assayName

     }

@@ -178,6 +191,7 @@ setMethod("decontX", "SingleCellExperiment", function(x,

     z = z,

     batch = batch,

     countsBackground = countsBackground,

+    batchBackground = bgBatch,

     maxIter = maxIter,

     convergence = convergence,

     iterLogLik = iterLogLik,

@@ -230,6 +244,7 @@ setMethod("decontX", "ANY", function(x,

                                      z = NULL,

                                      batch = NULL,

                                      background = NULL,

+                                     bgBatch = NULL,

                                      maxIter = 500,

                                      delta = c(10, 10),

                                      estimateDelta = TRUE,

@@ -244,8 +259,16 @@ setMethod("decontX", "ANY", function(x,

   countsBackground <- NULL

   if (!is.null(background)) {

     # Remove cells with the same ID between x and the background matrix

-    background <- .checkBackground(x = x, background = background,

-                                   logfile = logfile, verbose = verbose)

+    # Also update bgBatch when background is updated and bgBatch is not null

+    temp <- .checkBackground(x = x,

+                             background = background,

+                             bgBatch = bgBatch,

+                             logfile = logfile,

+                             verbose = verbose)

+

+    background <- temp$background

+    bgBatch <- temp$bgBatch

+

   }

   .decontX(

@@ -253,6 +276,7 @@ setMethod("decontX", "ANY", function(x,

     z = z,

     batch = batch,

     countsBackground = countsBackground,

+    batchBackground = bgBatch,

     maxIter = maxIter,

     convergence = convergence,

     iterLogLik = iterLogLik,

@@ -335,6 +359,7 @@ setMethod(

                      z = NULL,

                      batch = NULL,

                      countsBackground = NULL,

+                     batchBackground = NULL,

                      maxIter = 200,

                      convergence = 0.001,

                      iterLogLik = 10,

@@ -365,6 +390,7 @@ setMethod(

   runParams <- list(

     z = z,

     batch = batch,

+    batchBackground = batchBackground,

     maxIter = maxIter,

     delta = delta,

     estimateDelta = estimateDelta,

@@ -382,7 +408,7 @@ setMethod(

   nC <- ncol(counts)

   allCellNames <- colnames(counts)

-  ## Set up final deconaminated matrix

+  ## Set up final decontaminated matrix

   estRmat <- Matrix::Matrix(

     data = 0,

     ncol = totalCells,

@@ -394,8 +420,32 @@ setMethod(

   ## Generate batch labels if none were supplied

   if (is.null(batch)) {

     batch <- rep("all_cells", nC)

+

+    # If batch null, bgBatch has to be null

+    if (!is.null(batchBackground)) {

+      stop(

+        "When experiment default to no bacth, background should ",

+        "also default to no batch."

+      )

+    }

+

+    if (!is.null(countsBackground)) {

+      batchBackground <- rep("all_cells", ncol(countsBackground))

+    }

+  } else {

+

+    # If batch not null and countsBackground supplied,

+    # user has to supply batchBackground as well

+    if (!is.null(countsBackground) & is.null(batchBackground)) {

+      stop(

+        "Cell batch, and background are supplied. Please also ",

+        "supply background batch."

+      )

+    }

+

   }

   runParams$batch <- batch

+  runParams$batchBackground <- batchBackground

   batchIndex <- unique(batch)

   ## Set result lists upfront for all cells from different batches

@@ -428,6 +478,7 @@ setMethod(

     zBat <- NULL

     countsBat <- counts[, batch == bat]

+    bgBat <- countsBackground[, batchBackground == bat]

     ## Convert to sparse matrix

     if (!inherits(countsBat, "dgCMatrix")) {

@@ -440,9 +491,9 @@ setMethod(

       )

       countsBat <- methods::as(countsBat, "dgCMatrix")

     }

-    if (!is.null(countsBackground)) {

-      if (!inherits(countsBackground, "dgCMatrix")) {

-        countsBackground <- methods::as(countsBackground, "dgCMatrix")

+    if (!is.null(bgBat)) {

+      if (!inherits(bgBat, "dgCMatrix")) {

+        bgBat <- methods::as(bgBat, "dgCMatrix")

       }

     }

@@ -454,7 +505,7 @@ setMethod(

         counts = countsBat,

         z = zBat,

         batch = bat,

-        countsBackground = countsBackground,

+        countsBackground = bgBat,

         maxIter = maxIter,

         delta = delta,

         estimateDelta = estimateDelta,

@@ -473,7 +524,7 @@ setMethod(

           counts = countsBat,

           z = zBat,

           batch = bat,

-          countsBackground = countsBackground,

+          countsBackground = bgBat,

           maxIter = maxIter,

           delta = delta,

           estimateDelta = estimateDelta,

@@ -489,7 +540,7 @@ setMethod(

     }

     ## Try to convert class of new matrix to class of original matrix

-    

+

     .logMessages(

       date(),

       ".. Calculating final decontaminated matrix",

@@ -561,7 +612,7 @@ setMethod(

       append = TRUE,

       verbose = verbose

     )

-    

+

     ## Determine class of seed in DelayedArray

     seed.class <- unique(DelayedArray::seedApply(counts, class))[[1]]

     if (seed.class == "HDF5ArraySeed") {

@@ -1367,9 +1418,11 @@ simulateContamination <- function(C = 300,

 }

-.checkBackground <- function(x, background, logfile = NULL, verbose = FALSE) {

+.checkBackground <- function(x, background, bgBatch,

+                             logfile = NULL, verbose = FALSE) {

   # Remove background barcodes that have already appeared in x

-  if(!is.null(colnames(background))) {

+  # If bgBatch param is supplied, also remove duplicate bgBatch

+  if (!is.null(colnames(background))) {

     dupBarcode <- colnames(background) %in% colnames(x)

   } else {

     dupBarcode <- FALSE

@@ -1379,7 +1432,7 @@ simulateContamination <- function(C = 300,

             " Please ensure that no true cells are included in the background ",

             "matrix. Otherwise, results will be incorrect.")

   }

-  

+

   if (any(dupBarcode)) {

     .logMessages(

       date(),

@@ -1392,6 +1445,20 @@ simulateContamination <- function(C = 300,

       verbose = verbose

     )

     background <- background[, !(dupBarcode), drop = FALSE]

+

+    if (!is.null(bgBatch)) {

+      if (length(bgBatch) != length(dupBarcode)) {

+        stop(

+          "Length of bgBatch must be equal to the number of columns",

+          "of background matrix."

+          )

+      }

+      bgBatch <- bgBatch[!(dupBarcode)]

+    }

   }

-  return(background)

+

+  re <- list(background = background,

+            bgBatch = bgBatch)

+

+  return(re)

 }

@@ -15,6 +15,7 @@ decontX(x, ...)

   batch = NULL,

   background = NULL,

   bgAssayName = NULL,

+  bgBatch = NULL,

   maxIter = 500,

   delta = c(10, 10),

   estimateDelta = TRUE,

@@ -32,6 +33,7 @@ decontX(x, ...)

   z = NULL,

   batch = NULL,

   background = NULL,

+  bgBatch = NULL,

   maxIter = 500,

   delta = c(10, 10),

   estimateDelta = TRUE,

@@ -72,15 +74,20 @@ should be considered different batches. Default NULL.}

 \item{background}{A numeric matrix of counts or a

 \linkS4class{SingleCellExperiment} with the matrix located in the assay

-slot under \code{assayName}. It should have the same structure as \code{x}

-except it contains the matrix of empty droplets instead of cells. When

-supplied, empirical distribution of transcripts from these empty droplets

+slot under \code{assayName}. It should have the same data format as \code{x}

+except it contains the empty droplets instead of cells. When supplied,

+empirical distribution of transcripts from these empty droplets

 will be used as the contamination distribution. Default NULL.}

 \item{bgAssayName}{Character. Name of the assay to use if \code{background}

 is a \linkS4class{SingleCellExperiment}. Default to same as

 \code{assayName}.}

+\item{bgBatch}{Numeric or character vector. Batch labels for

+\code{background}. Its unique values should be the same as those in

+\code{batch}, such that each batch of cells have their corresponding batch

+of empty droplets as background, pointed by this parameter. Default to NULL.}

+

 \item{maxIter}{Integer. Maximum iterations of the EM algorithm. Default 500.}

 \item{delta}{Numeric Vector of length 2. Concentration parameters for

@@ -6,6 +6,11 @@

 using namespace Rcpp;

+#ifdef RCPP_USE_GLOBAL_ROSTREAM

+Rcpp::Rostream<true>&  Rcpp::Rcout = Rcpp::Rcpp_cout_get();

+Rcpp::Rostream<false>& Rcpp::Rcerr = Rcpp::Rcpp_cerr_get();

+#endif

+

 // decontXEM

 Rcpp::List decontXEM(const Eigen::MappedSparseMatrix<double>& counts, const NumericVector& counts_colsums, const NumericVector& theta, const bool& estimate_eta, const NumericMatrix& eta, const NumericMatrix& phi, const IntegerVector& z, const bool& estimate_delta, const NumericVector& delta, const double& pseudocount);

 RcppExport SEXP _celda_decontXEM(SEXP countsSEXP, SEXP counts_colsumsSEXP, SEXP thetaSEXP, SEXP estimate_etaSEXP, SEXP etaSEXP, SEXP phiSEXP, SEXP zSEXP, SEXP estimate_deltaSEXP, SEXP deltaSEXP, SEXP pseudocountSEXP) {