zinbwave: Perform dimensionality reduction using a ZINB regression...
In zinbwave: Zero-Inflated Negative Binomial Model for RNA-Seq Data

Description Usage Arguments Details Value Methods (by class) Examples

Given an object with the data, it performs dimensionality reduction using a ZINB regression model with gene and cell-level covariates.

zinbwave(Y, ...)

## S4 method for signature 'SummarizedExperiment'
zinbwave(
  Y,
  X,
  V,
  K = 2,
  fitted_model,
  which_assay,
  which_genes,
  commondispersion = TRUE,
  zeroinflation = TRUE,
  verbose = FALSE,
  nb.repeat.initialize = 2,
  maxiter.optimize = 25,
  stop.epsilon.optimize = 1e-04,
  BPPARAM = BiocParallel::bpparam(),
  normalizedValues = FALSE,
  residuals = FALSE,
  imputedValues = FALSE,
  observationalWeights = FALSE,
  ...
)

`Y`	The data (genes in rows, samples in columns). Currently implemented only for `SummarizedExperiment`.
`...`	Additional parameters to describe the model, see `zinbModel`.
`X`	The design matrix containing sample-level covariates, one sample per row. If missing, X will contain only an intercept. If Y is a SummarizedExperiment object, X can be a formula using the variables in the colData slot of Y.
`V`	The design matrix containing gene-level covariates, one gene per row. If missing, V will contain only an intercept. If Y is a SummarizedExperiment object, V can be a formula using the variables in the rowData slot of Y.
`K`	integer. Number of latent factors. Specify `K = 0` if only computing observational weights.
`fitted_model`	a `ZinbModel` object.
`which_assay`	numeric or character. Which assay of Y to use. If missing, if 'assayNames(Y)' contains "counts" then that is used. Otherwise, the first assay is used.
`which_genes`	character. Which genes to use to estimate W (see details). Ignored if `fitted_model` is provided.
`commondispersion`	Whether or not a single dispersion for all features is estimated (default TRUE).
`zeroinflation`	Whether or not a ZINB model should be fitted. If FALSE, a negative binomial model is fitted instead.
`verbose`	Print helpful messages.
`nb.repeat.initialize`	Number of iterations for the initialization of beta_mu and gamma_mu.
`maxiter.optimize`	maximum number of iterations for the optimization step (default 25).
`stop.epsilon.optimize`	stopping criterion in the optimization step, when the relative gain in likelihood is below epsilon (default 0.0001).
`BPPARAM`	object of class `bpparamClass` that specifies the back-end to be used for computations. See `bpparam` for details.
`normalizedValues`	indicates wether or not you want to compute normalized values for the counts after adjusting for gene and cell-level covariates.
`residuals`	indicates wether or not you want to compute the residuals of the ZINB model. Deviance residuals are computed.
`imputedValues`	indicates wether or not you want to compute the imputed counts of the ZINB model.
`observationalWeights`	indicates whether to compute the observational weights for differential expression (see vignette).

For visualization (heatmaps, ...), please use the normalized values. It corresponds to the deviance residuals when the W is not included in the model but the gene and cell-level covariates are. As a results, when W is not included in the model, the deviance residuals should capture the biology. Note that we do not recommend to use the normalized values for any downstream analysis (such as clustering, or differential expression), but only for visualization.

If one has already fitted a model using ZinbModel, the object containing such model can be used as input of zinbwave to save the resulting W into a SummarizedExperiment and optionally compute residuals and normalized values, without the need for re-fitting the model.

By default zinbwave uses all genes to estimate W. However, we recommend to use the top 1,000 most variable genes for this step. In general, a user can specify any custom set of genes to be used to estimate W, by specifying either a vector of gene names, or a single character string corresponding to a column of the rowData.

Note that if both which_genes is specified and at least one among observationalWeights, imputedValues, residuals, and normalizedValues is TRUE, the model needs to be fit twice.

An object of class SingleCellExperiment; the dimensionality reduced matrix is stored in the reducedDims slot and optionally normalized values and residuals are added in the list of assays.

SummarizedExperiment: Y is a SummarizedExperiment.

se <- SingleCellExperiment(assays = list(counts = matrix(rpois(60, lambda=5),
                                                         nrow=10, ncol=6)),
                           colData = data.frame(bio = gl(2, 3)))

m <- zinbwave(se, X="~bio", BPPARAM=BiocParallel::SerialParam())