correlateNull {scran} | R Documentation

## Build null correlations

### Description

Build a distribution of correlations under the null hypothesis of independent expression between pairs of genes.

### Usage

    correlateNull(
      ncells,
      iters = 1e+06,
      block = NULL,
      design = NULL,
      equiweight = TRUE,
      BPPARAM = SerialParam()
    )

### Arguments

`ncells` | An integer scalar indicating the number of cells in the data set.
`iters` | An integer scalar specifying the number of values in the null distribution.
`block` | A factor specifying the blocking level for each cell.
`design` | A numeric design matrix containing uninteresting factors to be ignored.
`equiweight` | A logical scalar indicating whether statistics from each block should be given equal weight. Otherwise, each block is weighted according to its number of cells. Only used if `block` is specified.
`BPPARAM` | A BiocParallelParam object that specifies the manner of parallel processing to use.

### Details

The `correlateNull` function constructs an empirical null distribution for Spearman's rank correlation when it is computed with `ncells` cells. This is done by shuffling the ranks, calculating the correlation and repeating until `iters` values are obtained. No consideration is given to tied ranks, which has implications for the accuracy of p-values in `correlatePairs`.

If `block` is specified, a null correlation is created within each level of `block` using the shuffled ranks. The final correlation is then defined as the average of the per-level correlations, weighted by the number of cells in that level if `equiweight=FALSE`. Levels with fewer than 3 cells are ignored, and if no level has 3 or more cells, all returned correlations will be `NA`.

If `design` is specified, the same process is performed on ranks derived from simulated residuals computed by fitting the linear model to a vector of normally distributed values. If there are not at least 3 residual d.f., all returned correlations will be `NA`. The `design` argument cannot be used at the same time as `block`.

### Value

A numeric vector of length `iters` is returned containing the sorted correlations under the null hypothesis of no correlations.

### Author(s)

Aaron Lun

### See Also

`correlatePairs`, where the null distribution is used to compute p-values.

### Examples

    set.seed(0)
    ncells <- 100

    # Simplest case:
    null.dist <- correlateNull(ncells, iters=10000)
    hist(null.dist)

    # With a blocking factor:
    block <- sample(LETTERS[1:3], ncells, replace=TRUE)
    null.dist <- correlateNull(block=block, iters=10000)
    hist(null.dist)

    # With a design matrix.
    cov <- runif(ncells)
    X <- model.matrix(~cov)
    null.dist <- correlateNull(design=X, iters=10000)
    hist(null.dist)

[Package scran version 1.16.0 Index]