Edges show individual cell pairs. Aggregation summarizes them for each cell’s neighborhood, which gives you per-cell values to compare across a tissue.
library(NICHESv2)
library(data.table)
data(NICHESv2_example)
obj <- aggregate_NICHESObject(
NICHESv2_example,
cell.type.col = "celltype",
verbose = FALSE
)
names(obj$aggregations)
#> [1] "neighborhood.edge.agg" "neighborhood.composition"aggregate_NICHESObject() runs
add_neighborhood_edge_agg(), then
add_neighborhood_composition() if you pass
cell.type.col. Each run replaces the previous result.
Edge aggregation
$aggregations$neighborhood.edge.agg has 27 columns, with
one row for each (cell, LRM) pair that has signal.
agg <- obj$aggregations$neighborhood.edge.agg
dim(agg)
#> [1] 399 27Five categories
Each edge in a neighborhood falls into one category relative to the focal cell:
| Category | Meaning |
|---|---|
in |
A neighbor sends to the focal cell |
out |
The focal cell sends to a neighbor |
cross |
One neighbor sends to another; the focal cell isn’t involved |
self.autocrine |
The focal cell’s own self-loop |
other.autocrine |
A neighbor’s self-loop |
The cross category captures what a cell’s surroundings
exchange, even when the cell itself takes no part.
Columns
{category} below stands for each of the five categories,
or total for all of them together.
| Column | Meaning |
|---|---|
count.{category} |
Number of edges with signal |
score.{category}.sum |
Total score |
score.{category}.mean |
Total score divided by all edges in the neighborhood, including those with no signal for this LRM |
score.{category}.cmean |
Total score divided by the count, or NA when the count
is zero |
score.inout.ratio |
score.in.sum divided by score.out.sum, or
NA when nothing is sent |
Use mean to compare the overall signal between
neighborhoods of different sizes. Use cmean to see how
strong the signal is on the edges that carry it.
agg[, .(cell, LRM, count.in, score.in.sum, score.in.mean, score.in.cmean)][1:3]| cell | LRM | count.in | score.in.sum | score.in.mean | score.in.cmean |
|---|---|---|---|---|---|
| Cell_1 | Gene11|Gene12 | 1 | 10 | 0.588 | 10 |
| Cell_1 | Gene13|Gene14 | 0 | 0 | 0.000 | NA |
| Cell_1 | Gene15|Gene16 | 0 | 0 | 0.000 | NA |
Edges with no signal for any LR pair still count toward the
mean denominator, which comes from
$neighborhood.meta$n.edges.
Neighborhood composition
$aggregations$neighborhood.composition has one row per
cell, with counts and proportions of neighboring cell types. By default
it counts the focal cell too; pass include.self = FALSE to
add_neighborhood_composition() to leave it out.
comp <- obj$aggregations$neighborhood.composition
head(comp[, .(cell, TypeA.neighbor.prop, TypeB.neighbor.prop, TypeC.neighbor.prop)], 3)| cell | TypeA.neighbor.prop | TypeB.neighbor.prop | TypeC.neighbor.prop |
|---|---|---|---|
| Cell_1 | 1 | 0 | 0 |
| Cell_10 | 1 | 0 | 0 |
| Cell_11 | 1 | 0 | 0 |
This table needs spatial data. In "nonspatial" mode it
stops with an error, because neighbor cell types would only reflect the
sampling.
Subsets
Aggregate the full object first, then subset. Neighborhood slots and aggregation tables are indexed by cell, so each kept cell keeps its rows unchanged. Those values still describe the cell’s whole neighborhood, including neighbors you didn’t keep.
keep <- obj$cell.meta[celltype == "TypeA", cell]
sub <- obj[keep]
identical(
sub$aggregations$neighborhood.edge.agg$score.in.sum,
agg[cell %in% keep]$score.in.sum
)
#> [1] TRUEThe edge slots of a subset keep only edges between kept cells. Two things follow:
- Summing a cell’s rows in
sub$edge.datacan give less than its aggregation row. - A TissuePlex export of the subset shows only those kept edges.
Recalculating on a subset
The removed edges are gone, so a subset can’t recompute full-tissue values, and trying stops with an error:
add_neighborhood_edge_agg(sub, verbose = FALSE)
#> Error:
#> ! [add_neighborhood_edge_agg] This object is a subset whose neighborhoods include edges to removed cells, so aggregations cannot be recomputed on it. Aggregate the full object before subsetting (the results carry over), or run add_neighborhoods(obj, overwrite = TRUE) first to analyze the subset as a separate tissue.Each kept cell already has its correct values, so you rarely need to recalculate. To treat the subset as a separate tissue instead, rebuild its neighborhoods first. This clears the carried-over tables, and the new values use only the kept cells:
separate <- add_neighborhoods(sub, overwrite = TRUE, verbose = FALSE)
separate <- aggregate_NICHESObject(separate, verbose = FALSE)Changing neighborhoods
add_neighborhoods(overwrite = TRUE) can also apply
another edge.filter.mode. It clears existing aggregation
tables, so run aggregation again afterward.
narrow <- add_neighborhoods(
NICHESv2_example,
edge.filter.mode = "central_cell_only",
overwrite = TRUE,
verbose = FALSE
)
narrow <- add_neighborhood_edge_agg(narrow, verbose = FALSE)