renoir-spatial 1.0.0

Charting spatial ligand-target activity using Renoir (ligand-taRgEt iNteractions acrOss spatIal topogRaphy)

Charting spatial ligand-target activity using Renoir

Renoir is an information-theory-based scoring metric for quantifying the activity between a ligand and its target gene given a specific spatial context. Renoir can also infer spatial communication domains that harbor similar ligand-target activities. Renoir also identifies spatially enriched ligand-target gene sets (pathway activity) and characterizes domain-specific activities between ligands and targets.

Requirements

All requirements are provided in the renoir.yml file. It is recommended to utilize the same versions as provided in renoir.yml file.

Quick Start

This example walks through a complete Renoir workflow on a 10x Genomics Visium spatial transcriptomics dataset.

Installation

Via: pip

pip install renoir-spatial

Via: conda

conda env create -f renoir.yml
pip install .

Note: cell2location must be installed separately. See cell2location installation.

---

Step 1 — Imports

import Renoir
import scanpy as sc
import pandas as pd
import numpy as np

---

Step 2 — Required inputs

Renoir requires the following input files:

Input	Description
ST_path	Spatial transcriptomics AnnData (.h5ad)
SC_path	Matched scRNA-seq reference AnnData with annotated cell types (.h5ad)
pairs_path	CSV of ligand–target pairs to score
ligand_receptor_path	Curated ligand–receptor pair table (e.g. from NATMI / OmniPath)
celltype_proportions_path	CSV of per-spot cell-type proportions (e.g. from cell2location)
expins_path	Cell-type-specific mRNA abundance pickle (see format note below)

mRNA abundance file format

mRNA_abundance.pkl must be a dictionary where each key is a gene name and each value is the cell-type-specific mRNA abundance for that gene across all spots. Two formats are supported:

Format 1 — dictionary of DataFrames:

{
    'GENE1': pd.DataFrame(  # shape: (n_spots, n_celltypes)
        index=['spot_1', 'spot_2', ...],       # spot barcodes
        columns=['CellType_A', 'CellType_B', ...],
    ),
    'GENE2': pd.DataFrame(...),
    ...
}

Each cell in the DataFrame holds the expression of that gene attributed to that cell type in that spot.

Format 2 — dictionary of CSR matrices with shared index keys:

{
    'GENE1': scipy.sparse.csr_matrix(...),  # shape: (n_spots, n_celltypes)
    'GENE2': scipy.sparse.csr_matrix(...),
    ...
    'cells':     ['spot_1', 'spot_2', ...],  # row indices, shared across all matrices
    'celltypes': ['CellType_A', 'CellType_B', ...],  # column indices, shared across all matrices
}

In Format 2, the 'cells' and 'celltypes' keys provide the row and column labels shared across all gene matrices.

Cell-type-specific mRNA abundance values can be computed from cell2location. Currently Renoir also provides a naïve approach to computing cell-type-specific mRNA abundance by setting expins_path=None in the compute_neighborhood_scores function.

---

Step 3 — Compute neighborhood scores

neighborhood_scores = Renoir.compute_neighborhood_scores(
    SC_path='path/to/scRNA.h5ad',
    ST_path='path/to/ST.h5ad',
    pairs_path='path/to/lt_pairs.csv',
    ligand_receptor_path='path/to/All_human_lrpairs.csv',
    celltype_proportions_path='path/to/celltype_proportions.csv',
    expins_path='path/to/mRNA_abundance.pkl',
)

---

Documentation

For full tutorials including Visium, CosMx, VisiumHD, and Xenium workflows, see the documentation.

References

If you use Renoir, please cite our paper:

Rao, N., Kumar, T., Kazemi, D. et al. Charting spatial ligand-target activity using Renoir. Nature Communications 17, 3983 (2026). https://doi.org/10.1038/s41467-026-72388-7