Compute the concordex coefficient — calculateConcordex • concordexR

Compute the raw and corrected concordex coefficient using a neighborhood graph and observation labels.

Usage

calculateConcordex(x, ...)

# S4 method for ANY
calculateConcordex(
  x,
  labels,
  k = 20,
  n.iter = 15,
  return.map = TRUE,
  BPPARAM = SerialParam()
)

Arguments

x: A numeric matrix specifying the neighborhood structure of observations. Typically an adjacency matrix produced by a k-Nearest Neighbor algorithm. It can also be a matrix whose rows correspond to each observation and columns correspond to neighbor indices, i.e. matrix form of an adjacency list which can be a matrix due to fixed number of neighbors.
...: Arguments passed to methods.
labels: A numeric or character vector containing the label or class corresponding to each observation. For example, a cell type or cluster ID.
k: Number of neighbors to expect for each observation. Defaults to 20.
n.iter: A number specifying the number of permutations for correcting the coefficient.
return.map: Logical, whether to return the matrix of the number of cells of each label in the neighborhood of cells of each label.
BPPARAM: A BiocParallelParam object specifying whether and how computing the metric for numerous observations shall be parallelized.

Value

A named list with the following components:

concordex: The raw concordex coefficient corresponding to the original label assignments.
mean_random_concordex: The average of n.iter concordex coefficients. concordex coefficients are computed after permuting the labels and reassigning them to new observations.
corrected_concordex: Simply the raw concordex coefficient divided by the average of the permuted coefficients.
simulated: Numeric vector of the concordex coefficients from permuted labels, showing the null distribution.
map: Numeric matrix of the number of cells of each label in the neighborhood of cells of each label. Only returned when return.map = TRUE.

Examples


# Simplest case where input is a nxn matrix
# Neighbors can be oriented along the rows or columns
nCells <- 10
k <- 3
set.seed(40)
labels <- sample(paste0("l", seq_len(3)), nCells, replace=TRUE)

mtx <- sapply(seq_len(nCells), function(x) {
    out <- rep(0, nCells)
    out[-x] <- sample(c(rep(1, k), rep(0, nCells - k - 1)))
    out
})

res <- calculateConcordex(mtx, labels, k = k)

res
#> $concordex
#> [1] 0.4814815
#> 
#> $mean_random_concordex
#> [1] 0.2790123
#> 
#> $concordex_ratio
#> [1] 1.725664
#> 
#> $simulated
#>  [1] 0.4537037 0.2870370 0.2962963 0.2777778 0.1574074 0.3333333 0.1944444
#>  [8] 0.3148148 0.2500000 0.2129630 0.4351852 0.3055556 0.2037037 0.2314815
#> [15] 0.2314815
#> 
#> $map
#>           l1        l2         l3
#> l1 0.3333333 0.4444444 0.22222222
#> l2 0.2500000 0.6666667 0.08333333
#> l3 0.3333333 0.2222222 0.44444444
#> 

# Also works if input matrix is nxk or kxn
mtx <- sapply(seq_len(nCells), function(x) {
  out <- sample((seq_len(nCells))[-x], k)
  out
})

res <- calculateConcordex(mtx, labels, k = k)

res
#> $concordex
#> [1] 0.2592593
#> 
#> $mean_random_concordex
#> [1] 0.2469136
#> 
#> $concordex_ratio
#> [1] 1.05
#> 
#> $simulated
#>  [1] 0.3703704 0.2500000 0.2500000 0.2314815 0.2222222 0.1296296 0.1851852
#>  [8] 0.2777778 0.2222222 0.3055556 0.2314815 0.2314815 0.1296296 0.2592593
#> [15] 0.4074074
#> 
#> $map
#>            l1        l2        l3
#> l1 0.33333333 0.4444444 0.2222222
#> l2 0.08333333 0.3333333 0.5833333
#> l3 0.11111111 0.7777778 0.1111111
#>