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, ...)

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.

...

Graphical parameters (see par).

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.6.0 Index]