Compute Local Coherence of a Vector Field

This function calculates the local coherence of a cell-wise vector field (e.g., perturbation vectors) based on a cell–cell neighborhood graph. For each cell, it measures how similar the vectors of its neighbors are to the cell's own vector, using cosine similarity. The result is a per-cell numeric vector of coherence values.

Usage

VectorFieldCoherence(
  seurat_obj,
  perturbation_name,
  reduction = "umap",
  graph = "RNA_nn",
  n_threads = 4,
  arrow_scale = 1,
  max_pct = 0.9,
  weighted = FALSE
)

Arguments

seurat_obj

A Seurat object containing the neighborhood graph and the perturbation vectors.

perturbation_name

Name of the perturbation assay or matrix used to compute the cell-wise vectors (passed to PerturbationVectors).

reduction

Character. Dimensionality reduction to use for the vector representation (default: "umap").

graph

Character. Name of the graph slot in the Seurat object (e.g. "RNA_nn" or "RNA_snn") used to define cell neighborhoods.

n_threads

Integer. Number of threads to use (currently not implemented for parallelization, but reserved for future use).

arrow_scale

Numeric. Scaling factor for arrow (vector) lengths passed to PerturbationVectors.

max_pct

Numeric. Maximum percentile of vector magnitudes to keep when scaling (passed to PerturbationVectors).

weighted

Logical. If TRUE, coherence is computed as a weighted average of neighbor similarities using the edge weights from the graph; if FALSE, an unweighted mean is used.

Value

A numeric vector of length equal to the number of cells, containing the local coherence score for each cell. Higher values indicate that a cell’s vector is more aligned with its neighbors’ vectors.

Details

Local coherence quantifies directional agreement of perturbation vectors within the local neighborhood of each cell. Cosine similarity is used to measure alignment between a cell's vector and those of its neighbors. Weighted coherence accounts for edge weights in the neighborhood graph (e.g. from SNN graphs).