Modify splatSimulate to use SplatParams

DESCRIPTION

 Package: splatter
 Type: Package
 Title: Simple Simulation of Single-cell RNA Sequencing Data
-Version: 0.6.7
+Version: 0.6.8
 Date: 2016-10-13
 Author: Luke Zappia
 Authors@R: as.person(c(

NAMESPACE

@@ -13,14 +13,31 @@ export(newSplatParams)
 export(setParam)
 export(setParams)
 export(simpleSimulate)
+export(splatSimulate)
+export(splatSimulateGroups)
+export(splatSimulatePaths)
+export(splatSimulateSingle)
 exportClasses(SimpleParams)
 exportClasses(SplatParams)
+importFrom(Biobase,"assayData<-")
+importFrom(Biobase,"fData<-")
+importFrom(Biobase,"pData<-")
+importFrom(Biobase,assayData)
+importFrom(Biobase,fData)
+importFrom(Biobase,pData)
 importFrom(checkmate,checkFlag)
 importFrom(checkmate,checkInt)
 importFrom(checkmate,checkIntegerish)
 importFrom(checkmate,checkNumber)
 importFrom(checkmate,checkNumeric)
+importFrom(scater,counts)
 importFrom(scater,newSCESet)
 importFrom(stats,median)
+importFrom(stats,rbinom)
+importFrom(stats,rchisq)
 importFrom(stats,rgamma)
+importFrom(stats,rlnorm)
 importFrom(stats,rnbinom)
+importFrom(stats,rnorm)
+importFrom(stats,rpois)
+importFrom(stats,runif)

R/splat-estimate.R

 #' Estimate Splatter simulation parameters
 #'
 #' Estimate simulation parameters for the Splatter simulation from a real
-#' dataset.
+#' dataset. See the individual estimation functions for more details on how this
+#' is done.
 #'
 #' @param counts either a counts matrix or an SCESet object containing count
 #'        data to estimate parameters from.
 #' @param params SplatParams object to store estimated values in.
 #'
-#' @details
+#' @seealso
+#' \code{\link{estSplatMean}},  \code{\link{estSplatLib}},
+#' \code{\link{estSplatOutlier}}, \code{\link{estSplatBCV}},
+#' \code{\link{estSplatDropout}}
 #'
 #' @return SplatParams object containing the estimated parameters.
 #'

man/bridge.Rd

+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/splat-simulate.R
+\name{bridge}
+\alias{bridge}
+\title{Brownian bridge}
+\usage{
+bridge(x = 0, y = 0, N = 5, n = 100, sigma.fac = 0.8)
+}
+\arguments{
+\item{x}{starting value.}
+
+\item{y}{end value.}
+
+\item{N}{number of steps in random walk.}
+
+\item{n}{number of points in smoothed bridge.}
+
+\item{sigma.fac}{multiplier specifying how extreme each step can be.}
+}
+\value{
+Vector of length n following a path from x to y.
+}
+\description{
+Calculate a smoothed Brownian bridge between two points. A Brownian bridge is
+a random walk with fixed end points.
+}
+

man/estSplatMeans.Rd → man/estSplatMean.Rd

 % Generated by roxygen2: do not edit by hand
 % Please edit documentation in R/splat-estimate.R
-\name{estSplatMeans}
-\alias{estSplatMeans}
+\name{estSplatMean}
+\alias{estSplatMean}
 \title{Estimate Splatter mean parameters}
 \usage{
-estSplatMeans(norm.counts, params)
+estSplatMean(norm.counts, params)
 }
 \arguments{
 \item{norm.counts}{library size normalised counts matrix.}

man/estimateSimpleParams.Rd

@@ -6,15 +6,15 @@
 \alias{estimateSimpleParams.matrix}
 \title{Estimate simple simulation parameters}
 \usage{
-estimateSimpleParams(data, params = newSimpleParams())
+estimateSimpleParams(counts, params = newSimpleParams())
 
-\method{estimateSimpleParams}{SCESet}(data, params = newSimpleParams())
+\method{estimateSimpleParams}{SCESet}(counts, params = newSimpleParams())
 
-\method{estimateSimpleParams}{matrix}(data, params = newSimpleParams())
+\method{estimateSimpleParams}{matrix}(counts, params = newSimpleParams())
 }
 \arguments{
-\item{data}{either a counts matrix or an SCESet object containing count data
-to estimate parameters from.}
+\item{counts}{either a counts matrix or an SCESet object containing count
+data to estimate parameters from.}
 
 \item{params}{SimpleParams object to store estimated values in.}
 }

man/estimateSplatParams.Rd

@@ -6,15 +6,15 @@
 \alias{estimateSplatParams.matrix}
 \title{Estimate Splatter simulation parameters}
 \usage{
-estimateSplatParams(data, params = newSplatParams())
+estimateSplatParams(counts, params = newSplatParams())
 
-\method{estimateSplatParams}{SCESet}(data, params = newSplatParams())
+\method{estimateSplatParams}{SCESet}(counts, params = newSplatParams())
 
-\method{estimateSplatParams}{matrix}(data, params = newSplatParams())
+\method{estimateSplatParams}{matrix}(counts, params = newSplatParams())
 }
 \arguments{
-\item{data}{either a counts matrix or an SCESet object containing count data
-to estimate parameters from.}
+\item{counts}{either a counts matrix or an SCESet object containing count
+data to estimate parameters from.}
 
 \item{params}{SplatParams object to store estimated values in.}
 }
@@ -23,14 +23,17 @@ SplatParams object containing the estimated parameters.
 }
 \description{
 Estimate simulation parameters for the Splatter simulation from a real
-dataset.
-}
-\details{
-
+dataset. See the individual estimation functions for more details on how this
+is done.
 }
 \examples{
 data("sc_example_counts")
 params <- estimateSplatParams(sc_example_counts)
 params
 }
+\seealso{
+\code{\link{estSplatMean}},  \code{\link{estSplatLib}},
+\code{\link{estSplatOutlier}}, \code{\link{estSplatBCV}},
+\code{\link{estSplatDropout}}
+}
 

man/getLNormFactors.Rd

+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/splat-simulate.R
+\name{getLNormFactors}
+\alias{getLNormFactors}
+\title{Get log-normal factors}
+\usage{
+getLNormFactors(n.facs, sel.prob, neg.prob, fac.loc, fac.scale)
+}
+\arguments{
+\item{n.facs}{Number of factors to generate.}
+
+\item{sel.prob}{Probability that a factor will be selected to be different
+from 1.}
+
+\item{neg.prob}{Probability that a selected factor is less than one.}
+
+\item{fac.loc}{Location parameter for the log-normal distribution.}
+
+\item{fac.scale}{Scale factor for the log-normal distribution.}
+}
+\value{
+Vector containing generated factors.
+}
+\description{
+Randomly generate multiplication factors from a log-normal distribution.
+}
+

man/getPathOrder.Rd

+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/splat-simulate.R
+\name{getPathOrder}
+\alias{getPathOrder}
+\title{Get path order}
+\usage{
+getPathOrder(path.from)
+}
+\arguments{
+\item{path.from}{vector giving the path endpoints that each path orginates
+from.}
+}
+\value{
+Vector giving the order to process paths in.
+}
+\description{
+Identify the correct order to process paths so that preceding paths have
+already been simulated.
+}
+

man/splatSimBCVMeans.Rd

+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/splat-simulate.R
+\name{splatSimBCVMeans}
+\alias{splatSimBCVMeans}
+\title{Simulate BCV means}
+\usage{
+splatSimBCVMeans(sim, params)
+}
+\arguments{
+\item{sim}{SCESet to add BCV means to.}
+
+\item{params}{SplatParams object with simulation parameters.}
+}
+\value{
+SCESet with simulated BCV means.
+}
+\description{
+Simulate means for each gene in each cell that are adjusted to follow a
+mean-variance trend using Biological Coefficient of Variation taken from
+and inverse gamma distribution.
+}
+

man/splatSimCellMeans.Rd

+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/splat-simulate.R
+\name{splatSimCellMeans}
+\alias{splatSimCellMeans}
+\alias{splatSimGroupCellMeans}
+\alias{splatSimPathCellMeans}
+\alias{splatSimSingleCellMeans}
+\title{Simulate cell means}
+\usage{
+splatSimSingleCellMeans(sim, params)
+
+splatSimGroupCellMeans(sim, params)
+
+splatSimPathCellMeans(sim, params)
+}
+\arguments{
+\item{sim}{SCESet to add cell means to.}
+
+\item{params}{SplatParams object with simulation parameters.}
+}
+\value{
+SCESet with added cell means.
+}
+\description{
+Simulate a gene by cell matrix giving the mean expression for each gene in
+each cell. Cells start with the mean expression for the group they belong to
+(when simulating groups) or cells are assigned the mean expression from a
+random position on the appropriate path (when simulating paths). The selected
+means are adjusted for each cell's expected library size.
+}
+

man/splatSimDE.Rd

+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/splat-simulate.R
+\name{splatSimDE}
+\alias{splatSimDE}
+\alias{splatSimGroupDE}
+\alias{splatSimPathDE}
+\title{Simulate group differential expression}
+\usage{
+splatSimGroupDE(sim, params)
+
+splatSimPathDE(sim, params)
+}
+\arguments{
+\item{sim}{SCESet to add differential expression to.}
+
+\item{params}{splatParams object with simulation parameters.}
+}
+\value{
+SCESet with simulated differential expression.
+}
+\description{
+Simulate differential expression. Differential expression factors for each
+group are produced using \code{\link{getLNormFactors}} and these are added
+along with updated means for each group. For paths care is taked to make sure
+they are simualated in the correct order.
+}
+

man/splatSimDropout.Rd

+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/splat-simulate.R
+\name{splatSimDropout}
+\alias{splatSimDropout}
+\title{Simulate dropout}
+\usage{
+splatSimDropout(sim, params)
+}
+\arguments{
+\item{sim}{SCESet to add dropout to.}
+
+\item{params}{SplatParams object with simulation parameters.}
+}
+\value{
+SCESet with simulated dropout and observed counts.
+}
+\description{
+A logistic function is used to form a relationshop between the expression
+level of a gene and the probability of dropout, giving a probability for each
+gene in each cell. These probabilities are used in a Bernoulli distribution
+to decide which counts should be dropped.
+}
+

man/splatSimGeneMeans.Rd

+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/splat-simulate.R
+\name{splatSimGeneMeans}
+\alias{splatSimGeneMeans}
+\title{Simulate gene means}
+\usage{
+splatSimGeneMeans(sim, params)
+}
+\arguments{
+\item{sim}{SCESet to add gene means to.}
+
+\item{params}{SplatParams object with simulation parameters.}
+}
+\value{
+SCESet with simulated gene means.
+}
+\description{
+Simulate gene means from a gamma distribution. Also simulates outlier
+expression factors. Genes with an outlier factor not equal to 1 are replaced
+with the median mean expression multiplied by the outlier factor.
+}
+

man/splatSimLibSizes.Rd

+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/splat-simulate.R
+\name{splatSimLibSizes}
+\alias{splatSimLibSizes}
+\title{Simulate library sizes}
+\usage{
+splatSimLibSizes(sim, params)
+}
+\arguments{
+\item{sim}{SCESet to add library size to.}
+
+\item{params}{SplatParams object with simulation parameters.}
+}
+\value{
+SCESet with simulated library sizes.
+}
+\description{
+Simulate expected library sizes from a log-normal distribution
+}
+

man/splatSimTrueCounts.Rd

+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/splat-simulate.R
+\name{splatSimTrueCounts}
+\alias{splatSimTrueCounts}
+\title{Simulate true counts}
+\usage{
+splatSimTrueCounts(sim, params)
+}
+\arguments{
+\item{sim}{SCESet to add true counts to.}
+
+\item{params}{SplatParams object with simulation parameters.}
+}
+\value{
+SCESet with simulated true counts.
+}
+\description{
+Simulate a true counts matrix. Counts are simulated from a poisson
+distribution where Each gene in each cell has it's own mean based on the
+group (or path position), expected library size and BCV.
+}
+

man/splatSimulate.Rd

+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/splat-simulate.R
+\name{splatSimulate}
+\alias{splatSimulate}
+\alias{splatSimulateGroups}
+\alias{splatSimulatePaths}
+\alias{splatSimulateSingle}
+\title{Splatter simulation}
+\usage{
+splatSimulate(params = newSplatParams(), method = c("single", "groups",
+  "paths"), verbose = TRUE, ...)
+
+splatSimulateSingle(params = newSplatParams(), verbose = TRUE, ...)
+
+splatSimulateGroups(params = newSplatParams(), verbose = TRUE, ...)
+
+splatSimulatePaths(params = newSplatParams(), verbose = TRUE, ...)
+}
+\arguments{
+\item{params}{SplatParams object containing parameters for the simulation.
+See \code{\link{SplatParams}} for details.}
+
+\item{method}{which simulation method to use. Options are "single" which
+produces a single population, "groups" which produces distinct groups
+(eg. cell types) or "paths" which selects cells from continuous
+trajectories (eg. differentiation processes).}
+
+\item{verbose}{logical. Whether to print progress messages.}
+
+\item{...}{any additional parameter settings to override what is provided in
+\code{params}.}
+}
+\value{
+SCESet object containing the simulated counts and intermediate
+values.
+}
+\description{
+Simulate count data from a fictional single-cell RNA-seq experiment using
+the Splatter method.
+}
+\details{
+Parameters can be set in a variety of ways. If no parameters are provided
+the default parameters are used. Any parameters in \code{params} can be
+overridden by supplying additional arguments through a call to
+\code{\link{setParams}}. This design allows the user flexibility in
+how they supply parameters and allows small adjustments without creating a
+new \code{SplatParams} object. See examples for a demonstration of how this
+can be used.
+
+The simulation involves the following steps:
+\enumerate{
+  \item Set up simulation object
+  \item Simulate library sizes
+  \item Simulate gene means
+  \item Simulate groups/paths
+  \item Simulate BCV adjusted cell means
+  \item Simulate true counts
+  \item Simulate dropout
+  \item Create final SCESet object
+}
+
+The final output is an \code{\link[scater]{SCESet}} object that contains the
+simulated counts but also the values for various intermediate steps. These
+are stored in the \code{\link[Biobase]{phenoData}} (for cell specific
+information), \code{\link[Biobase]{featureData}} (for gene specific
+information) or \code{\link[Biobase]{assayData}} (for gene by cell matrices)
+slots. This additional information includes:
+\describe{
+  \item{\code{phenoData}}{
+    \describe{
+      \item{Cell}{Unique cell identifier.}
+      \item{Group}{The group or path the cell belongs to.}
+      \item{ExpLibSize}{The expected library size for that cell.}
+      \item{Step (paths only)}{how far along the path each cell is.}
+    }
+  }
+  \item{\code{featureData}}{
+    \describe{
+      \item{Gene}{Unique gene identifier.}
+      \item{BaseGeneMean}{The base expression level for that gene.}
+      \item{OutlierFactor}{Expression outlier factor for that gene. Values
+      of 1 indicate the gene is not an expression outlier.}
+      \item{GeneMean}{Expression level after applying outlier factors.}
+      \item{DEFac[Group]}{The differential expression factor for each gene
+      in a particular group. Values of 1 indicate the gene is not
+      differentially expressed.}
+      \item{GeneMean[Group]}{Expression level of a gene in a particular
+      group after applying differential expression factors.}
+    }
+  }
+  \item{\code{assayData}}{
+    \describe{
+      \item{BaseCellMeans}{The expression of genes in each cell adjusted for
+      expected library size.}
+      \item{BCV}{The Biological Coefficient of Variation for each gene in
+      each cell.}
+      \item{CellMeans}{The expression level of genes in each cell adjusted
+      for BCV.}
+      \item{TrueCounts}{The simulated counts before dropout.}
+      \item{Dropout}{Logical matrix showing which values have been dropped
+      in which cells.}
+    }
+  }
+}
+
+Values that have been added by Splatter are named using \code{CamelCase} in
+order to differentiate them from the values added by Scater which uses
+\code{underscore_naming}.
+}
+\examples{
+# Simulation with default parameters
+sim <- splatSimulate()
+# Simulation with different number of genes
+sim <- splatSimulate(nGenes = 1000)
+# Simulation with custom parameters
+params <- newSplatParams(nGenes = 100, mean.rate = 0.5)
+sim <- splatSimulate(params)
+# Simulation with adjusted custom parameters
+sim <- splatSimulate(params, mean.rate = 0.6, out.prob = 0.2)
+# Simulate groups
+sim <- splatSimulate(method = "groups")
+# Simulate paths
+sim <- splatSimulate(method = "paths")
+}
+\seealso{
+\code{\link{splatSimLibSizes}}, \code{\link{splatSimGeneMeans}},
+\code{\link{splatSimDE}}, \code{\link{splatSimCellMeans}},
+\code{\link{splatSimBCVMeans}}, \code{\link{splatSimTrueCounts}},
+\code{\link{splatSimDropout}}
+}
+