Metadata-Version: 2.4
Name: renoir-spatial
Version: 1.0.0
Summary: Charting spatial ligand-target activity using Renoir (ligand-taRgEt iNteractions acrOss spatIal topogRaphy)
Home-page: https://github.com/Zafar-Lab/Renoir
Author: Narein Rao (Zafar-Lab)
Project-URL: Documentation, https://renoir.readthedocs.io/en/latest/
Project-URL: Bug Tracker, https://github.com/Zafar-Lab/Renoir/issues
Project-URL: Source Code, https://github.com/Zafar-Lab/Renoir
Keywords: spatial transcriptomics,cell-cell communication,ligand-target,Visium,CosMx,scRNA-seq,bioinformatics
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: pandas
Requires-Dist: scikit-learn>=1.6.0
Requires-Dist: scanpy>=1.10.4
Requires-Dist: squidpy>=1.6.2
Requires-Dist: anndata
Requires-Dist: leidenalg
Requires-Dist: igraph
Requires-Dist: hdbscan>=0.8.40
Requires-Dist: plotly>=5.24.1
Requires-Dist: distinctipy>=1.3.4
Requires-Dist: matplotlib
Requires-Dist: seaborn
Requires-Dist: harmonypy>=0.0.10
Requires-Dist: dynamictreecut>=0.1.1
Requires-Dist: spatialdata>=0.7.0
Requires-Dist: spatialdata-io
Requires-Dist: spatialdata-plot
Requires-Dist: tqdm
Requires-Dist: setuptools<82
Provides-Extra: test
Requires-Dist: pytest>=7.4; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Charting spatial ligand-target activity using Renoir

<p align="center">
<img src="https://raw.githubusercontent.com/Zafar-Lab/Renoir/main/docs/source/_static/renoir_logo.png" alt="RENOIR" width="300"/>
</p>

[![Tests](https://github.com/Zafar-Lab/Renoir/actions/workflows/test.yaml/badge.svg)](https://github.com/Zafar-Lab/Renoir/actions/workflows/test.yaml)
[![codecov](https://codecov.io/gh/Zafar-Lab/Renoir/graph/badge.svg)](https://app.codecov.io/gh/Zafar-Lab/Renoir)
[![Docs](https://readthedocs.org/projects/renoir/badge/?version=latest)](https://renoir.readthedocs.io/en/latest/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**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.

<p align="center">
<img src="https://raw.githubusercontent.com/Zafar-Lab/Renoir/main/docs/source/images/Overview.png" alt="Overview of RENOIR" width="600"/>
</p>



## 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**
```bash
pip install renoir-spatial
```

**Via: conda**
```bash
conda env create -f renoir.yml
pip install .
```

> **Note:** `cell2location` must be installed separately. See [cell2location installation](https://cell2location.readthedocs.io/en/latest/).

---

### Step 1 — Imports

```python
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:**
> ```python
> {
>     '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:**
> ```python
> {
>     '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](https://cell2location.readthedocs.io/en/latest/notebooks/cell2location_tutorial.html#Estimate-cell-type-specific-expression-of-every-gene-in-the-spatial-data-(needed-for-NCEM)). 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

```python
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](https://renoir.readthedocs.io/en/latest/).

## 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](https://doi.org/10.1038/s41467-026-72388-7)
