@@ -17,6 +17,7 @@ export(celda_G)

 export(clusterProbability)

 export(clusters)

 export(compareCountMatrix)

+export(curveElbow)

 export(differentialExpression)

 export(distinct_colors)

 export(factorizeMatrix)

@@ -43,6 +44,8 @@ export(plotGridSearchPerplexity.celda_G)

 export(plotHeatmap)

 export(recodeClusterY)

 export(recodeClusterZ)

+export(recursiveSplitCell)

+export(recursiveSplitModule)

 export(resList)

 export(resamplePerplexity)

 export(runParams)

@@ -13,9 +13,9 @@

 #' @param split.on.last Integer. After `stop.iter` iterations have been performed without improvement, a heuristic will be applied to determine if a cell population should be reassigned and another cell population should be split into two clusters. If a split occurs, then `stop.iter` will be reset. Default TRUE.

 #' @param seed Integer. Passed to `set.seed()`. Default 12345. If NULL, no calls to `set.seed()` are made. 

 #' @param nchains Integer. Number of random cluster initializations. Default 3.  

-#' @param initialize Chararacter. One of 'random' or 'split'. With 'random', cells are randomly assigned to a clusters. With 'split' cell clusters will be recurssively split into two clusters using `celda_C` until the specified K is reached. Default 'random'.

-#' @param count.checksum "Character. An MD5 checksum for the `counts` matrix. Default NULL.

+#' @param z.initialize Chararacter. One of 'random', 'split', or 'predefined'. With 'random', cells are randomly assigned to a populations. With 'split', cells will be split into sqrt(K) populations and then each popluation will be subsequently split into another sqrt(K) populations. With 'predefined', values in `z.init` will be used to initialize `z`. Default 'split'.

 #' @param z.init Integer vector. Sets initial starting values of z. If NULL, starting values for each cell will be randomly sampled from `1:K`. 'z.init' can only be used when `initialize = 'random'`. Default NULL.

+#' @param count.checksum "Character. An MD5 checksum for the `counts` matrix. Default NULL.

 #' @param logfile Character. Messages will be redirected to a file named `logfile`. If NULL, messages will be printed to stdout.  Default NULL.

 #' @param verbose Logical. Whether to print log messages. Default TRUE. 

 #' @return An object of class `celda_C` with the cell population clusters stored in in `z`.

@@ -17,10 +17,11 @@

 #' @param split.on.last Integer. After `stop.iter` iterations have been performed without improvement, a heuristic will be applied to determine if a cell population or feature module should be reassigned and another cell population or feature module should be split into two clusters. If a split occurs, then 'stop.iter' will be reset. Default TRUE.

 #' @param seed Integer. Passed to `set.seed()`. Default 12345. If NULL, no calls to `set.seed()` are made.

 #' @param nchains Integer. Number of random cluster initializations. Default 3.  

-#' @param initialize Chararacter. One of 'random' or 'split'. With 'random', cells and features are randomly assigned to a clusters. With 'split' cell and feature clusters will be recurssively split into two clusters using `celda_C` and `celda_G`, respectively, until the specified K and L is reached. Default 'random'.

-#' @param count.checksum Character. An MD5 checksum for the `counts` matrix. Default NULL.

+#' @param z.initialize Chararacter. One of 'random', 'split', or 'predefined'. With 'random', cells are randomly assigned to a populations. With 'split', cells will be split into sqrt(K) populations and then each popluation will be subsequently split into another sqrt(K) populations. With 'predefined', values in `z.init` will be used to initialize `z`. Default 'split'.

+#' @param y.initialize Chararacter. One of 'random', 'split', or 'predefined'. With 'random', features are randomly assigned to a modules. With 'split', features will be split into sqrt(L) modules and then each module will be subsequently split into another sqrt(L) modules. With 'predefined', values in `y.init` will be used to initialize `y`. Default 'split'.

 #' @param z.init Integer vector. Sets initial starting values of z. If NULL, starting values for each cell will be randomly sampled from 1:K. 'z.init' can only be used when `initialize' = 'random'`. Default NULL.

 #' @param y.init Integer vector. Sets initial starting values of y. If NULL, starting values for each feature will be randomly sampled from 1:L. 'y.init' can only be used when `initialize = 'random'`. Default NULL.

+#' @param count.checksum Character. An MD5 checksum for the `counts` matrix. Default NULL.

 #' @param logfile Character. Messages will be redirected to a file named `logfile`. If NULL, messages will be printed to stdout.  Default NULL.

 #' @param verbose Logical. Whether to print log messages. Default TRUE. 

 #' @return An object of class `celda_CG` with the cell populations clusters stored in in `z` and feature module clusters stored in `y`.

