Inverse Simpson Index (ISI) for Batch Mixing

Evaluates the diversity of batch labels within each cell's k-nearest neighborhood using the Inverse Simpson Index (1 / sum(p_b^2)). Implements a pure-R, lightweight formulation of LISI with optional distance weighting.

Usage

calc_isi(coords, batch_info, k = 30, weighted = TRUE)

Arguments

coords

Matrix of cell coordinates (cells x dimensions).

batch_info

Factor or character vector of batch assignments.

k

Number of nearest neighbors. Default is 30.

weighted

Logical, whether to weight neighbor contributions by inverse distance. Default is TRUE.

Value

A named list:

isi_scores

Numeric vector of cell-level ISI values

mean_isi

Mean ISI score (ranges from 1 to number of batches; higher indicates better mixing)

median_isi

Median ISI score

Examples

coords <- matrix(stats::rnorm(100), 50, 2)
batch <- factor(rep(c("B1", "B2"), length.out = 50))
calc_isi(coords, batch)
#> $isi_scores
#>  [1] 1.997918 1.999436 1.981518 1.991420 1.994033 1.950686 1.999411 1.999660
#>  [9] 1.992445 1.996571 1.990966 1.992288 1.992078 1.969170 1.979706 1.991100
#> [17] 1.976520 1.968818 1.991672 1.994273 1.989650 1.966601 1.996352 1.999377
#> [25] 1.949606 1.998926 1.998179 1.979191 1.992378 1.989906 1.991017 1.997757
#> [33] 1.990033 1.980044 1.989056 1.999999 1.980087 1.999407 1.997797 1.984632
#> [41] 1.987075 1.994840 1.978158 1.999978 1.999454 1.987071 1.999988 1.989269
#> [49] 1.993713 1.998492
#> 
#> $mean_isi
#> [1] 1.988954
#> 
#> $median_isi
#> [1] 1.991875
#>