Welcome to ONTraC (Ordered Niche Trajectory Construction) website

Overview

ONTraC (Ordered Niche Trajectory Construction) is a niche-centered machine learning method for constructing spatially continuous trajectories.

ONTraC differs from existing tools in that it treats a niche, rather than an individual cell, as the basic unit for spatial trajectory analysis. A niche is defined as a multicellular, spatially localized region where different cell types may coexist and interact with each other.

ONTraC integrates niche features (cell-type composition) and spatial information using a graph neural network framework. Its output, the niche trajectory, represents a one-dimensional continuum of the tissue microenvironment. By disentangling cell-level and niche-level properties, niche trajectory analysis offers a coherent framework for studying coordinated cellular responses to continuous tissue microenvironment variations.

ONTraC can give every cell from all samples a NT (niche trajectory) score to describe its position along the niche trajectory, which provide a uniform spatial trajectory across the whole dataset.

Quick start

Input File

This file contains all input formation with five columns: Cell_ID, Sample, Cell_Type, x, and y.

Cell_ID	Sample	Cell_Type	x	y
E12_E1S3_100034	E12_E1S3	Fibro	15940	18584
E12_E1S3_100035	E12_E1S3	Fibro	15942	18623
…	…	…	…	…
E16_E2S7_326412	E16_E2S7	Fibro	32990.5	14475

For detailed information about input and output files, please see the IO Files Explanation.

Installation

pip install "ONTraC[all]"

• See the Installation and Setup for more details.

Run ONTraC

ONTraC \
    --meta-input simulated_dataset.csv \
    --NN-dir simulation_NN \
    --GNN-dir simulation_GNN \
    --NT-dir simulation_NT \  
    --hidden-feats 4 \
    -k 6 \
    --modularity-loss-weight 0.3 \
    --purity-loss-weight 300 \
    --regularization-loss-weight 0.1 \
    --beta 0.03 2>&1 | tee simulation.log

• See the Command Line Interface Tutorial for using ONTraC via command line.

• For Jupyter-based usage, refer to the Interactive Tutorial.

Visualization

ONTraC_analysis \
    -o analysis_output/simulation \
    -l simulation.log \
    --NN-dir simulation_NN \
    -GNN-dir simulation_GNN \
    --NT-dir simulation_NT \
    -r

• See the Visualization Tutorial for more details.

Note

This project is actively maintained and under active development.

Citation

Wang, W.*, Zheng, S.*, Shin, C. S., Chávez-Fuentes J. C. & Yuan, G. C.$. ONTraC characterizes spatially continuous variations of tissue microenvironment through niche trajectory analysis. Genome Biol, 2025.

Other Resources

Reproducible code for our paper

Datasets and outputs used in our paper