Welcome to the 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 assign every cell from all samples an NT (niche trajectory) score to describe its position along the niche trajectory, which provides a uniform spatial trajectory across the whole dataset.

Quick start

Input File

This file contains all input information 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 from the 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