Metadata-Version: 2.4
Name: cytocommunity2
Version: 0.1.2
Summary: Weakly supervised cellular-neighborhood learning for spatial omics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: matplotlib>=3.6
Requires-Dist: numpy<2,>=1.23
Requires-Dist: pandas<3,>=1.5
Requires-Dist: sci-palettes
Requires-Dist: scikit-learn>=1.1
Requires-Dist: scipy>=1.9
Requires-Dist: seaborn>=0.12
Requires-Dist: torch-geometric>=2.0
Provides-Extra: downstream
Requires-Dist: esda<2.6,>=2.5; extra == "downstream"
Requires-Dist: jupyter; extra == "downstream"
Requires-Dist: libpysal<4.10,>=4.9; extra == "downstream"
Dynamic: license-file

# CytoCommunity2

## Contents

- [Overview](#overview)
- [Installation](#installation)
- [Usage](#usage)
- [Maintainers](#maintainers)
- [Citation](#citation)

## Overview

To enhance CytoCommunity (https://github.com/huBioinfo/CytoCommunity), we
present CytoCommunity2, **a unified weakly-supervised framework** for
identifying and comparing tissue cellular neighborhoods (TCNs or CNs) across
**large-scale spatial omics samples with single or multiple biological
conditions**.

Inspired by histopathology workflows, CytoCommunity2 first hierarchically
partitions the large single-cell spatial map into small patches, performs graph
construction and weakly supervised TCN learning for each patch, and finally
merges results through KNN-based TCN reassignment at segmentation boundaries to
ensure TCN spatial continuity. This strategy divides the original sample into
patches for TCN learning, achieving **memory efficiency (typical 24G graphics
memory is enough)** and also increased sample throughput. These optimizations
significantly **enhance the robustness of TCNs and cross-sample alignment
performance**.

Furthermore, to make CytoCommunity2 a unified framework that is also
**applicable for single-condition spatial omics datasets**, pseudo-samples with
artificial labels are generated, enabling automatic TCN alignment across real
samples via **contrastive learning**.

**_In summary, the advantages of CytoCommunity2 include:_**

**_(1) Using significantly less memory for large-scale spatial omics samples
with millions of cells._**

**_(2) A unified weakly-supervised model applicable for both multi-condition
and single-condition datasets._**

**_(3) High TCN alignment performance makes it well-suited for comparative
analysis in large cohort studies._**

## Installation

### Hardware requirement

Graphics memory: 24G

Storage: 10GB or more

### Install CytoCommunity2

CytoCommunity2 requires Python 3.10 or newer. We recommend creating and
activating a Conda environment first:

```bash
conda create -n cytocommunity2 python=3.10
conda activate cytocommunity2
```

Install PyTorch for your compute platform before installing CytoCommunity2.
For an NVIDIA GPU on Windows or Linux, first install the appropriate
CUDA-enabled PyTorch build from the
[official PyTorch installation page](https://pytorch.org/get-started/locally/).

Install the package:

```bash
pip install cytocommunity2
```

To run the downstream analyses, install the
optional downstream dependencies with:

```bash
pip install "cytocommunity2[downstream]"
```

This extra includes `esda`, `libpysal`, and Jupyter; they are not installed
by the basic command above.

## Usage

### 1. Prepare input data

The input data to CytoCommunity2 includes four types of files :

(1) An image (sample) name list file, named as "ImageNameList.txt".

(2) A cell type label file for each image (sample), named as "[image
name]_CellTypeLabel.txt". Note that [image_name] should be consistent with your
customized image names listed in the "ImageNameList.txt". This file lists cell
type names of all cells in an image (sample).

(3) A cell spatial coordinate file for each image (sample), named as "[image
name]_Coordinates.txt". Note that [image_name] should be consistent with your
customized image names listed in the "ImageNameList.txt". This file lists cell
coordinates (tab-delimited x/y) of all cells in an image (sample). The cell
orders should be exactly the same with "[image name]_CellTypeLabel.txt".

(4) A graph label file for each image (sample), named as "[image
name]_GraphLabel.txt". For multi-condition datasets, this file must be provided
for every image (sample) and contain one integer indicating its biological
condition. For single-condition datasets, graph label
files can be omitted for all images (samples), and CytoCommunity2 will generate
pseudo-samples for weakly-supervised learning.

### 2. Configure CytoCommunity2

Before running CytoCommunity2, set `input_dir` and review all
model and downstream parameters in
[`hyperparameters.json`](https://github.com/LiukangWu/CytoCommunity2/blob/main/hyperparameters.json). The Python workflow will use this configuration file.

### 3. Run CytoCommunity2

The tutorial uses a TNBC dataset as a worked example and demonstrates the
entire CytoCommunity2 workflow, from model training and CN identification to
downstream analysis:

```bash
jupyter notebook tutorial/TNBC_workflow.ipynb
```

### 4. Output files

The main output directories are:

- `CNLearning_Output/`: CN-number screening, trained models and CN labels.
- `CNVisualization_Output/`: spatial plots and result tables.
- `data/`: downstream analysis results and intermediate data tables.
- `plot/`: figures generated by downstream analyses.

## Maintainers

- Liukang Wu (yetong@stu.xidian.edu.cn)
- Yafei Xu (22031212416@stu.xidian.edu.cn)
- Yuxuan Hu (huyuxuan@xidian.edu.cn)

## Citation

Yuxuan Hu, Jiazhen Rong, Yafei Xu, Runzhi Xie, Jacqueline Peng, Lin Gao, and
Kai Tan. “Unsupervised and supervised discovery of tissue cellular
neighborhoods from cell phenotypes.” *Nature Methods* 21 (2024): 267–278.
https://doi.org/10.1038/s41592-023-02124-2
