Unsupervised discovery of tissue architechture with graphs (UTAG)

⬅️ read the preprint here

⬅️ Preprocessed Multiplexed Image Data and UTAG results

This package implements segmentation of multiplexed imaging data into microanatomical domains. Multiplexed imaging data types are typically imaging mass cytometry (IMC), co-detection by indexing (CODEX), multiplexed ion beam imaging by time of flight (MIBI-TOF), cyclic immunofluorescence (CyCIF), and others. The package also provides functions for the downstream analysis of the detected micro-anatomical structure.

Getting Started

Install from github

pip install git+https://github.com/ElementoLab/utag.git@main

Installation should take less than 10 seconds.

Requirements

There are no specific hardware requirements.

Software requirements: - UTAG has been tested on Mac and Linux machines. - Python 3.7+ (tested on 3.8.2) - Python packages (automatically installed by pip): - numpy - pandas - anndata - scanpy - parc - squidpy - scipy - matplotlib - tqdm - networkx - parmap - scikit-learn - setuptools_scm (may require manual installation for MacOS through pip)

Specific versions of Python packages have been pinned to the setup.cfg file.

Basic Usage Principles

The UTAG process can be run with a single function call utag.utag. The input is a AnnData object which should have the position of cells (typically centroids) in the spatial slot of adata.obsm. The function will output domain classes for each cell stored in the obs slot of the returned AnnData object.

Running an example/demo dataset

Please refer to the notebook directory, and to the notebook on running UTAG on healthy lung data for a reproducible example. All data and respective results used for analysis can be downloaded from .

All data could alternatively be downloaded through command line:

pip install zenodo_get
zenodo_get -d 10.5281/zenodo.6376767 -o data

Running on your data

To run the method on multiple images/slides in batch mode:

from utag import utag

# Use Scanpy to get a h5ad file with provided data
import scanpy as sc
adata = sc.read(
    'data/healthy_lung_adata.h5ad',
    backup_url='https://zenodo.org/record/6376767/files/healthy_lung_adata.h5ad?download=1')

# Run UTAG on provided data
utag_results = utag(
    adata,
    slide_key="roi",
    max_dist=20,
    normalization_mode='l1_norm',
    apply_clustering=True,
    clustering_method = 'leiden', 
    resolutions = [0.05, 0.1, 0.3]
)

To run the method on a single image, pass None to the slide_key argument:

from utag import utag
utag_results = utag(
    adata,
    slide_key=None,
    max_dist=20,
    normalization_mode='l1_norm',
    apply_clustering=True,
    clustering_method = 'leiden', 
    resolutions = [0.05, 0.1, 0.3]
)

To visually inspect the results of the method:

import scanpy as sc
for roi in utag_results.obs['roi'].unique():
    result = utag_results[utag_results.obs['roi'] == roi].copy()
    sc.pl.spatial(result, color = 'UTAG Label_leiden_0.1', spot_size = 10)

Key Parameters

For more detailed usage of the package and downstream analysis, please refer to IMC Healthy Lung.ipynb in the documentation folder.