CytoCommunity2

Contents

• Overview
• Installation
• Usage
• Maintainers
• 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 CN learning for each patch, and finally merges results through KNN-based CN reassignment at segmentation boundaries to ensure CN spatial continuity. This strategy divides the original sample into patches for CN learning, achieving memory efficiency (typical 24G graphics memory is enough) and also increased sample throughput. These optimizations significantly enhance the robustness of CNs 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 CN 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 CN 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:

conda create -n cytocommunity2 python=3.10
conda activate cytocommunity2

For an NVIDIA GPU on Windows or Linux, first install the appropriate CUDA-enabled PyTorch build from the official PyTorch installation page.

Install the package via pip:

pip install cytocommunity2

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. The Python workflow will use this configuration file.

3. Run CytoCommunity2

With hyperparameters.json in the working directory, run the core workflow:

from pathlib import Path
import cytocommunity2 as cc2

CONFIG_FILE = Path("hyperparameters.json").resolve()

config = cc2.CytoCommunityConfig.from_json(CONFIG_FILE)
dataset = cc2.build_spatial_graphs(config)
learning_result = cc2.run_learning(dataset, config)
cc2.visualize_results(learning_result, config)

4.Tutorial

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:

jupyter notebook tutorial/TNBC_workflow.ipynb

5. Output files

The main output directories are:

• CNLearning_Output/: CN-number screening, trained models, and final result tables.
• CNVisualization_Output/: CN and cell-type spatial plots.
• data/: downstream analysis results.
• 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