Package 'blisa'

blisa: Bivariate Local Indicator of Spatial Association for spatial transcriptomics

Description

Tools for spatial cell-cell communication analysis of spatial transcriptomics data.

---

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

## S3 method for class 'SpatialExperiment'
blisa(x, bin_size = 50, LR_df = NULL, group = "cell_type", genes = NULL, ...)

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.
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. Bins with fewer cells are excluded from Moran's I and assigned neutral statistics (p = 1, LISA = 0). 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.
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".

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 spdep::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. Bins cells into hexagonal tiles via hexBinCells then delegates to blisa.default.

---

Compute Spatial Weights for BLISA

Description

Builds queen (nearby) and distance-decay (diffuse) spatial weight matrices from a bin-level sf object, excluding isolated bins and optionally excluding low-cell bins. A second-pass isolation check further removes bins that become isolated after the initial subset.

Usage

computeSpatialWeights(
  bins,
  bin_size = 50,
  dmax = 250,
  min_cells = 1,
  n_cells_col = NA
)

Arguments

bins	An sf object of spatial bins.
bin_size	Numeric. Bin spacing used to define queen adjacency (1.2 * bin_size radius).
dmax	Numeric. Maximum distance for diffuse-mode neighbours.
min_cells	Integer. Minimum cell count for a bin to be included. Ignored when n_cells_col = NA.
n_cells_col	Character or NA. Column name in bins holding per-bin cell counts. Set to NA to skip cell-count filtering (default).

Value

A list with:

queen_wt

Spatial weights list for nearby (queen) mode.

dist_wt

Spatial weights list for diffuse (distance-decay) mode.

keep_idx_queen

Integer indices of bins used in queen-mode Moran.

keep_idx_dist

Integer indices of bins used in diffuse-mode Moran.

isolate_idx_queen

Integer indices of original queen-mode isolates.

isolate_idx_dist

Integer indices of original diffuse-mode isolates.

low_cell_idx

Integer indices of bins excluded for low cell counts.

queen_nb_full

Full (unsubset) neighbour list for nearby mode, indexed over all bins.

dist_nb_full

Full (unsubset) neighbour list for diffuse mode, indexed over all bins.

---

Filter ligand-receptor pairs by expression threshold

Description

Retains only LR pairs where at least one bin/spot has counts at or above min_ligand for every ligand subunit and min_receptor for every receptor subunit.

Usage

filterLRpairs(
  counts,
  min_ligand = 10,
  min_receptor = 10,
  LR_df = NULL,
  species = c("human", "mouse")
)

Arguments

counts	Gene-by-bin count matrix (dense or sparse). Row names must be gene symbols.
min_ligand	Numeric. Minimum count threshold for ligand genes. At least one bin must meet or exceed this value. Default 10.
min_receptor	Numeric. Minimum count threshold for receptor genes. At least one bin must meet or exceed this value. Default 10.
LR_df	Data frame of ligand-receptor pairs with columns ligand.symbol and receptor.symbol (comma-separated gene symbols for multi-subunit complexes). When NULL, the CellChatDB for the chosen species is downloaded automatically.
species	Character. Which CellChatDB to download when LR_df is NULL. One of "human" (default) or "mouse".

Value

A subset of LR_df containing only pairs that pass the expression thresholds for both ligand and receptor.

---

Bin cells into hexagonal spatial bins

Description

Aggregates single-cell spatial data into hexagonal bins and returns a bin-level count matrix together with a matching sf polygon object, ready to pass directly to blisa.default.

Usage

hexBinCells(
  coords_df,
  counts_matrix,
  bin_size = 50,
  min_cells = 1,
  group = NULL
)

Arguments

coords_df	Data frame or matrix with columns x_centroid and y_centroid (e.g. the output of SpatialExperiment::spatialCoords()). Row names must be cell IDs matching the column names of counts_matrix.
counts_matrix	Gene-by-cell count matrix (dense or sparse). Row names must be gene symbols; column names must be cell IDs present in coords_df.
bin_size	Numeric. Approximate width of each hexagonal bin in coordinate units (e.g. microns). Analogous to grid.length.x in sciderHex::gridDensity. Default 50.
min_cells	Integer. Bins containing fewer than min_cells cells are dropped from the output. Default 1.
group	Factor or character vector of length ncol(counts_matrix) giving the cell-type label of each cell. When supplied, a named list of per-cell-type gene-by-bin matrices is included in the output as counts_by_group. Default NULL (not computed).

