Calculate spatially-weighted metabolite-mediated communication. This function incorporates spatial distance between spots to weight communication strength.
computeSpatialCommunication(
object,
method = "knn",
k_neighbors = 6,
symmetric = TRUE,
distance_threshold = 150,
sigma = 50,
lambda = 50,
comm_method = "geometric",
min_production = 0.1,
min_sensing = 0.1,
analysis_level = "region",
n_permutations = 1000,
n_cores = 1,
seed = 42,
verbose = TRUE
)A scMetaLink object with spatial information and production/sensing scores
Character. Spatial weighting method:
"knn": K-nearest neighbors only (recommended for Visium, most honest given the resolution limitations)
"gaussian": Gaussian decay exp(-d^2/2*sigma^2)
"exponential": Exponential decay exp(-d/lambda)
"linear": Linear decay max(0, 1 - d/d_max)
"threshold": Binary cutoff (1 if d <= threshold, 0 otherwise)
Integer. Number of nearest neighbors for knn method. Default: 6. For Visium hexagonal grid, 6 corresponds to immediate neighbors. **Note**: The weight matrix is symmetrized, so actual neighbor count per spot may exceed k (typically k to 2k).
Logical. Whether to symmetrize the KNN weight matrix (default: TRUE). If TRUE, when spot A is a neighbor of B, B is also considered a neighbor of A. This ensures bidirectional communication potential.
Numeric. Maximum distance for communication in micrometers. Spot pairs beyond this distance are considered non-interacting. Default: 150 um. Note: Most metabolites have effective diffusion ranges of 10-200 um in tissue. For Visium data (100 um spot spacing), values >200 um are rarely meaningful.
Numeric. Sigma parameter for Gaussian decay (in um). Default: 50 um. Represents the characteristic decay distance. Literature suggests:
Fast-turnover metabolites (adenosine, ATP): 20-30 um
Medium-range metabolites (lactate): 50-80 um
Stable metabolites (amino acids): 80-120 um
Numeric. Lambda parameter for exponential decay (in um). Default: 50 um.
Character. Communication score method: "geometric", "product", "harmonic"
Numeric. Minimum production score threshold (0-1). Cell types with production score below this are considered non-producers.
Numeric. Minimum sensing score threshold (0-1). Cell types with sensing score below this are considered non-sensors.
Character. Level of analysis:
"region": Aggregate by cell type (default, recommended). Uses the full inferProduction/inferSensing logic.
"spot": Compute spot-to-spot communication. **WARNING**: This is a simplified implementation for exploratory analysis. It does NOT include: degradation adjustment, secretion weighting, Hill transformation, or full normalization. Use for hotspot identification only.
Integer. Number of permutations for significance testing. Default: 1000. For publication, recommend >= 1000 permutations. The permutation test shuffles cell type labels while preserving spatial structure, then **recalculates production and sensing scores** from scratch (consistent with non-spatial version), which is the scientifically correct null model for testing whether communication patterns are associated with cell type identity.
Integer. Number of cores for parallel computing
Integer. Random seed for reproducibility
Logical. Print progress messages
Updated scMetaLink object with spatial_communication slot
**Important Notes on Spatial Resolution:**
For Visium data (55 um spots, ~100 um spacing), each spot contains 1-10 cells. This means:
Cell type annotations should ideally come from deconvolution methods (e.g., RCTD, cell2location, SPOTlight)
The "knn" method (k=6) is recommended as it only considers immediate neighbors, which is most honest given the resolution limitations
Distance-weighted methods (gaussian, exponential) may provide "false precision" when spot spacing is similar to metabolite diffusion distance
**Permutation Test Design:**
The permutation test shuffles cell type labels (not spatial positions) and **recalculates production/sensing scores from expression data**. This is consistent with the non-spatial version and tests whether the observed communication pattern is associated with cell type identity beyond what would be expected by chance.
**Spatial communication is modeled as:** $$C_{spatial}(i -> j, m) = MPP(m, i) * MSC(m, j) * w(d_{ij})$$
where w(d) is the spatial weight function:
Gaussian: w(d) = exp(-d^2 / 2*sigma^2)
Exponential: w(d) = exp(-d / lambda)
Linear: w(d) = max(0, 1 - d/d_max)
Threshold: w(d) = I(d <= d_threshold)
# \donttest{
data(st_expr)
data(st_meta)
data(st_scalefactors)
# Create object and run analysis
obj <- createScMetaLinkFromSpatial(st_expr, st_meta[,c("x","y")],
st_meta, "cell_type", st_scalefactors)
#> Created spatial scMetaLink object with 4284 genes, 1000 spots, 6 cell types
obj <- inferProduction(obj)
#> Inferring production potential for 6 cell types...
#> Calculating cell type expression profiles...
#> Building metabolite-gene mapping...
#> Found 15699 production enzyme-metabolite pairs
#> Computing production scores (matrix multiplication)...
#> Adjusting for degradation...
#> Applying secretion potential weights...
#> Normalizing scores...
#> Computed production scores for 796 metabolites
#> Done!
obj <- inferSensing(obj)
#> Inferring sensing capability for 6 cell types...
#> Calculating cell type expression profiles...
#> Building metabolite-receptor mapping...
#> Found 12959 receptor-metabolite pairs
#> Computing sensing scores (matrix multiplication)...
#> Normalizing scores...
#> Computed sensing scores for 499 metabolites
#> Done!
# Compute spatial communication (knn method recommended for Visium)
obj <- computeSpatialCommunication(obj, method = "knn", k_neighbors = 6)
#> Computing spatial communication (region level)...
#> Method: knn, threshold: 150 um, 1000 spots
#> Computing distance matrix...
#> Computing spatial weights...
#> Metabolites: 288, Cell types: 6
#> Running 1000 spatial permutations...
#>
|
| | 0%
|
| | 1%
|
|= | 1%
|
|= | 2%
|
|== | 2%
|
|== | 3%
|
|== | 4%
|
|=== | 4%
|
|=== | 5%
|
|==== | 5%
|
|==== | 6%
|
|===== | 6%
|
|===== | 7%
|
|===== | 8%
|
|====== | 8%
|
|====== | 9%
|
|======= | 9%
|
|======= | 10%
|
|======= | 11%
|
|======== | 11%
|
|======== | 12%
|
|========= | 12%
|
|========= | 13%
|
|========= | 14%
|
|========== | 14%
|
|========== | 15%
|
|=========== | 15%
|
|=========== | 16%
|
|============ | 16%
|
|============ | 17%
|
|============ | 18%
|
|============= | 18%
|
|============= | 19%
|
|============== | 19%
|
|============== | 20%
|
|============== | 21%
|
|=============== | 21%
|
|=============== | 22%
|
|================ | 22%
|
|================ | 23%
|
|================ | 24%
|
|================= | 24%
|
|================= | 25%
|
|================== | 25%
|
|================== | 26%
|
|=================== | 26%
|
|=================== | 27%
|
|=================== | 28%
|
|==================== | 28%
|
|==================== | 29%
|
|===================== | 29%
|
|===================== | 30%
|
|===================== | 31%
|
|====================== | 31%
|
|====================== | 32%
|
|======================= | 32%
|
|======================= | 33%
|
|======================= | 34%
|
|======================== | 34%
|
|======================== | 35%
|
|========================= | 35%
|
|========================= | 36%
|
|========================== | 36%
|
|========================== | 37%
|
|========================== | 38%
|
|=========================== | 38%
|
|=========================== | 39%
|
|============================ | 39%
|
|============================ | 40%
|
|============================ | 41%
|
|============================= | 41%
|
|============================= | 42%
|
|============================== | 42%
|
|============================== | 43%
|
|============================== | 44%
|
|=============================== | 44%
|
|=============================== | 45%
|
|================================ | 45%
|
|================================ | 46%
|
|================================= | 46%
|
|================================= | 47%
|
|================================= | 48%
|
|================================== | 48%
|
|================================== | 49%
|
|=================================== | 49%
|
|=================================== | 50%
|
|=================================== | 51%
|
|==================================== | 51%
|
|==================================== | 52%
|
|===================================== | 52%
|
|===================================== | 53%
|
|===================================== | 54%
|
|====================================== | 54%
|
|====================================== | 55%
|
|======================================= | 55%
|
|======================================= | 56%
|
|======================================== | 56%
|
|======================================== | 57%
|
|======================================== | 58%
|
|========================================= | 58%
|
|========================================= | 59%
|
|========================================== | 59%
|
|========================================== | 60%
|
|========================================== | 61%
|
|=========================================== | 61%
|
|=========================================== | 62%
|
|============================================ | 62%
|
|============================================ | 63%
|
|============================================ | 64%
|
|============================================= | 64%
|
|============================================= | 65%
|
|============================================== | 65%
|
|============================================== | 66%
|
|=============================================== | 66%
|
|=============================================== | 67%
|
|=============================================== | 68%
|
|================================================ | 68%
|
|================================================ | 69%
|
|================================================= | 69%
|
|================================================= | 70%
|
|================================================= | 71%
|
|================================================== | 71%
|
|================================================== | 72%
|
|=================================================== | 72%
|
|=================================================== | 73%
|
|=================================================== | 74%
|
|==================================================== | 74%
|
|==================================================== | 75%
|
|===================================================== | 75%
|
|===================================================== | 76%
|
|====================================================== | 76%
|
|====================================================== | 77%
|
|====================================================== | 78%
|
|======================================================= | 78%
|
|======================================================= | 79%
|
|======================================================== | 79%
|
|======================================================== | 80%
|
|======================================================== | 81%
|
|========================================================= | 81%
|
|========================================================= | 82%
|
|========================================================== | 82%
|
|========================================================== | 83%
|
|========================================================== | 84%
|
|=========================================================== | 84%
|
|=========================================================== | 85%
|
|============================================================ | 85%
|
|============================================================ | 86%
|
|============================================================= | 86%
|
|============================================================= | 87%
|
|============================================================= | 88%
|
|============================================================== | 88%
|
|============================================================== | 89%
|
|=============================================================== | 89%
|
|=============================================================== | 90%
|
|=============================================================== | 91%
|
|================================================================ | 91%
|
|================================================================ | 92%
|
|================================================================= | 92%
|
|================================================================= | 93%
|
|================================================================= | 94%
|
|================================================================== | 94%
|
|================================================================== | 95%
|
|=================================================================== | 95%
|
|=================================================================== | 96%
|
|==================================================================== | 96%
|
|==================================================================== | 97%
|
|==================================================================== | 98%
|
|===================================================================== | 98%
|
|===================================================================== | 99%
|
|======================================================================| 99%
|
|======================================================================| 100%
#> Done!
# Alternative: Gaussian decay with conservative parameters
obj <- computeSpatialCommunication(obj, method = "gaussian",
sigma = 50, # 50 um decay
distance_threshold = 150) # max 150 um
#> Computing spatial communication (region level)...
#> Method: gaussian, threshold: 150 um, 1000 spots
#> Computing distance matrix...
#> Computing spatial weights...
#> Metabolites: 288, Cell types: 6
#> Running 1000 spatial permutations...
#>
|
| | 0%
|
| | 1%
|
|= | 1%
|
|= | 2%
|
|== | 2%
|
|== | 3%
|
|== | 4%
|
|=== | 4%
|
|=== | 5%
|
|==== | 5%
|
|==== | 6%
|
|===== | 6%
|
|===== | 7%
|
|===== | 8%
|
|====== | 8%
|
|====== | 9%
|
|======= | 9%
|
|======= | 10%
|
|======= | 11%
|
|======== | 11%
|
|======== | 12%
|
|========= | 12%
|
|========= | 13%
|
|========= | 14%
|
|========== | 14%
|
|========== | 15%
|
|=========== | 15%
|
|=========== | 16%
|
|============ | 16%
|
|============ | 17%
|
|============ | 18%
|
|============= | 18%
|
|============= | 19%
|
|============== | 19%
|
|============== | 20%
|
|============== | 21%
|
|=============== | 21%
|
|=============== | 22%
|
|================ | 22%
|
|================ | 23%
|
|================ | 24%
|
|================= | 24%
|
|================= | 25%
|
|================== | 25%
|
|================== | 26%
|
|=================== | 26%
|
|=================== | 27%
|
|=================== | 28%
|
|==================== | 28%
|
|==================== | 29%
|
|===================== | 29%
|
|===================== | 30%
|
|===================== | 31%
|
|====================== | 31%
|
|====================== | 32%
|
|======================= | 32%
|
|======================= | 33%
|
|======================= | 34%
|
|======================== | 34%
|
|======================== | 35%
|
|========================= | 35%
|
|========================= | 36%
|
|========================== | 36%
|
|========================== | 37%
|
|========================== | 38%
|
|=========================== | 38%
|
|=========================== | 39%
|
|============================ | 39%
|
|============================ | 40%
|
|============================ | 41%
|
|============================= | 41%
|
|============================= | 42%
|
|============================== | 42%
|
|============================== | 43%
|
|============================== | 44%
|
|=============================== | 44%
|
|=============================== | 45%
|
|================================ | 45%
|
|================================ | 46%
|
|================================= | 46%
|
|================================= | 47%
|
|================================= | 48%
|
|================================== | 48%
|
|================================== | 49%
|
|=================================== | 49%
|
|=================================== | 50%
|
|=================================== | 51%
|
|==================================== | 51%
|
|==================================== | 52%
|
|===================================== | 52%
|
|===================================== | 53%
|
|===================================== | 54%
|
|====================================== | 54%
|
|====================================== | 55%
|
|======================================= | 55%
|
|======================================= | 56%
|
|======================================== | 56%
|
|======================================== | 57%
|
|======================================== | 58%
|
|========================================= | 58%
|
|========================================= | 59%
|
|========================================== | 59%
|
|========================================== | 60%
|
|========================================== | 61%
|
|=========================================== | 61%
|
|=========================================== | 62%
|
|============================================ | 62%
|
|============================================ | 63%
|
|============================================ | 64%
|
|============================================= | 64%
|
|============================================= | 65%
|
|============================================== | 65%
|
|============================================== | 66%
|
|=============================================== | 66%
|
|=============================================== | 67%
|
|=============================================== | 68%
|
|================================================ | 68%
|
|================================================ | 69%
|
|================================================= | 69%
|
|================================================= | 70%
|
|================================================= | 71%
|
|================================================== | 71%
|
|================================================== | 72%
|
|=================================================== | 72%
|
|=================================================== | 73%
|
|=================================================== | 74%
|
|==================================================== | 74%
|
|==================================================== | 75%
|
|===================================================== | 75%
|
|===================================================== | 76%
|
|====================================================== | 76%
|
|====================================================== | 77%
|
|====================================================== | 78%
|
|======================================================= | 78%
|
|======================================================= | 79%
|
|======================================================== | 79%
|
|======================================================== | 80%
|
|======================================================== | 81%
|
|========================================================= | 81%
|
|========================================================= | 82%
|
|========================================================== | 82%
|
|========================================================== | 83%
|
|========================================================== | 84%
|
|=========================================================== | 84%
|
|=========================================================== | 85%
|
|============================================================ | 85%
|
|============================================================ | 86%
|
|============================================================= | 86%
|
|============================================================= | 87%
|
|============================================================= | 88%
|
|============================================================== | 88%
|
|============================================================== | 89%
|
|=============================================================== | 89%
|
|=============================================================== | 90%
|
|=============================================================== | 91%
|
|================================================================ | 91%
|
|================================================================ | 92%
|
|================================================================= | 92%
|
|================================================================= | 93%
|
|================================================================= | 94%
|
|================================================================== | 94%
|
|================================================================== | 95%
|
|=================================================================== | 95%
|
|=================================================================== | 96%
|
|==================================================================== | 96%
|
|==================================================================== | 97%
|
|==================================================================== | 98%
|
|===================================================================== | 98%
|
|===================================================================== | 99%
|
|======================================================================| 99%
|
|======================================================================| 100%
#> Done!
# }