ONTraC
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. In this context, we define niche as a multicellular, spatially localized region where different cell types may coexist and interact with each other. ONTraC seamlessly integrates cell-type composition and spatial information by using the graph neural network modeling framework. Its output, which is called the niche trajectory, can be viewed as a one dimensional representation of the tissue microenvironment continuum. By disentangling cell-level and niche- level properties, niche trajectory analysis provides a coherent framework to study coordinated responses from all the cells in association with continuous tissue microenvironment variations.
Installation
pip install ONTraC
For details and alternative approches, please see the installation tutorial
Tutorial
Please see ONTraC website for details.
Run ONTraC with original cell type
Input File
An example metadata input file is provided. This file contains 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 file, please see the IO files explanation.
Run ONTraC
The required options for running ONTraC are the paths to the input file and the three output directories:
- NN-dir: This directory stores preprocessed data and other intermediary datasets for analysis.
- GNN-dir: This directory stores output from he GNN algorithm.
- NT-dir: This directory stores NT output.
For detailed description about all parameters, please see the Parameters explanation.
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
The input dataset and output files could be downloaded from the Zenodo Dataset Repository.
We recommand running ONTraC on GPU, it may take much more time on your own laptop with CPU only.
Run ONTraC with kernel-based cell type adjustment
Input Files
- Metadata file
An example metadata input file is provided.
- Embeddings file
An example embeddings input file is provided.
For detailed information about input and output file, please see the IO files explanation.
Run ONTraC
ONTraC --meta-input ./examples/V2/data/merfish_meta.csv --embedding-input ./examples/V2/data/merfish_embedding.csv --NN-dir ./examples/V2_example_embedding_NN --GNN-dir ./examples/V2_example_embedding_GNN --NTScore-dir ./examples/V2_example_embedding_NT --embedding-adjust -s 42 --equal-space 2>&1 | tee log/V2_example_embedding_input.log
Output
The example ouputs could be found in the Zenodo Dataset Repository.
The intermediate and final results are located in NN-dir, GNN-dir, and NT-dir directories. Please see IO files explanation for detailed infromation.
Visualization
Please see the Visualization Tutorial.
Interoperability
ONTraC has been incorporated with Giotto Suite.
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.
If you are using kernel-based cell type adjustment or working on low-resolution data, please also cite: Wang, W., Shin, C. S., Chávez-Fuentes J. C. & Yuan, G.-C.$. A Robust Kernel-Based Workflow for Niche Trajectory Analysis. Small Methods, 2025 (inner cover story).
Other Resources
4 maintainers
Release files for ONTraC 2.1.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| ontrac-2.1.2.tar.gz | 93.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| ontrac-2.1.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 201.0 kB
Release files / ontrac-2.1.2.tar.gz
| Download URL | ontrac-2.1.2.tar.gz |
|---|---|
| Size | 93.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c2383abd61ba98908bef5e9ebc690e846237da3f28c73f3a4dfc8e9d6f622a64
|
|
BLAKE2b-256 checksum How to use checksums |
4695c1293188cad1965fefe0048593f4516eb232156ab3aa9764fb66f8a81042
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.11.12
|
Release files / ontrac-2.1.2-py3-none-any.whl
| Download URL | ontrac-2.1.2-py3-none-any.whl |
|---|---|
| Size | 107.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f48ffbd1da2e76b2252752a52753a1e3b356e1ae5b5f0ff17caa3eab080e6256
|
|
BLAKE2b-256 checksum How to use checksums |
72f2f8540f0b1864da61c1c523e2025962a28e081ccef09a9711e5f249797754
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.11.12
|
