mmDS {muscat} | R Documentation

## DS analysis using mixed-models (MM)

### Description

Performs cluster-wise DE analysis by fitting cell-level models.

### Usage

    mmDS(
      x,
      coef = NULL,
      covs = NULL,
      method = c("dream2", "dream", "vst", "poisson", "nbinom", "hybrid"),
      n_cells = 10,
      n_samples = 2,
      min_count = 1,
      min_cells = 20,
      n_threads = 1,
      verbose = TRUE,
      vst = c("sctransform", "DESeq2"),
      ddf = c("Satterthwaite", "Kenward-Roger", "lme4"),
      dup_corr = FALSE,
      trended = FALSE,
      bayesian = FALSE,
      blind = TRUE,
      REML = TRUE,
      moderate = FALSE
    )

    .mm_dream(
      x,
      coef = NULL,
      covs = NULL,
      dup_corr = FALSE,
      trended = FALSE,
      ddf = c("Satterthwaite", "Kenward-Roger"),
      n_threads = 1,
      verbose = FALSE
    )

    .mm_dream2(
      x,
      coef = NULL,
      covs = NULL,
      ddf = c("Satterthwaite", "Kenward-Roger"),
      n_threads = 1,
      verbose = FALSE
    )

    .mm_vst(
      x,
      vst = c("sctransform", "DESeq2"),
      coef = NULL,
      covs = NULL,
      bayesian = FALSE,
      blind = TRUE,
      REML = TRUE,
      ddf = c("Satterthwaite", "Kenward-Roger", "lme4"),
      n_threads = 1,
      verbose = FALSE
    )

    .mm_glmm(
      x,
      coef = NULL,
      covs = NULL,
      n_threads = 1,
      family = c("poisson", "nbinom"),
      verbose = TRUE,
      moderate = FALSE
    )

### Arguments

`x` | a `SingleCellExperiment`.
`coef` | character specifying the coefficient to test. If NULL (default), will test the last level of `"group_id"`.
`covs` | character vector of `colData(x)` column names to use as covariates.
`method` | a character string. Either `"dream2"` (default, lme4 with voom-weights), `"dream"` (previous implementation of the dream method), `"vst"` (variance-stabilizing transformation), `"poisson"` (poisson GLM-MM), `"nbinom"` (negative binomial GLM-MM), `"hybrid"` (combination of pseudobulk and poisson methods) or a function accepting the same arguments.
`n_cells` | number of cells per cluster-sample required to consider a sample for testing.
`n_samples` | number of samples per group required to consider a cluster for testing.
`min_count` | numeric. For a gene to be tested in a given cluster, at least `min_cells` must have a count >= `min_count`.
`min_cells` | number (or fraction, if < 1) of cells with a count > `min_count` required for a gene to be tested in a given cluster.
`n_threads` | number of threads to use.
`verbose` | logical specifying whether messages on progress and a progress bar should be displayed.
`vst` | method to use as variance-stabilizing transformations. `"sctransform"` for `vst`; `"DESeq2"` for `varianceStabilizingTransformation`.
`ddf` | character string specifying the method for estimating the effective degrees of freedom. For `method = "dream"`, either `"Satterthwaite"` (faster) or `"Kenward-Roger"` (more accurate); see `?variancePartition::dream` for details. For `method = "vst"`, method `"lme4"` is also valid; see `contest.lmerModLmerTest`.
`dup_corr` | logical; whether to use `duplicateCorrelation`.
`trended` | logical; whether to use expression-dependent variance priors in `eBayes`.
`bayesian` | logical; whether to use bayesian mixed models.
`blind` | logical; whether to ignore experimental design for the vst.
`REML` | logical; whether to maximize REML instead of log-likelihood.
`moderate` | logical; whether to perform empirical Bayes moderation.
`family` | character string specifying which GLMM to fit: `"poisson"` for `bglmer`, `"nbinom"` for `glmmTMB`.

### Details

The `.mm_*` functions (e.g. `.mm_dream`) expect cells from a single cluster, and do not perform filtering or handle incorrect parameters well. Meant to be called by `mmDS` with `method = c("dream", "vst")` and `vst = c("sctransform", "DESeq2")` to be applied across all clusters.

`method = "dream2"`

  `variancePartition`'s (>=1.14.1) voom-lme4-implementation of mixed models for RNA-seq data; function `dream`.

`method = "dream"`

  `variancePartition`'s older voom-lme4-implementation of mixed models for RNA-seq data; function `dream`.

`method = "vst"`
  `vst = "sctransform"`

    `lmer` or `blmer` mixed models on `vst` transformed counts.

  `vst = "DESeq2"`

    `varianceStabilizingTransformation` followed by `lme4` mixed models.

### Value

a data.frame

### Functions

- `.mm_dream`: see details.

- `.mm_dream2`: see details.

- `.mm_vst`: see details.

- `.mm_glmm`: see details.

### Author(s)

Pierre-Luc Germain & Helena L Crowell

### References

Crowell, HL, Soneson, C, Germain, P-L, Calini, D, Collin, L, Raposo, C, Malhotra, D & Robinson, MD: On the discovery of population-specific state transitions from multi-sample multi-condition single-cell RNA sequencing data. bioRxiv 713412 (2018). doi: https://doi.org/10.1101/713412

### Examples

    data(sce)
    # subset "B cells" cluster
    sce <- sce[, sce$cluster_id == "B cells"]
    sce$cluster_id <- droplevels(sce$cluster_id)

    # downsample to 100 genes
    gs <- sample(nrow(sce), 100)
    sce <- sce[gs, ]

    res <- mmDS(sce, method = "dream",
        n_threads = 2, verbose = FALSE)
    head(res$`B cells`)

[Package muscat version 1.2.1 Index]