# **ONTraC**
[](https://pypi.org/project/ONTraC/)
[](https://pypi.org/project/ONTraC/)
[](https://pepy.tech/project/ONTraC)
[](https://github.com/gyuanlab/ONTraC)
[](https://github.com/gyuanlab/ONTraC/issues)
[](https://github.com/gyuanlab/ONTraC/blob/master/LICENSE)
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
```sh
pip install ONTraC
```
For details and alternative approches, please see the [installation tutorial](https://ontrac-website.readthedocs.io/en/latest/installation.html)
## Tutorial
Please see [ONTraC website](https://ontrac-website.readthedocs.io/en/latest/) for details.
### Run ONTraC with original cell type
#### Input File
An [example metadata input file](./examples/code_for_paper_reproduce/stereo_input.csv) 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](https://ontrac-website.readthedocs.io/en/latest/tutorials/IO_files.html).
#### 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](https://ontrac-website.readthedocs.io/en/latest/tutorials/parameters.html).
```{sh}
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](https://doi.org/10.5281/zenodo.11186619).
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](./examples/V2/data/merfish_meta.csv) is provided.
- Embeddings file
An [example embeddings input file](./examples/V2/data/merfish_embedding.csv) is provided.
For detailed information about input and output file, please see the [IO files explanation](https://ontrac-website.readthedocs.io/en/latest/tutorials/IO_files.html).
#### Run ONTraC
```{sh}
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](https://zenodo.org/records/15571644/files/Stereo_seq_data.zip).
The intermediate and final results are located in `NN-dir`, `GNN-dir`, and `NT-dir` directories. Please see [IO files explanation](https://ontrac-website.readthedocs.io/en/latest/tutorials/IO_files.html#output-files) for detailed infromation.
### Visualization
Please see the [Visualization Tutorial](https://ontrac-website.readthedocs.io/en/latest/tutorials/visualization.html).
### Interoperability
ONTraC has been incorporated with [Giotto Suite](https://drieslab.github.io/Giotto_website/articles/ontrac.html).
## Citation
**Wang, W.\*, Zheng, S.\*, Shin, C. S., Chávez-Fuentes J. C. & [Yuan, G.-C.](https://labs.icahn.mssm.edu/yuanlab/)$**. [ONTraC characterizes spatially continuous variations of tissue microenvironment through niche trajectory analysis](https://doi.org/10.1186/s13059-025-03588-5). ***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.](https://labs.icahn.mssm.edu/yuanlab/)$**. [A Robust Kernel-Based Workflow for Niche Trajectory Analysis](https://onlinelibrary.wiley.com/doi/10.1002/smtd.202401199). ***Small Methods***, 2025 ([inner cover story](https://onlinelibrary.wiley.com/doi/10.1002/smtd.202570031)).
## Other Resources
- [Reproducible codes for our ***Genome Biology*** paper](https://github.com/gyuanlab/ONTraC_paper)
- [Dataset/output used in our ***Genome Biology*** paper](https://doi.org/10.5281/zenodo.11186619)
- [Reproducible codes for our ***Small Methods*** paper](https://github.com/gyuanlab/ONTraC_v2_paper)
Raw data
{
"_id": null,
"home_page": null,
"name": "ONTraC",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.10",
"maintainer_email": null,
"keywords": "graph neural network, pytorch, pytorch geometric, trajectory inference, spatial omics",
"author": null,
"author_email": "Wen Wang <wwang.bio@gmail.com>, Shiwei Zheng <swzheng29@gmail.com>, Sujung Crystal Shin <sjcshin5040@gmail.com>, \"Joselyn C. Ch\u00e1vez-Fuentes\" <joselynchavezf@gmail.com>, Guo-Cheng Yuan <gcyuan@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/e9/f7/e65e2045e37f22eb793ac5db072be4bb72f05d07898dffc6ec2f5b2df131/ontrac-2.0.7.post1.tar.gz",
"platform": null,
"description": "# **ONTraC**\n\n[](https://pypi.org/project/ONTraC/)\n[](https://pypi.org/project/ONTraC/)\n[](https://pepy.tech/project/ONTraC)\n[](https://github.com/gyuanlab/ONTraC)\n[](https://github.com/gyuanlab/ONTraC/issues)\n[](https://github.com/gyuanlab/ONTraC/blob/master/LICENSE)\n\nONTraC (Ordered Niche Trajectory Construction) is a niche-centered, machine learning\nmethod for constructing spatially continuous trajectories. ONTraC differs from existing tools in\nthat it treats a niche, rather than an individual cell, as the basic unit for spatial trajectory\nanalysis. In this context, we define niche as a multicellular, spatially localized region where\ndifferent cell types may coexist and interact with each other. ONTraC seamlessly integrates\ncell-type composition and spatial information by using the graph neural network modeling\nframework. Its output, which is called the niche trajectory, can be viewed as a one dimensional\nrepresentation of the tissue microenvironment continuum. By disentangling cell-level and niche-\nlevel properties, niche trajectory analysis provides a coherent framework to study coordinated\nresponses from all the cells in association with continuous tissue microenvironment variations.\n\n\n\n\n## Installation\n\n```sh\npip install ONTraC\n```\n\nFor details and alternative approches, please see the [installation tutorial](https://ontrac-website.readthedocs.io/en/latest/installation.html)\n\n## Tutorial\n\nPlease see [ONTraC website](https://ontrac-website.readthedocs.io/en/latest/) for details.\n\n### Run ONTraC with original cell type\n\n#### Input File\n\nAn [example metadata input file](./examples/code_for_paper_reproduce/stereo_input.csv) is provided.\nThis file contains formation with five columns: Cell_ID, Sample, Cell_Type, x, and y.\n\n| Cell_ID | Sample | Cell_Type | x | y |\n| --------------- | -------- | --------- | ------- | ----- |\n| E12_E1S3_100034 | E12_E1S3 | Fibro | 15940 | 18584 |\n| E12_E1S3_100035 | E12_E1S3 | Fibro | 15942 | 18623 |\n| ... | ... | ... | ... | ... |\n| E16_E2S7_326412 | E16_E2S7 | Fibro | 32990.5 | 14475 |\n\nFor detailed information about input and output file, please see the [IO files explanation](https://ontrac-website.readthedocs.io/en/latest/tutorials/IO_files.html).\n\n#### Run ONTraC\n\nThe required options for running ONTraC are the paths to the input file and the three output directories:\n\n- **NN-dir:** This directory stores preprocessed data and other intermediary datasets for analysis.\n- **GNN-dir:** This directory stores output from he GNN algorithm.\n- **NT-dir:** This directory stores NT output.\n\nFor detailed description about all parameters, please see the [Parameters explanation](https://ontrac-website.readthedocs.io/en/latest/tutorials/parameters.html).\n\n```{sh}\nONTraC --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\n```\n\nThe input dataset and output files could be downloaded from the [Zenodo Dataset Repository](https://doi.org/10.5281/zenodo.11186619).\n\nWe recommand running `ONTraC` on GPU, it may take much more time on your own laptop with CPU only.\n\n### Run ONTraC with kernel-based cell type adjustment\n\n#### Input Files\n\n- Metadata file\n\nAn [example metadata input file](./examples/V2/data/merfish_meta.csv) is provided.\n\n- Embeddings file\n\nAn [example embeddings input file](./examples/V2/data/merfish_embedding.csv) is provided.\n\nFor detailed information about input and output file, please see the [IO files explanation](https://ontrac-website.readthedocs.io/en/latest/tutorials/IO_files.html).\n\n#### Run ONTraC\n\n```{sh}\nONTraC --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\n```\n\n### Output\n\nThe example ouputs could be found in the [Zenodo Dataset Repository](https://zenodo.org/records/15571644/files/Stereo_seq_data.zip).\nThe intermediate and final results are located in `NN-dir`, `GNN-dir`, and `NT-dir` directories. Please see [IO files explanation](https://ontrac-website.readthedocs.io/en/latest/tutorials/IO_files.html#output-files) for detailed infromation.\n\n### Visualization\n\nPlease see the [Visualization Tutorial](https://ontrac-website.readthedocs.io/en/latest/tutorials/visualization.html).\n\n### Interoperability\n\nONTraC has been incorporated with [Giotto Suite](https://drieslab.github.io/Giotto_website/articles/ontrac.html).\n\n## Citation\n\n**Wang, W.\\*, Zheng, S.\\*, Shin, C. S., Ch\u00e1vez-Fuentes J. C. & [Yuan, G.-C.](https://labs.icahn.mssm.edu/yuanlab/)$**. [ONTraC characterizes spatially continuous variations of tissue microenvironment through niche trajectory analysis](https://doi.org/10.1186/s13059-025-03588-5). ***Genome Biol***, 2025.\n\nIf you are using kernel-based cell type adjustment or working on low-resolution data, please also cite:\n**Wang, W., Shin, C. S., Ch\u00e1vez-Fuentes J. C. & [Yuan, G.-C.](https://labs.icahn.mssm.edu/yuanlab/)$**. [A Robust Kernel-Based Workflow for Niche Trajectory Analysis](https://onlinelibrary.wiley.com/doi/10.1002/smtd.202401199). ***Small Methods***, 2025 ([inner cover story](https://onlinelibrary.wiley.com/doi/10.1002/smtd.202570031)).\n\n## Other Resources\n\n- [Reproducible codes for our ***Genome Biology*** paper](https://github.com/gyuanlab/ONTraC_paper)\n- [Dataset/output used in our ***Genome Biology*** paper](https://doi.org/10.5281/zenodo.11186619)\n- [Reproducible codes for our ***Small Methods*** paper](https://github.com/gyuanlab/ONTraC_v2_paper)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A niche-centered, machine learning method for constructing spatially continuous trajectories",
"version": "2.0.7.post1",
"project_urls": {
"Homepage": "https://github.com/gyuanlab/ONTraC",
"Issue Tracker": "https://github.com/gyuanlab/ONTraC/issues",
"Repository": "https://github.com/gyuanlab/ONTraC"
},
"split_keywords": [
"graph neural network",
" pytorch",
" pytorch geometric",
" trajectory inference",
" spatial omics"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "94b64527352ef7fc3642382a9a0ec4fc2a504771eaf84f253929ee0d0443ed77",
"md5": "58f64b9182b3248407ad57f6280e00e7",
"sha256": "ff4e2721d831f2c4db92b0f57b6167c8f04fa7d4cb375c09f6350774de10527e"
},
"downloads": -1,
"filename": "ontrac-2.0.7.post1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "58f64b9182b3248407ad57f6280e00e7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.10",
"size": 88463,
"upload_time": "2025-10-06T21:18:09",
"upload_time_iso_8601": "2025-10-06T21:18:09.931336Z",
"url": "https://files.pythonhosted.org/packages/94/b6/4527352ef7fc3642382a9a0ec4fc2a504771eaf84f253929ee0d0443ed77/ontrac-2.0.7.post1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e9f7e65e2045e37f22eb793ac5db072be4bb72f05d07898dffc6ec2f5b2df131",
"md5": "ed960b54e2afab6ed3ed4de627b18d5d",
"sha256": "37ecf49aacb378cd582eb44732c7ee6163684e1bee922a1268ee2f0f66bdfdb6"
},
"downloads": -1,
"filename": "ontrac-2.0.7.post1.tar.gz",
"has_sig": false,
"md5_digest": "ed960b54e2afab6ed3ed4de627b18d5d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.10",
"size": 75363,
"upload_time": "2025-10-06T21:18:12",
"upload_time_iso_8601": "2025-10-06T21:18:12.072707Z",
"url": "https://files.pythonhosted.org/packages/e9/f7/e65e2045e37f22eb793ac5db072be4bb72f05d07898dffc6ec2f5b2df131/ontrac-2.0.7.post1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-06 21:18:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "gyuanlab",
"github_project": "ONTraC",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ontrac"
}
JSON
