BASiCS_TestDE {BASiCS} | R Documentation

## Detection of genes with changes in expression

### Description

Function to assess changes in expression between two groups of cells (mean and over-dispersion)

### Usage

    BASiCS_TestDE(
      Chain1,
      Chain2,
      EpsilonM = log2(1.5),
      EpsilonD = log2(1.5),
      EpsilonR = log2(1.5)/log2(exp(1)),
      ProbThresholdM = 2/3,
      ProbThresholdD = 2/3,
      ProbThresholdR = 2/3,
      OrderVariable = "GeneIndex",
      GroupLabel1 = "Group1",
      GroupLabel2 = "Group2",
      Plot = TRUE,
      PlotOffset = TRUE,
      Offset = TRUE,
      EFDR_M = 0.05,
      EFDR_D = 0.05,
      EFDR_R = 0.05,
      GenesSelect = NULL,
      min.mean = 1,
      ...
    )

### Arguments

`Chain1` | an object of class `BASiCS_Chain` containing parameter estimates for the first group of cells
`Chain2` | an object of class `BASiCS_Chain` containing parameter estimates for the second group of cells
`EpsilonM` | Minimum fold change tolerance threshold for detecting changes in overall expression (must be a positive real number). Default value: `EpsilonM = log2(1.5)` (i.e. 50% increase).
`EpsilonD` | Minimum fold change tolerance threshold for detecting changes in biological over-dispersion (must be a positive real number). Default value: `EpsilonM = log2(1.5)` (i.e. 50% increase).
`EpsilonR` | Minimum distance threshold for detecting changes in residual over-dispersion (must be a positive real number). Default value: `EpsilonR= log2(1.5)/log2(exp(1))` (i.e. 50% increase).
`ProbThresholdM` | Optional parameter. Probability threshold for detecting changes in overall expression (must be a positive value, between 0 and 1). If `EFDR_M = NULL`, the posterior probability threshold for the differential mean expression test will be set to `ProbThresholdM`. If a value for `EFDR_M` is provided, the posterior probability threshold is chosen to achieve an EFDR equal to `EFDR_M` and `ProbThresholdM` defines a minimum probability threshold for this calibration (this avoids low values of `ProbThresholdM` to be chosen by the EFDR calibration. Default value `ProbThresholdM = 2/3`, i.e. the probability of observing a log2-FC above `EpsilonM` must be at least twice the probality of observing the complementary event (log2-FC below `EpsilonM`).
`ProbThresholdD` | Optional parameter. Probability threshold for detecting changes in cell-to-cell biological over-dispersion (must be a positive value, between 0 and 1). Same usage as `ProbThresholdM`, depending on the value provided for `EFDR_D`. Default value `ProbThresholdD = 2/3`.
`ProbThresholdR` | Optional parameter. Probability threshold for detecting changes in residual over-dispersion (must be a positive value, between 0 and 1). Same usage as `ProbThresholdM`, depending on the value provided for `EFDR_R`. Default value `ProbThresholdR = 2/3`.
`OrderVariable` | Ordering variable for output. Possible values: `'GeneIndex'` (default), `'GeneName'` and `'Mu'` (mean expression).
`GroupLabel1` | Label assigned to reference group. Default: `GroupLabel1 = 'Group1'`
`GroupLabel2` | Label assigned to reference group. Default: `GroupLabel2 = 'Group2'`
`Plot` | If `Plot = TRUE`, MA and volcano plots are generated.
`PlotOffset` | If `Plot = TRUE`, the offset effect is visualised.
`Offset` | Optional argument to remove a fix offset effect (if not previously removed from the MCMC chains). Default: `Offset = TRUE`.
`EFDR_M` | Target for expected false discovery rate related to the comparison of means. If `EFDR_M = NULL`, EFDR calibration is not performed and the posterior probability threshold is set equal to `ProbThresholdM`. Default `EFDR_M = 0.05`.
`EFDR_D` | Target for expected false discovery rate related to the comparison of dispersions. If `EFDR_D = NULL`, EFDR calibration is not performed and the posterior probability threshold is set equal to `ProbThresholdD`.Default `EFDR_D = 0.05`.
`EFDR_R` | Target for expected false discovery rate related to the comparison of residual over-dispersions. If `EFDR_R = NULL`, EFDR calibration is not performed and the posterior probability threshold is set equal to `ProbThresholdR`.Default `EFDR_D = 0.05`.
`GenesSelect` | Optional argument to provide a user-defined list of genes to be considered for the comparison. Default: `GenesSelect = NULL`. When used, this argument must be a vector of `TRUE` (include gene) / `FALSE` (exclude gene) indicator, with the same length as the number of intrinsic genes and following the same order as how genes are displayed in the table of counts. This argument is necessary in order to have a meaningful EFDR calibration when the user decides to exclude some genes from the comparison.
`min.mean` | Minimum mean expression threshold required for inclusion in offset calculation. Similar to 'min.mean' in 'scran::computeSumFactors'. This parameter is only relevant with 'Offset = TRUE'.
`...` | Optional parameters.

### Value

`BASiCS_TestDE` returns a list of 4 elements:

`TableMean`

  A `data.frame` containing the results of the differential mean test

  `GeneName`

    Gene name

  `MeanOverall`

    For each gene, the estimated mean expression parameter μ_i is averaged across both groups of cells (weighted by sample size).

  `Mean1`

    Estimated mean expression parameter μ_i for each biological gene in the first group of cells.

  `Mean2`

    Estimated mean expression parameter μ_i for each biological gene in the second group of cells.

  `MeanFC`

    Fold change in mean expression parameters between the first and second groups of cells.

  `MeanLog2FC`

    Log2-transformed fold change in mean expression between the first and second groups of cells.

  `ProbDiffMean`

    Posterior probability for mean expression difference between the first and second groups of cells.

  `ResultDiffExp`

    Indicator if a gene has a higher mean expression in the first or second groups of cells.

`TableDisp`

  A `data.frame` containing the results of the differential dispersion test (excludes genes for which the mean does not changes).

  `GeneName`

    Gene name

  `MeanOverall`

    For each gene, the estimated mean expression parameter μ_i is averaged across both groups of cells (weighted by sample size).

  `DispOverall`

    For each gene, the estimated over-dispersion parameter δ_i is averaged across both groups of cells (weighted by sample size).

  `Disp1`

    Estimated over-dispersion parameter δ_i for each biological gene in the first group of cells.

  `Disp2`

    Estimated over-dispersion parameter δ_i for each biological gene in the second group of cells.

  `DispFC`

    Fold change in over-dispersion parameters between the between the first and second groups of cells.

  `DispLog2FC`

    Log-transformed fold change in over-dispersion between the first and second groups of cells.

  `ProbDiffDisp`

    Posterior probability for over-dispersion difference between the first and second groups of cells.

  `ResultDiffDisp`

    Indicator if a gene has a higher over-dispersion in the first or second groups of cells. Genes labelled with "ExcludedFromTest" were detected as showing differential mean expression.

`TableResDisp`

  A `data.frame` containing the results of the differential residual over-dispersion test.

  `GeneName`

    Gene name

  `MeanOverall`

    For each gene, the estimated mean expression parameter μ_i is averaged across both groups of cells (weighted by sample size).

  `ResDispOverall`

    For each gene, the estimated residual over-dispersion parameter δ_i is averaged across both groups of cells (weighted by sample size).

  `ResDisp1`

    Estimated residual over-dispersion parameter ε_i for each biological gene in the first group of cells.

  `ResDisp2`

    Estimated residual over-dispersion parameter ε_i for each biological gene in the second group of cells.

  `ResDispDistance`

    Difference in residual over-dispersion between the first and second groups of cells.

  `ProbDiffResDisp`

    Posterior probability for residual over-dispersion difference between the first and second groups of cells.

  `ResultDiffResDisp`

    Indicator if a gene has a higher residual over-dispersion in the first or second groups of cells. Genes labelled with "ExcludedFromTest" were not expressed in at least 2 cells per condition.

`DiffMeanSummary`

  A list containing the following information for the differential mean expression test:

  `ProbThreshold`

    Posterior probability threshold.

  `EFDR`

    Expected false discovery rate for the given thresholds.

  `EFNR`

    Expected false negative rate for the given thresholds.

`DiffDispSummary`

  A list containing the following information for the differential over-dispersion test:

  `ProbThreshold`

    Posterior probability threshold.

  `EFDR`

    Expected false discovery rate for the given thresholds.

  `EFNR`

    Expected false negative rate for the given thresholds.

`DiffResDispSummary`

  A list containing the following information for the differential residual over-dispersion test:

  `ProbThreshold`

    Posterior probability threshold.

  `EFDR`

    Expected false discovery rate for the given thresholds.

  `EFNR`

    Expected false negative rate for the given thresholds.

`Chain1_offset`

  an `BASiCS_Chain` object: `Chain1` after offset removal.

`Chain2_offset`

  an `BASiCS_Chain` object: `Chain2` after offset removal (this is only provided for completeness; `Chain2` is not affected by the offset).

`OffsetChain`

  MCMC chain calculated for the offset effect.

`Offset`

  Estimated offset (posterior median of `OffsetChain`). Default value set equal to 1 when offset correction is not performed.

### Author(s)

Catalina A. Vallejos cnvallej@uc.cl

Nils Eling eling@ebi.ac.uk

### Examples

    # Loading two 'BASiCS_Chain' objects (obtained using 'BASiCS_MCMC')
    data(ChainSC)
    data(ChainRNA)

    Test <- BASiCS_TestDE(Chain1 = ChainSC, Chain2 = ChainRNA,
                          GroupLabel1 = 'SC', GroupLabel2 = 'P&S',
                          EpsilonM = log2(1.5), EpsilonD = log2(1.5),
                          OffSet = TRUE)

    # Results for the differential mean test
    head(Test$TableMean)

    # Results for the differential over-dispersion test
    # This only includes genes marked as 'NoDiff' in Test$TableMean
    head(Test$TableDisp)

    # For testing differences in residual over-dispersion, two chains obtained
    # via 'BASiCS_MCMC(Data, N, Thin, Burn, Regression=TRUE)' need to be provided
    data(ChainSCReg)
    data(ChainRNAReg)

    Test <- BASiCS_TestDE(Chain1 = ChainSCReg, Chain2 = ChainRNAReg,
                          GroupLabel1 = 'SC', GroupLabel2 = 'P&S',
                          EpsilonM = log2(1.5), EpsilonD = log2(1.5),
                          EpsilonR = log2(1.5)/log2(exp(1)),
                          OffSet = TRUE)

[Package BASiCS version 1.8.1 Index]