@@ -13,9 +13,9 @@

 #' @param split.on.last Integer. After `stop.iter` iterations have been performed without improvement, a heuristic will be applied to determine if a cell population should be reassigned and another cell population should be split into two clusters. If a split occurs, then `stop.iter` will be reset. Default TRUE.

 #' @param seed Integer. Passed to `set.seed()`. Default 12345. If NULL, no calls to `set.seed()` are made.

 #' @param nchains Integer. Number of random cluster initializations. Default 3.  

-#' @param initialize Chararacter. One of 'random' or 'split'. With 'random', features are randomly assigned to a clusters. With 'split' cell and feature clusters will be recurssively split into two clusters using `celda_G()` until the specified L is reached. Default 'random'.

-#' @param count.checksum Character. An MD5 checksum for the `counts` matrix. Default NULL.

+#' @param y.initialize Chararacter. One of 'random', 'split', or 'predefined'. With 'random', features are randomly assigned to a modules. With 'split', features will be split into sqrt(L) modules and then each module will be subsequently split into another sqrt(L) modules. With 'predefined', values in `y.init` will be used to initialize `y`. Default 'split'.

 #' @param y.init Integer vector. Sets initial starting values of y. If NULL, starting values for each feature will be randomly sampled from `1:L`. `y.init` can only be used when `initialize = 'random'`. Default NULL.

+#' @param count.checksum Character. An MD5 checksum for the `counts` matrix. Default NULL.

 #' @param logfile Character. Messages will be redirected to a file named `logfile`. If NULL, messages will be printed to stdout.  Default NULL.

 #' @param verbose Logical. Whether to print log messages. Default TRUE. 

 #' @return An object of class `celda_G` with the feature module clusters stored in `y`.

@@ -7,7 +7,7 @@

 celda_C(counts, sample.label = NULL, K, alpha = 1, beta = 1,

   algorithm = c("EM", "Gibbs"), stop.iter = 10, max.iter = 200,

   split.on.iter = 10, split.on.last = TRUE, seed = 12345,

-  nchains = 3, initialize = c("random", "split"),

+  nchains = 3, z.initialize = c("split", "random", "predefined"),

   count.checksum = NULL, z.init = NULL, logfile = NULL,

   verbose = TRUE)

 }

