blisa: Run BLISA spatial cell-cell communication analysis

In blisa: Infer Cell-Cell Communication from Spatial Transcriptomics

Run BLISA spatial cell-cell communication analysis

Description

Generic function for running BLISA (Bivariate Local Indicator of Spatial Association). Dispatches on the class of x:

• blisa.default accepts a pre-binned gene-by-bin count matrix and a matching bins polygon object.

• blisa.SpatialExperiment accepts a cell-level SpatialExperiment object and bins cells into hexagonal tiles internally via hexBinCells before running the analysis.

Usage

blisa(x, ...)

## Default S3 method:
blisa(
  x,
  bins,
  LR_df = NULL,
  bin_size = 50,
  dmax = 250,
  nsim = 999,
  p_cutoff = 0.05,
  min_ligand = 10,
  min_receptor = 10,
  min_cells = 1,
  n_cells_col = NA,
  annotation_col = "annotation",
  default_mode = "diffuse",
  diffuse_category = c("Secreted Signaling", "Non-protein Signaling"),
  species = c("human", "mouse"),
  genes = NULL,
  counts_by_group = NULL,
  fast = TRUE,
  cpu_threads = 4L,
  verbose = FALSE,
  ...
)

## S3 method for class 'SpatialExperiment'
blisa(
  x,
  bin_size = 50,
  LR_df = NULL,
  group = "cell_type",
  genes = NULL,
  min_cells = 1,
  min_total_counts = 10,
  platform = c("auto", "xenium", "visium"),
  verbose = FALSE,
  ...
)

Arguments

x	A gene-by-bin count matrix (for blisa.default) or a cell-level SpatialExperiment object (for blisa.SpatialExperiment).
...	Additional arguments passed to the relevant method.
bins	An sf object of bin polygons. Row order must match the column order of x.
LR_df	Data frame of ligand-receptor pairs with columns ligand.symbol and receptor.symbol. When NULL, CellChatDB for the chosen species is downloaded automatically.
bin_size	Numeric. Width of each hexagonal bin in coordinate units (e.g. microns). Passed to hexBinCells and computeSpatialWeights. Default 50; for the Visium path it defaults to 100 (spot center-to-center spacing) when left unset.
dmax	Numeric. Maximum distance for diffuse-mode neighbours. Default 250.
nsim	Integer. Number of permutations for Moran's I significance. Default 999.
p_cutoff	Numeric. P-value threshold for High-High hotspots. Default 0.05.
min_ligand	Numeric. Minimum ligand count threshold. Default 10.
min_receptor	Numeric. Minimum receptor count threshold. Default 10.
min_cells	Integer. Minimum number of cells per bin. For a SpatialExperiment, bins below this threshold are dropped during binning by hexBinCells. For pre-binned input supplied directly to blisa.default, they are dropped from bins, x and counts_by_group before the spatial weights are built; this requires n_cells_col and is ignored when n_cells_col = NA. Default 1.
n_cells_col	Character or NA. Column in bins holding per-bin cell counts used for min_cells filtering. Set to NA to skip (default).
annotation_col	Character. Column in LR_df specifying interaction category used for communication-mode assignment. Default "annotation".
default_mode	Character. CCC mode assigned to LR pairs whose annotation does not match diffuse_category. Default "diffuse".
diffuse_category	Character vector of annotation categories treated as diffuse signalling.
species	Character. Which CellChatDB to download when LR_df = NULL. One of "human" (default) or "mouse".
genes	Character vector of gene names to consider when matching ligand-receptor pairs. Defaults to rownames(x) (all genes in the SpatialExperiment object).
counts_by_group	Named list of gene-by-bin count matrices, one per group level (e.g. cell type), as returned by hexBinCells when group is supplied. When provided, runCCI is called automatically after the BLISA loop and its output is included in the result as CCI_scores. Default NULL.
fast	Logical. When TRUE (default), uses fastLISA::local_moran_bv (a fast C/OpenMP backend) for the bivariate local Moran's I computation. When FALSE, uses the original spdep::localmoran_bv + spdep::hotspot pipeline.
cpu_threads	Integer. Number of OpenMP threads used by fastLISA::local_moran_bv. Only used when fast = TRUE. Ignored on platforms without OpenMP. Default 4L.
verbose	Logical. If TRUE, print progress messages. Default FALSE (silent).
group	Character. Column name in colData(x) to use as the grouping variable (e.g. cell type) for per-group bin aggregation and downstream CCI analysis via runCCI. If the column is not found in colData(x), a message is issued and CCI is skipped. Default "cell_type".
min_total_counts	Numeric. Bins whose total counts (summed over all genes) fall below this threshold are dropped during binning by hexBinCells. Set to 0 to disable. Default 10.
platform	Character. "auto" (default) inspects colData(x): if array_col/array_row are present the object is treated as "visium", otherwise "xenium". Set explicitly to override the detection.

Value

A list; see individual method documentation for details.

An object of class blisa with four components:

LR_results

Data frame of BLISA results for each LR pair, including ccc_mode, sig_numbers, sig_index, sig_pval, all_pval, all_lisa, all_quadrant, and original columns from LR_df. all_quadrant is a character vector of hotspot quadrant labels ("High-High", "Low-Low", etc.) for every bin; non-tested bins are NA.

bins

Bin-level sf object of hexagonal polygons.

spatial_weights

Spatial weights list from computeSpatialWeights.

CCI_scores

NULL unless counts_by_group is supplied, in which case a wide data frame of interaction scores from runCCI: rows are "Sender->Receiver" group pairs, columns are LR pairs.

Methods (by class)

• blisa(default): Method for a gene-by-bin count matrix.

• blisa(SpatialExperiment): Method for a cell-level SpatialExperiment object. For cell-level platforms (e.g. Xenium) it bins cells into hexagonal tiles via hexBinCells; for Visium it treats each spot as a bin via visiumSpotBins. Either way it then delegates to blisa.default. The path is chosen by platform.

Examples

## Not run: 
# Download and cache the example Xenium breast cancer dataset (~21 MB)
data_url  <- paste0(
  "https://github.com/ChenLaboratory/example_data/releases/",
  "download/v1.0.0/spe_xenium_bc_s1rep1.rds"
)
cache_dir <- tools::R_user_dir("blisa", "cache")
data_file <- file.path(cache_dir, "spe_xenium_bc_s1rep1.rds")
if (!file.exists(data_file)) {
  dir.create(cache_dir, recursive = TRUE, showWarnings = FALSE)
  download.file(data_url, data_file, mode = "wb")
}
spe <- readRDS(data_file)

# blisa.SpatialExperiment method: bins cells, runs LISA, scores CCI
result <- blisa(spe, bin_size = 50, group = "cell_type")
result

## End(Not run)

blisa documentation built on Oct. 30, 2026, 9:10 a.m.