Value

A list with:

counts_matrix

Gene-by-bin sparse count matrix (all cells combined). Column i corresponds to row i of bins.

bins

An sf object of hexagonal bin polygons with an n_cells column recording how many cells fall in each bin. Row order matches the columns of counts_matrix.

counts_by_group

(Only when group is supplied.) A named list of gene-by-bin sparse matrices, one per cell-type level, with the same bin order as counts_matrix.

---

Test if an object is a blisa object

Description

Test if an object is a blisa object

Usage

is.blisa(x)

Arguments

x	Any R object.

Value

Logical.

---

Heatmap of CCI scores across all ligand-receptor pairs

Description

Generic function. Draws a clustered heatmap (via ComplexHeatmap) with rows as Sender $\rightarrow$ Receiver cell-type pairs and columns as LR pairs. Row annotations colour-code the sender and receiver cell types.

Usage

plotCCI(x, ...)

## S3 method for class 'blisa'
plotCCI(
  x,
  top_lr = 20,
  top_pairs = 30,
  sender = NULL,
  receiver = NULL,
  colors = NULL,
  colours = NULL,
  ...
)

## Default S3 method:
plotCCI(
  x,
  top_lr = 20,
  top_pairs = 30,
  sender = NULL,
  receiver = NULL,
  colors = NULL,
  colours = NULL,
  ...
)

Arguments

x	A blisa object or a CCI scores data frame (the CCI_scores slot of a blisa object). The data frame must contain columns Sender, Receiver, and one column per LR pair.
...	Additional arguments passed to the relevant method.
top_lr	Integer or NULL. Number of top-ranked LR pairs (by sig_numbers) to display as columns. LR pairs in CCI_scores are already ordered by rank, so this simply takes the first top_lr columns. Default 20.
top_pairs	Integer or NULL. Number of top sender-receiver pairs to display as rows, ranked by their maximum interaction score across the displayed LR pairs (after top_lr is applied). When NULL all rows are shown. Default 30.
sender	Character vector or NULL. If provided, only rows where Sender is in this vector are kept. Applied independently of receiver (AND logic when both are supplied). Default NULL (all senders).
receiver	Character vector or NULL. If provided, only rows where Receiver is in this vector are kept. Applied independently of sender (AND logic when both are supplied). Default NULL (all receivers).
colors	Named character vector mapping cell-type names to colours, used for the sender/receiver row annotations. When NULL (default), colours are assigned automatically from the package palette. The British spelling colours is accepted as an alias.
colours	Alias for colors (British spelling). Ignored when colors is supplied.

Value

Invisibly returns the Heatmap object.

Methods (by class)

• plotCCI(blisa): Method for a blisa object. Extracts CCI_scores and delegates to plotCCI.default. Stops with an informative error if CCI_scores is NULL.

• plotCCI(default): Method for a CCI scores data frame (e.g. the CCI_scores slot of a blisa object).

See Also

plotCCILR for a sender-by-receiver heatmap of a single LR pair; plotCCIsummary for an aggregated sender-by-receiver heatmap across all LR pairs.

---

Sender-by-receiver heatmap of CCI scores for one ligand-receptor pair

Description

Generic function. Reshapes the CCI data frame into a receiver-by-sender cell-type matrix for one selected LR pair and draws a clustered heatmap.

Usage

plotCCILR(x, ...)

## S3 method for class 'blisa'
plotCCILR(x, index = 1, ligand = NULL, receptor = NULL, ...)

## Default S3 method:
plotCCILR(x, lr_pair, ...)

Arguments

x	A blisa object or a CCI scores data frame (the CCI_scores slot of a blisa object).
...	Additional arguments passed to the relevant method.
index	Integer. Row index into LR_results selecting the ligand-receptor pair to visualise. Ignored when both ligand and receptor are supplied. Default 1 (top-ranked pair).
ligand	Character. Ligand gene symbol. When both ligand and receptor are provided the matching LR pair is located automatically and index is ignored. Must be supplied together with receptor.
receptor	Character. Receptor gene symbol. Must be supplied together with ligand.
lr_pair	Character. Column name in the CCI scores data frame corresponding to the ligand-receptor pair to visualise (e.g. "CXCL12_CXCR4").

Value

A Heatmap object.

Methods (by class)