@@ -36,7 +36,7 @@ celda_C(counts, sample.label = NULL, K, alpha = 1, beta = 1,

 \item{nchains}{Integer. Number of random cluster initializations. Default 3.}

-\item{initialize}{Chararacter. One of 'random' or 'split'. With 'random', cells are randomly assigned to a clusters. With 'split' cell clusters will be recurssively split into two clusters using `celda_C` until the specified K is reached. Default 'random'.}

+\item{z.initialize}{Chararacter. One of 'random', 'split', or 'predefined'. With 'random', cells are randomly assigned to a populations. With 'split', cells will be split into sqrt(K) populations and then each popluation will be subsequently split into another sqrt(K) populations. With 'predefined', values in `z.init` will be used to initialize `z`. Default 'split'.}

 \item{count.checksum}{"Character. An MD5 checksum for the `counts` matrix. Default NULL.}

@@ -8,8 +8,10 @@ celda_CG(counts, sample.label = NULL, K, L, alpha = 1, beta = 1,

   delta = 1, gamma = 1, algorithm = c("EM", "Gibbs"),

   stop.iter = 10, max.iter = 200, split.on.iter = 10,

   split.on.last = TRUE, seed = 12345, nchains = 3,

-  initialize = c("random", "split"), count.checksum = NULL,

-  z.init = NULL, y.init = NULL, logfile = NULL, verbose = TRUE)

+  z.initialize = c("split", "random", "predefined"),

+  y.initialize = c("split", "random", "predefined"),

+  count.checksum = NULL, z.init = NULL, y.init = NULL,

+  logfile = NULL, verbose = TRUE)

 }

 \arguments{

 \item{counts}{Integer matrix. Rows represent features and columns represent cells.}

@@ -42,7 +44,9 @@ celda_CG(counts, sample.label = NULL, K, L, alpha = 1, beta = 1,

 \item{nchains}{Integer. Number of random cluster initializations. Default 3.}

-\item{initialize}{Chararacter. One of 'random' or 'split'. With 'random', cells and features are randomly assigned to a clusters. With 'split' cell and feature clusters will be recurssively split into two clusters using `celda_C` and `celda_G`, respectively, until the specified K and L is reached. Default 'random'.}

+\item{z.initialize}{Chararacter. One of 'random', 'split', or 'predefined'. With 'random', cells are randomly assigned to a populations. With 'split', cells will be split into sqrt(K) populations and then each popluation will be subsequently split into another sqrt(K) populations. With 'predefined', values in `z.init` will be used to initialize `z`. Default 'split'.}

+

+\item{y.initialize}{Chararacter. One of 'random', 'split', or 'predefined'. With 'random', features are randomly assigned to a modules. With 'split', features will be split into sqrt(L) modules and then each module will be subsequently split into another sqrt(L) modules. With 'predefined', values in `y.init` will be used to initialize `y`. Default 'split'.}

 \item{count.checksum}{Character. An MD5 checksum for the `counts` matrix. Default NULL.}

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

 \usage{

 celda_G(counts, L, beta = 1, delta = 1, gamma = 1, stop.iter = 10,

   max.iter = 200, split.on.iter = 10, split.on.last = TRUE,

-  seed = 12345, nchains = 3, initialize = c("random", "split"),

+  seed = 12345, nchains = 3, y.initialize = c("split", "random"),

   count.checksum = NULL, y.init = NULL, logfile = NULL,

   verbose = TRUE)

 }

@@ -33,7 +33,7 @@ celda_G(counts, L, beta = 1, delta = 1, gamma = 1, stop.iter = 10,

 \item{nchains}{Integer. Number of random cluster initializations. Default 3.}

-\item{initialize}{Chararacter. One of 'random' or 'split'. With 'random', features are randomly assigned to a clusters. With 'split' cell and feature clusters will be recurssively split into two clusters using `celda_G()` until the specified L is reached. Default 'random'.}

+\item{y.initialize}{Chararacter. One of 'random', 'split', or 'predefined'. With 'random', features are randomly assigned to a modules. With 'split', features will be split into sqrt(L) modules and then each module will be subsequently split into another sqrt(L) modules. With 'predefined', values in `y.init` will be used to initialize `y`. Default 'split'.}

 \item{count.checksum}{Character. An MD5 checksum for the `counts` matrix. Default NULL.}

new file mode 100644

@@ -0,0 +1,62 @@

+% Generated by roxygen2: do not edit by hand

+% Please edit documentation in R/recursiveSplit.R

+\name{recursiveSplitCell}

+\alias{recursiveSplitCell}

+\title{Recursive cell splitting}

+\usage{

+recursiveSplitCell(counts, sample.label = NULL, initial.K = 5,

+  max.K = 25, y.init = NULL, alpha = 1, beta = 1, delta = 1,

+  gamma = 1, min.cell = 3, perplexity = TRUE, seed = 12345,

+  logfile = NULL, verbose = TRUE)

+}

+\arguments{

+\item{counts}{Integer matrix. Rows represent features and columns represent cells.}

+

+\item{sample.label}{Vector or factor. Denotes the sample label for each cell (column) in the count matrix.}

+

+\item{initial.K}{Integer. Minimum number of cell populations to try.}

+

+\item{max.K}{Integer. Maximum number of cell populations to try.}

+

+\item{y.init}{Integer vector. Module labels for features. Cells will be clusteredusing the `celda_CG` model based on the modules specified in `y.init` rather than the counts of individual features. While the feature module labels will be initialized to `y.init`, they will be allowed to move within each model with a new K.}

+

+\item{alpha}{Numeric. Concentration parameter for Theta. Adds a pseudocount to each cell population in each sample. Default 1.}

+

+\item{beta}{Numeric. Concentration parameter for Phi. Adds a pseudocount to each feature in each cell (if `y.init` is not used) or to each module in each cell population (if `y.init` is set). Default 1.}

+

+\item{delta}{Numeric. Concentration parameter for Psi. Adds a pseudocount to each feature in each module. Only used if `y.init` is set. Default 1.}

+

+\item{gamma}{Numeric. Concentration parameter for Eta. Adds a pseudocount to the number of features in each module. Only used if `y.init` is set. Default 1.}

+

+\item{min.cell}{Integer. Only attempt to split cell populations with at least this many cells.}

+

+\item{perplexity}{Logical. Whether to calculate perplexity for each model. If FALSE, then perplexity can be calculated later with `resamplePerplexity()`. Default TRUE.}

+

+\item{seed}{Integer. Passed to `set.seed()`. Default 12345. If NULL, no calls to `set.seed()` are made.}

+

+\item{logfile}{Character. Messages will be redirected to a file named `logfile`. If NULL, messages will be printed to stdout.  Default NULL.}

+

+\item{verbose}{Logical. Whether to print log messages. Default TRUE.}

+}

+\value{

+Object of class `celda_list`, which contains results for all model parameter combinations and summaries of the run parameters

+}

+\description{

+Uses the `celda_C` model to cluster cells into population for range of possible K's. The cell population labels of the previous "K-1" model are used as the initial values in the current model with K cell populations. The best split of an existing cell population is found to create the K-th cluster. This procedure is much faster than randomly initializing each model with a different K. If module labels for each feature are given in 'y.init', the `celda_CG` model will be used to split cell populations based on those modules instead of individual features. Module labels will also be updated during sampling and thus may end up slightly different than `y.init`.

+}

+\examples{

+## Create models that range from K=3 to K=10 by recursively splitting cell populations into two to produce `celda_C` cell clustering models

+testZ = recursiveSplitCell(celda.C.sim$counts, initial.K = 3, max.K=10)

+

+## Alternatively, first identify features modules usinge `recursiveSplitModule()`

+module.split = recursiveSplitModule(celda.CG.sim$counts, initial.L = 3, max.L=20)

+plotGridSearchPerplexity(module.split)

+module.split.select = subsetCeldaList(module.split, list(L=10))

+Then, use module labels for initialization in `recursiveSplitCell()` to produce `celda_CG` bi-clustering models

+cell.split = recursiveSplitCell(celda.CG.sim$counts, initial.K = 3, max.K=20, y.init = clusters(module.split.select)$y)

+plotGridSearchPerplexity(cell.split) 

+celda.mod = subsetCeldaList(cell.split, list(K=5, L=10))

+}

+\seealso{

+`recursiveSplitModule()` for recursive splitting of cell populations.

+}

new file mode 100644

@@ -0,0 +1,57 @@

+% Generated by roxygen2: do not edit by hand

+% Please edit documentation in R/recursiveSplit.R

+\name{recursiveSplitModule}

+\alias{recursiveSplitModule}

+\title{Recursive module splitting}

+\usage{

+recursiveSplitModule(counts, initial.L = 10, max.L = 100,

+  temp.K = 100, z.init = NULL, beta = 1, delta = 1, gamma = 1,

+  min.feature = 3, perplexity = TRUE, seed = 12345, verbose = TRUE,

+  logfile = NULL)

+}

+\arguments{

+\item{counts}{Integer matrix. Rows represent features and columns represent cells.}

+

+\item{initial.L}{Integer. Minimum number of modules to try.}

+

+\item{max.L}{Integer. Maximum number of modules to try.}

+

+\item{z.init}{Integer vector. Collapse cells to cell populations based on labels in `z.init` and then perform module splitting. If NULL, no collapasing will be performed unless `temp.z` is specified. Default NULL.}

+

+\item{beta}{Numeric. Concentration parameter for Phi. Adds a pseudocount to each feature module in each cell. Default 1.}

+

+\item{delta}{Numeric. Concentration parameter for Psi. Adds a pseudocount to each feature in each module. Default 1.}

+

+\item{gamma}{Numeric. Concentration parameter for Eta. Adds a pseudocount to the number of features in each module. Default 1.}

+

+\item{min.feature}{Integer. Only attempt to split modules with at least this many features.}

+

+\item{perplexity}{Logical. Whether to calculate perplexity for each model. If FALSE, then perplexity can be calculated later with `resamplePerplexity()`. Default TRUE.}

+

+\item{seed}{Integer. Passed to `set.seed()`. Default 12345. If NULL, no calls to `set.seed()` are made.}

+

+\item{verbose}{Logical. Whether to print log messages. Default TRUE.}

+

+\item{logfile}{Character. Messages will be redirected to a file named `logfile`. If NULL, messages will be printed to stdout.  Default NULL.}

+

+\item{temp.z}{Integer. Number of temporary cell populations to identify and use in module splitting. Only used if `z.init=NULL` Collapsing cells to a relatively smaller number of cell popluations will increase the speed of module clustering and tend to produce better modules. This number should be larger than the number of true cell populations expected in the dataset. Default 100.}

+}

+\value{

+Object of class `celda_list`, which contains results for all model parameter combinations and summaries of the run parameters

+}

+\description{

+Uses the `celda_G` model to cluster features into modules for a range of possible L's. The module labels of the previous "L-1" model are used as the initial values in the current model with L modules. The best split of an existing module is found to create the L-th module. This procedure is much faster than randomly initializing each model with a different L.

+}

+\examples{

+## Create models that range from L=3 to L=20 by recursively splitting modules into two

+module.split = recursiveSplitModule(celda.CG.sim$counts, initial.L = 3, max.L=20)

+

+## Example results with perplexity

+plotGridSearchPerplexity(module.split)

+

+## Select model for downstream analysis

+celda.mod = subsetCeldaList(module.split, list(L=10))

+}

+\seealso{

+`recursiveSplitCell()` for recursive splitting of cell populations.

+}