Add Unified Neighborhood Edge Aggregation to a NICHESObject
Source:R/add_neighborhood_edge_agg.R
add_neighborhood_edge_agg.RdFor each focal cell and each LRM pair, aggregates LR communication scores
across all edges in the cell's neighborhood. Each neighborhood edge is
classified into one of five mutually exclusive categories relative to the
focal cell: out (focal cell sends), in (focal cell receives),
cross (neither endpoint is the focal cell), self.autocrine
(focal cell's own self-loop: SendingCell == ReceivingCell == focal cell), or
other.autocrine (a neighbor cell's self-loop: SendingCell ==
ReceivingCell != focal cell).
Arguments
- niches.obj
A
NICHESObjectwith neighborhood slots populated.- n.cores
Positive integer. Retained for API compatibility; not used in the current sparse matrix implementation. Default
1L.- chunk.size
Positive integer. Number of LRM pairs processed per sparse matrix batch. Smaller values reduce peak memory at the cost of slightly more overhead; larger values are faster but require more RAM. Default
50L(about 12 batches for 558 LRMs). Reduce to between20Land30Lon memory-constrained machines.- verbose
Logical. Emit progress messages. Default
TRUE.
Details
All three score methods (sum, mean, cmean) and the
in/out ratio are always computed. The slot is always fully replaced on each
call – there is no incremental update mode. This follows the same
convention as Seurat slot-populating functions: call the function when you
want a fresh result.
Results are stored as a sparse data.table keyed on (cell, LRM) at
$aggregations$neighborhood.edge.agg. Only (cell, LRM) pairs
with at least one non-zero-score neighborhood edge are included.
Five-way edge classification
For a focal cell F and an edge (S -> R) in F's neighborhood:
self.autocrineS == R == F. F's own self-loop edge. Checked first.
count.self.autocrineis always 0 or 1 per (cell, LRM).other.autocrineS == R != F. A neighbor cell's self-loop edge; F is not the self-looping cell.
outS == F and S != R. Focal cell is the sender.
inR == F and S != R. Focal cell is the receiver.
crossS != F and R != F and S != R. Edge between two neighbors; focal cell is not involved.
Columns produced
Count columns (always produced):
count.in,count.out,count.cross,count.self.autocrine,count.other.autocrineNumber of non-zero-score edges in each category for this LRM. Because
$edge.datais sparse, every stored row represents an active edge.count.self.autocrineis always 0 or 1 per (cell, LRM).count.totalSum of all five category counts.
Score columns (all three methods always produced, for each category):
score.{cat}.sumTotal score across category edges.
score.{cat}.meanSum divided by total neighborhood edges (
$neighborhood.meta$n.edges), including zero-score edges. LRM-agnostic denominator.score.{cat}.cmeanConditional mean: sum divided by the category count.
NAwhen count is zero.score.inout.ratioscore.in.sum / score.out.sum.NAwhenscore.out.sum == 0.
Examples
# \donttest{
data(NICHESv2_example)
obj <- add_neighborhood_edge_agg(NICHESv2_example, n.cores = 1L)
#> [add_neighborhood_edge_agg] Aggregating 80 cells x 15 LRMs x 1364 neighborhood edges (chunk.size = 50) ...
#> [add_neighborhood_edge_agg] chunk 1 / 1 done.
#> [add_neighborhood_edge_agg] Done. 399 rows | 74 cells | 15 LRM pairs.
head(obj$aggregations$neighborhood.edge.agg)
#> Key: <cell, LRM>
#> cell LRM count.in count.out count.cross count.self.autocrine
#> <char> <char> <int> <int> <int> <int>
#> 1: Cell_1 Gene11|Gene12 1 0 0 1
#> 2: Cell_1 Gene13|Gene14 0 0 1 0
#> 3: Cell_1 Gene15|Gene16 0 0 0 0
#> 4: Cell_1 Gene17|Gene18 0 0 0 0
#> 5: Cell_1 Gene3|Gene4 1 0 0 0
#> 6: Cell_1 Gene9|Gene10 1 0 0 1
#> count.other.autocrine count.total score.in.sum score.out.sum score.cross.sum
#> <int> <int> <num> <num> <num>
#> 1: 0 2 10 0 0
#> 2: 0 1 0 0 8
#> 3: 1 1 0 0 0
#> 4: 1 1 0 0 0
#> 5: 0 1 48 0 0
#> 6: 0 2 21 0 0
#> score.self.autocrine.sum score.other.autocrine.sum score.total.sum
#> <num> <num> <num>
#> 1: 12 0 22
#> 2: 0 0 8
#> 3: 0 35 35
#> 4: 0 6 6
#> 5: 0 0 48
#> 6: 14 0 35
#> score.in.mean score.out.mean score.cross.mean score.self.autocrine.mean
#> <num> <num> <num> <num>
#> 1: 0.5882353 0 0.0000000 0.7058824
#> 2: 0.0000000 0 0.4705882 0.0000000
#> 3: 0.0000000 0 0.0000000 0.0000000
#> 4: 0.0000000 0 0.0000000 0.0000000
#> 5: 2.8235294 0 0.0000000 0.0000000
#> 6: 1.2352941 0 0.0000000 0.8235294
#> score.other.autocrine.mean score.total.mean score.in.cmean score.out.cmean
#> <num> <num> <num> <num>
#> 1: 0.0000000 1.2941176 10 NA
#> 2: 0.0000000 0.4705882 NA NA
#> 3: 2.0588235 2.0588235 NA NA
#> 4: 0.3529412 0.3529412 NA NA
#> 5: 0.0000000 2.8235294 48 NA
#> 6: 0.0000000 2.0588235 21 NA
#> score.cross.cmean score.self.autocrine.cmean score.other.autocrine.cmean
#> <num> <num> <num>
#> 1: NA 12 NA
#> 2: 8 NA NA
#> 3: NA NA 35
#> 4: NA NA 6
#> 5: NA NA NA
#> 6: NA 14 NA
#> score.total.cmean score.inout.ratio
#> <num> <num>
#> 1: 11.0 NA
#> 2: 8.0 NA
#> 3: 35.0 NA
#> 4: 6.0 NA
#> 5: 48.0 NA
#> 6: 17.5 NA
# }