• plotCCILR(blisa): Method for a blisa object. The LR pair is selected by index (default 1, the top-ranked pair) unless both ligand and receptor are supplied, in which case the matching row is located automatically and index is ignored. Stops with an informative error if CCI_scores is NULL or the selected LR pair has no significant hotspots.

• plotCCILR(default): Method for a CCI scores data frame (e.g. the CCI_scores slot of a blisa object). The LR pair is selected by column name via lr_pair.

See Also

plotCCI for an overview heatmap across all LR pairs; plotCCIsummary for an aggregated sender-by-receiver heatmap.

---

Spatial map of dominant sender-receiver cell-type pairs at BLISA hotspots

Description

For a selected ligand-receptor pair, identifies the dominant interacting cell-type pair at each significant hotspot bin and draws a spatial map of the tissue coloured by those pairs. Receiver cells are those inside hotspot bins; sender cells are drawn from the immediate neighbourhood.

Usage

plotCCIspatial(
  x,
  counts_by_group,
  index = 1,
  ligand = NULL,
  receptor = NULL,
  top_pairs = 30
)

Arguments

x	A blisa object as returned by blisa.
counts_by_group	Named list of gene-by-bin count matrices, one per cell type. Typically the counts_by_group element returned by hexBinCells. Names must match the cell-type levels.
index	Integer. Row index into x$LR_results selecting the ligand-receptor pair to visualise. Ignored when both ligand and receptor are supplied. Default 1 (top-ranked pair).
ligand	Character. Ligand gene symbol. When both ligand and receptor are provided the matching LR pair is located automatically and index is ignored. Must be supplied together with receptor.
receptor	Character. Receptor gene symbol. Must be supplied together with ligand.
top_pairs	Integer. Maximum number of distinct cell-type pairs to show in the legend; remaining pairs are grouped as "rare pairs". Default 30.

Value

A ggplot object.

See Also

plotHotspots for a significance-based spatial map of hotspot bins.

---

Sender-by-receiver heatmap of aggregated CCI scores across LR pairs

Description

Generic function. Aggregates CCI scores across all (or the top-ranked) ligand-receptor pairs and draws a clustered receiver-by-sender heatmap, one cell per Sender $\rightarrow$ Receiver combination.

Usage

plotCCIsummary(x, ...)

## S3 method for class 'blisa'
plotCCIsummary(
  x,
  top_lr = NULL,
  sender = NULL,
  receiver = NULL,
  agg_fun = sum,
  ...
)

## Default S3 method:
plotCCIsummary(
  x,
  top_lr = NULL,
  sender = NULL,
  receiver = NULL,
  agg_fun = sum,
  ...
)

Arguments

x	A blisa object or a CCI scores data frame (the CCI_scores slot of a blisa object).
...	Additional arguments passed to the relevant method.
top_lr	Integer or NULL. Number of top-ranked LR pairs (by sig_numbers) to include before aggregating. LR pairs in CCI_scores are already ordered by rank, so this takes the first top_lr columns. NULL (default) uses all pairs.
sender	Character vector or NULL. If provided, only rows where Sender is in this vector are kept (AND logic with receiver). Default NULL (all senders).
receiver	Character vector or NULL. If provided, only rows where Receiver is in this vector are kept (AND logic with sender). Default NULL (all receivers).
agg_fun	Function used to aggregate scores across LR pairs for each Sender $\rightarrow$ Receiver combination. Receives a numeric vector with NAs already removed. Default sum.

Value

A Heatmap object.

Methods (by class)

• plotCCIsummary(blisa): Method for a blisa object. Stops with an informative error if CCI_scores is NULL.

• plotCCIsummary(default): Method for a CCI scores data frame (e.g. the CCI_scores slot of a blisa object).

See Also

plotCCILR for a per-LR-pair version of this plot; plotCCI for a heatmap with LR pairs as columns.

---

Spatial hotspot map for one ligand-receptor pair

Description

Generic function. Plots each bin coloured by significance status: empty, non-significant, or significant hotspot (continuous gradient of -log10 p-value or 1 - p-value).

Usage

plotHotspots(x, ...)

## S3 method for class 'blisa'
plotHotspots(
  x,
  index = 1,
  ligand = NULL,
  receptor = NULL,
  log_pval = TRUE,
  p_cutoff = NULL,
  ...
)

Arguments

