Run the Full Aggregation Pipeline on a NICHESObject
Source:R/aggregate_NICHESObject.R
aggregate_NICHESObject.RdA convenience wrapper that calls all aggregation functions in the correct
dependency order, populating the $aggregations slot in a single
call. Both steps always fully recompute and replace their slots – there
is no incremental update mode. Individual functions can still be called
directly for finer control.
Usage
aggregate_NICHESObject(
niches.obj,
cell.type.col = NULL,
n.cores = 1L,
chunk.size = 50L,
verbose = TRUE
)Arguments
- niches.obj
A
NICHESObjectwith neighborhood slots populated.- cell.type.col
Character or
NULL. Name of the column in$cell.metaholding cell type annotations, passed toadd_neighborhood_composition. WhenNULL(default), step 2 is skipped.- n.cores
Positive integer. Retained for API compatibility; passed to
add_neighborhood_edge_aggbut not currently used by the sparse matrix implementation. Default1L.- chunk.size
Positive integer. Number of LRM pairs processed per sparse matrix batch in
add_neighborhood_edge_agg. Smaller values reduce peak memory; larger values are marginally faster. Default50L. Reduce to between20Land30Lon memory-constrained machines (e.g. laptops); increase on HPC nodes with abundant RAM.- verbose
Logical. Emit progress messages. Default
TRUE.
Value
The input niches.obj with $aggregations populated:
$neighborhood.edge.aggAlways populated (five-category edge aggregation keyed on
(cell, LRM), with all three score methods and in/out ratio).$neighborhood.compositionPopulated when
cell.type.colis provided andmode = "spatial".
Pipeline steps
add_neighborhood_edge_agg: for each focal cell and each LRM pair, aggregates scores across all neighborhood edges using a five-way classification (in, out, cross, self.autocrine, other.autocrine). All three score methods (sum, mean, cmean) and the in/out ratio are always computed. LRM pairs are processed in batches ofchunk.sizeto bound peak memory.add_neighborhood_composition: computes cell-type composition of each cell's local neighborhood from$edge.listand$cell.meta. Skipped ifcell.type.col = NULLor if the object mode is"nonspatial".
Neighborhood slots requirement
Step 1 requires the three neighborhood slots to be populated.
create_NICHESObject populates them automatically using
edge.filter.mode = "both_in_neighborhood" and
remove.autocrine = FALSE, so this requirement is met in the
standard workflow.
Examples
# \donttest{
data(NICHESv2_example)
# Edge aggregation only
obj <- aggregate_NICHESObject(NICHESv2_example, n.cores = 1L)
#> [aggregate_NICHESObject] Starting aggregation pipeline ...
#> [aggregate_NICHESObject] Step 1/2: neighborhood edge aggregation.
#> [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.
#> [aggregate_NICHESObject] Step 2/2: SKIPPED -- 'cell.type.col' not provided. Supply cell.type.col to compute neighborhood composition.
#> [aggregate_NICHESObject] Pipeline complete. Slots populated: neighborhood.edge.agg.
names(obj$aggregations)
#> [1] "neighborhood.edge.agg"
# With cell-type composition
obj <- aggregate_NICHESObject(
NICHESv2_example,
cell.type.col = "celltype",
n.cores = 1L
)
#> [aggregate_NICHESObject] Starting aggregation pipeline ...
#> [aggregate_NICHESObject] Step 1/2: neighborhood edge aggregation.
#> [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.
#> [aggregate_NICHESObject] Step 2/2: neighborhood composition.
#> [add_neighborhood_composition] Computing composition across 80 cells | 3 cell types ...
#> [add_neighborhood_composition] Done. 80 cells | 3 cell types | columns: count + prop.
#> [aggregate_NICHESObject] Pipeline complete. Slots populated: neighborhood.edge.agg, neighborhood.composition.
# }