create_NICHESObject() needs an expression matrix, cell
metadata and an LR database. This guide shows how to prepare each
one.
Expression matrix
count.mtx is a gene-by-cell matrix, sparse or dense. Row
names are gene symbols and column names are cell barcodes.
class(NICHESv2_inputs$count.mtx)
#> [1] "dgCMatrix"
#> attr(,"package")
#> [1] "Matrix"
dim(NICHESv2_inputs$count.mtx)
#> [1] 50 80The values you pass set what the scores mean. Raw counts give absolute magnitudes, and normalized expression gives relative scores. NICHESv2 uses the matrix as it is, so this choice affects which edges score highest.
Cell metadata
meta.data is a data frame with cell barcodes as row
names, matching the matrix columns. What else it needs depends on the
mode:
| Mode | Required columns |
|---|---|
"spatial" |
x and y
|
"nonspatial" |
the column named by cell.type.col
|
Other columns carry through to $cell.meta and appear on
each edge in $edge.meta.
head(NICHESv2_inputs$meta.data, 3)| x | y | nCount_RNA | celltype | |
|---|---|---|---|---|
| Cell_1 | 0.136 | 0.298 | 66 | TypeA |
| Cell_2 | 0.238 | 0.172 | 53 | TypeA |
| Cell_3 | 0.225 | 0.240 | 55 | TypeA |
Several samples
When your data has several samples, set sample.col to
the column that identifies them. Each sample is processed separately and
the results are merged, so no edges cross samples.
Barcodes must be unique across all samples, and a duplicate stops the
merge with an error. Add a prefix first if needed, such as
paste0(sample.id, "_", barcode).
LR databases
Pass one of three database names to LRM.db, or your own
data frame.
| Name | Species | Needs internet |
|---|---|---|
"connectomedb2025" |
human, mouse, rat, pig | No |
"fantom5" |
human, mouse, rat, pig | No |
"omnipath" |
human, mouse, rat | Yes, plus OmnipathR |
create_NICHESObject() has no default database, so always
set LRM.db. Set species to match your data. To
look at a database first:
db <- load_LRM_database("connectomedb2025", species = "mouse", verbose = FALSE)
nrow(db)
#> [1] 3252
head(db[, c("ligand", "receptor")], 3)| ligand | receptor |
|---|---|
| A2m | Lrp1 |
| Ace | Bdkrb2 |
| Adam10 | Epha3 |
Your own database
A custom data frame needs ligand and receptor columns. If they have
other names, set ligand.col and receptor.col.
Multi-gene complexes are written with underscores, and a pair is dropped
if any of its genes is missing from the matrix.
my.db <- data.frame(
L = c("Gene1", "Gene3"),
R = c("Gene2", "Gene4_Gene5")
)
obj <- create_NICHESObject(
count.mtx = NICHESv2_inputs$count.mtx,
meta.data = NICHESv2_inputs$meta.data,
LRM.db = my.db,
ligand.col = "L",
receptor.col = "R",
mode = "spatial",
k = 5L,
verbose = FALSE
)
obj$LRM.list
#> [1] "Gene1|Gene2" "Gene3|Gene4_Gene5"Seurat objects
extract_NICHESInputs_Seurat() needs the SeuratObject
package and reads both V4 and V5 objects, so you don’t need to update an
older object first. It returns count.mtx and
meta.data.
seu <- SeuratObject::CreateSeuratObject(
counts = NICHESv2_inputs$count.mtx,
meta.data = NICHESv2_inputs$meta.data
)
inputs <- extract_NICHESInputs_Seurat(
seu, assay = "RNA", layer = "counts", verbose = FALSE
)
dim(inputs$count.mtx)
#> [1] 50 80Spatial coordinates aren’t copied automatically, because Seurat keeps them with the image. For spatial objects, add them yourself, as shown in the spatial tutorial:
coords <- SeuratObject::GetTissueCoordinates(seurat.obj)
inputs$meta.data$x <- coords[rownames(inputs$meta.data), "x"]
inputs$meta.data$y <- coords[rownames(inputs$meta.data), "y"]AnnData files
extract_NICHESInputs_AnnData() reads .h5ad
files through the rhdf5 package, so Python isn’t needed.
layer = "counts" reads the counts layer, and
obs.cols limits which metadata columns are kept.
h5ad <- system.file("extdata", "NICHESv2_example.h5ad", package = "NICHESv2")
inputs <- extract_NICHESInputs_AnnData(h5ad, layer = "counts", verbose = FALSE)
dim(inputs$count.mtx)
#> [1] 50 80
colnames(inputs$meta.data)
#> [1] "celltype" "nCount_RNA" "x" "y"Install rhdf5 from Bioconductor:
install.packages("BiocManager")
BiocManager::install("rhdf5")