x	A blisa object.
...	Additional arguments passed to the method.
index	Integer. Row index into LR_results selecting the ligand-receptor pair to visualise. Ignored when both ligand and receptor are supplied. Default 1 (top-ranked pair).
ligand	Character. Ligand gene symbol. When both ligand and receptor are provided the matching LR pair is located automatically and index is ignored. Must be supplied together with receptor.
receptor	Character. Receptor gene symbol. Must be supplied together with ligand.
log_pval	Logical. If TRUE (default), colour significant bins by -log10(p-value). If FALSE, use 1 - p-value.
p_cutoff	Numeric or NULL. When NULL (default), the pre-computed hotspot bins stored in the blisa object are used, reflecting the p_cutoff and High-High quadrant classification applied during blisa. When a numeric value is supplied, bins are re-defined on the fly as those with all_pval <= p_cutoff and quadrant label "High-High" (from the stored all_quadrant), giving an exact re-threshold consistent with the original classification.

Value

A ggplot object.

Methods (by class)

• plotHotspots(blisa): Method for a blisa object.

---

Dot plot ranking LR pairs by number of significant hotspot bins

Description

Generic function for ranking LR pairs. Dispatches on the class of x:

• plotLRrank.blisa accepts a blisa object and uses its LR_results slot directly.

• plotLRrank.data.frame accepts the LR_results data frame directly.

Usage

plotLRrank(x, ...)

## S3 method for class 'blisa'
plotLRrank(x, top = 30, pt_size = 4, flip = FALSE, ...)

## S3 method for class 'data.frame'
plotLRrank(x, top = 30, pt_size = 4, flip = FALSE, ...)

Arguments

x	A blisa object or a data frame of LR results. The data frame must contain columns sig_numbers and annotation.
...	Additional arguments passed to the relevant method.
top	Integer or NULL. Number of top LR pairs (by sig_numbers) to display. Default 30.
pt_size	Numeric. Point size passed to geom_point. Default 4.
flip	Logical. When TRUE, LR pairs are placed on the x-axis and the hotspot count on the y-axis (vertical orientation). Default FALSE (LR pairs on y-axis, horizontal orientation).

Value

A ggplot object.

Methods (by class)

• plotLRrank(blisa): Method for a blisa object. Extracts LR_results and delegates to plotLRrank.data.frame.

• plotLRrank(data.frame): Method for a data frame of LR results (e.g. the LR_results slot of a blisa object).

---

Score cell-cell interactions from BLISA hotspots

Description

Generic function for scoring cell-cell interactions. Dispatches on the class of x:

• runCCI.blisa accepts a blisa object. If CCI_scores are already present and overwrite = FALSE (the default), the object is returned unchanged. Set overwrite = TRUE with a counts_by_group to recompute and replace existing scores. If no scores exist, counts_by_group must be supplied and scores are computed and attached.

• runCCI.default performs the raw computation given a blisa object and a counts_by_group list, returning only the scores data frame. Used internally by runCCI.blisa and blisa.default.

Usage

runCCI(x, ...)

## S3 method for class 'blisa'
runCCI(x, counts_by_group = NULL, overwrite = FALSE, ...)

## Default S3 method:
runCCI(x, counts_by_group, ...)

Arguments

x	A blisa object.
...	Additional arguments passed to the relevant method.
counts_by_group	Named list of gene-by-bin sparse count matrices, one per group level (e.g. cell type). Typically the counts_by_group element of the list returned by hexBinCells when group is supplied. Names must match the group levels. Required when x$CCI_scores is NULL or when overwrite = TRUE.
overwrite	Logical. If FALSE (default) and x$CCI_scores is already populated, the object is returned unchanged. If TRUE and counts_by_group is supplied, existing scores are recomputed and replaced.

Value

See individual method documentation.

runCCI.blisa: the input blisa object with CCI_scores populated (a wide data frame – rows are "Sender->Receiver" group pairs, columns are LR pairs).

runCCI.default: a data frame with "Sender->Receiver" row names and one column per significant LR pair containing the interaction score 0.5 * log2(receiver * sender + 1).

Methods (by class)

• runCCI(blisa): Method for a blisa object. If CCI_scores are already present and overwrite = FALSE (the default), the object is returned unchanged. Set overwrite = TRUE with a counts_by_group to recompute and replace existing scores. If no scores exist, counts_by_group must be supplied and scores are computed and attached to x$CCI_scores.

• runCCI(default): Default method. Performs the raw CCI computation and returns only the scores data frame. Typically called internally; use runCCI.blisa to compute and attach scores to a blisa object in one step.

---