clean up documentation

R/SOUP.R

@@ -6,7 +6,7 @@
 #' @param expr a cell-by-gene expression matrix, either the raw counts or log-transformed expressions. 
 #' @param Ks number of clusters, can be a single integer or a list of integers.
 #' @param type "log" if \code{expr} has been normalized and log-transformed (default),
-#'     or "count" (default) \code{expr} contains the raw counts.
+#'     or "count" if \code{expr} contains the raw counts.
 #'     It is recommended to use the log scale, which usually gives better results in practice.
 #' @param i.pure (optional) the indices of the pure cells. By default is \code{NULL}, and SOUP will infer the pure list.
 #' If the list is already known (for example, from previous runs), then providing it will reduce the computation time.
@@ -24,13 +24,7 @@
 #'   \item{i.pure}{the indices of pure cells with the highest purity scores.}
 #' }
 #' 
-#' @examples 
-#' select.genes = zeisel$select.genes
-#' counts = zeisel$counts[, colnames(counts) %in% select.genes]
-#' soup.out = SOUP(counts, Ks=7, type="count")
-#' 
 #' @export  
-
 SOUP <- function(expr, Ks=3, 
                  type="log", 
                  i.pure=NULL, ext.prop=NULL, pure.prop=0.5,
@@ -108,7 +102,7 @@ SOUP <- function(expr, Ks=3,
 #' 
 #' @param expr a cell-by-gene expression matrix, either the raw counts or log-transformed expressions. 
 #' @param type "log" if \code{expr} has been normalized and log-transformed (default),
-#'     or "count" (default) \code{expr} contains the raw counts.
+#'     or "count" if \code{expr} contains the raw counts.
 #' @param ext.prop (optional) the proportion of extreme neighbors for each cell, such that \code{ext.prop*n.cells} is roughly the number of pure cells \emph{per cluster}. 
 #' By default, \code{ext.prop=0.1} for less than 1,000 cells, and \code{ext.prop=0.05} for larger datasets.
 #' @param pure.prop (optional) the proportion of pure cells in the data. By default \code{pure.prop=0.5}.
@@ -257,7 +251,11 @@ getTheta <- function(expr, i.pure, pure.cluster, G) {
 
 }
 
-
+#' Clean up membership matrix
+#' 
+#' @param theta The estimated raw theta
+#' 
+#' @return The cleaned-up membership matrix.
 projMembership <- function(theta) {
   membership = theta
   membership[membership < 0] = 0

R/SOUPtime.R

@@ -1,5 +1,5 @@
 
-#' Estimate Developmental Timeline
+#' Estimate developmental trajectory
 #' 
 #' Estimate the developmental timeline for cells from SOUP soft membership.
 #' 
@@ -37,7 +37,7 @@ getTimeline <- function(membership, centers,
   return(timeline)
 }
 
-#' Order Clusters
+#' Order clusters
 #' 
 #' Re-order cluster labels, starting from \code{k.start}, 
 #' and consecutively append the next one with the highest correlation in cluster centers.

R/cvSOUP.R

@@ -1,20 +1,20 @@
-#' Cross Validation for SOUP
+#' Cross validation for SOUP
 #' 
 #' @param expr A cell-by-gene expression matrix, either the raw counts or log-transformed expressions. 
 #' @param type "log" if \code{expr} has been normalized and log-transformed (default),
 #'     or "count" (default) \code{expr} contains the raw counts.
-#' @param nfold Number of folds
-#' @param nCV Number of repetitions
 #' @param Ks A sequence of cluster numbers
-#' @param mc.cores Number of cores for parallelization
-#' @param verbose Whether to print progress
+#' @param nfold (optional) Number of folds, default is 10
+#' @param nCV (optional) Number of repetitions, default is 10
+#' @param mc.cores (optional) Number of cores for parallelization, default is 1 without parallelization
+#' @param seeds (optional) A list of seeds to be used, with length nCV, default is NULL
+#' @param verbose (optional) Whether to print progress, default is TRUE
 #' 
 #' @export
 #' 
-cvSOUP <- function(expr, type="log", 
-                   nfold=10, nCV=10, Ks=c(2:10), mc.cores=10,
-                   seeds=NULL,
-                   verbose=TRUE) {
+cvSOUP <- function(expr, type="log", Ks=c(2:10), 
+                   nfold=10, nCV=10, mc.cores=1,
+                   seeds=NULL, verbose=TRUE) {
 
   cv.errors = matrix(NA, nrow=nCV, ncol=length(Ks))
   cv.sds = matrix(NA, nrow=nCV, ncol=length(Ks))
@@ -48,20 +48,19 @@ cvSOUP <- function(expr, type="log",
               K.cv = K.cv))
 }
 
-#' Compute Cross Validation Errors
+#' Compute cross validation errors
 #' 
 #' @param expr A cell-by-gene expression matrix, either the raw counts or log-transformed expressions. 
 #' @param type "log" if \code{expr} has been normalized and log-transformed (default),
 #'     or "count" (default) \code{expr} contains the raw counts.
-#' @param nfold Number of folds
 #' @param Ks A sequence of cluster numbers
-#' @param seed (optional) random seed
-#' @param mc.cores Number of cores for parallelization
+#' @param nfold (optional) Number of folds, default is 10
+#' @param seed (optional) random seed, default is NULL
+#' @param mc.cores (optional) Number of cores for parallelization, default is 1 without parallelization
 #' 
 #' @export
-cv.error.SOUP <- function(expr, type="log", 
-                          nfold=10, Ks=c(2:10), seed=NULL,
-                          mc.cores=2) {
+cv.error.SOUP <- function(expr, type="log", Ks=c(2:10), 
+                          nfold=10, seed=NULL, mc.cores=1) {
 
   ## cross validation
   doCV <- function(fold, nfold, i.permute.ind, 
@@ -116,6 +115,10 @@ cv.error.SOUP <- function(expr, type="log",
 
 #' Predict the membership for new data points
 #' 
+#' @param new.expr cell-by-gene expression matrix
+#' @param t.centers transposed center matrix, n.gene-by-K
+#' 
+#' @return The predicted membership matrix.
 #' @export
 #' 
 predictTheta <- function(new.expr, t.centers) {

R/geneSelect.R

@@ -4,7 +4,7 @@
 #' 
 #' @param expr a cell-by-gene expression matrix, either the raw counts or log-transformed expressions. 
 #' @param type "count" if \code{expr} contains the raw counts (default), 
-#'      or "log" if \code{expr} has been normalized and log-transformed (default).
+#'      or "log" if \code{expr} has been normalized and log-transformed.
 #' @param SPCA boolean, whether to use SPCA or not.
 #' @param DESCEND boolean, whether to use DESCEND or not.
 #' @param n.cores the number of cores used for parallel computing of DESCEND. 
@@ -86,9 +86,9 @@ selectGenes <- function(expr, type="count",
 #' Select highly variable genes for clustering using DESCEND.
 #' 
 #' @param counts the cell-by-gene expression counts. 
-#'    Note that DESCEND uses a Poisson model, so the count data should be provided (without normalization or log transformation).
+#'    Note that DESCEND uses a Poisson model, so the count data should be provided.
 #' @param n.cores the number of cores used for parallel computing. DESCEND can be slow so parallelization is highly recommended.
-#' @param threshold the threshold for Gini index. Higer threshold leads to fewer selected genes.
+#' @param threshold (optional) the threshold for Gini index, default is 3. Higer threshold leads to fewer selected genes.
 #' 
 #' @return A list containing \describe{
 #'   \item{select.genes}{the names of selected genes, ordered by decreasing scores.}

R/utils_plot.R

@@ -48,7 +48,7 @@ heatmapKseq <- function(memberships, Ks, cell.type, ref.lab="Reference",
 }
 
 
-#' Get the SOUP majority matrix
+#' Get the SOUP hard assignment matrix
 #' 
 #' @export
 #' 
@@ -169,7 +169,7 @@ plotContTable <- function(est_label, true_label, short.names=NULL, xlab="Referen
   return(g)
 }
 
-#' Plot Gene Expression along Trajectory
+#' Plot gene expression along trajectory
 #' 
 #' @param expr The cell-by-gene expression matrix to be visualized
 #' @param marker.gene The gene to be visualized; must be one of the columns of \code{expr}
@@ -203,7 +203,7 @@ plotGeneTimeline <- function(expr, marker.gene, timeline,
   return(g)
 }
 
-#' Plot Multiple Gene Expressions along Trajectory
+#' Plot multiple gene expressions along trajectory
 #' 
 #' Expression levels of multiple genes along trajectory, arranged on a grid of plots.
 #'