{"id":18621304,"url":"https://github.com/4ment/torchtree","last_synced_at":"2025-06-25T06:05:13.574Z","repository":{"id":40253159,"uuid":"233313153","full_name":"4ment/torchtree","owner":"4ment","description":"A probabilistic framework in PyTorch for phylogenetic models","archived":false,"fork":false,"pushed_at":"2024-11-28T05:00:52.000Z","size":44651,"stargazers_count":16,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-16T14:52:53.643Z","etag":null,"topics":["phylogenetics","pytorch","variational-inference"],"latest_commit_sha":null,"homepage":"https://4ment.github.io/torchtree","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/4ment.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-01-11T23:47:07.000Z","updated_at":"2025-04-09T10:15:16.000Z","dependencies_parsed_at":"2023-12-06T09:31:23.458Z","dependency_job_id":"834bfeb3-394c-4123-aa06-a8046ab8806f","html_url":"https://github.com/4ment/torchtree","commit_stats":{"total_commits":207,"total_committers":2,"mean_commits":103.5,"dds":0.004830917874396157,"last_synced_commit":"53dc62ba7ed053037eaab4ba5dd1f13a27df5cd8"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/4ment/torchtree","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4ment%2Ftorchtree","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4ment%2Ftorchtree/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4ment%2Ftorchtree/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4ment%2Ftorchtree/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/4ment","download_url":"https://codeload.github.com/4ment/torchtree/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4ment%2Ftorchtree/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261816312,"owners_count":23213863,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["phylogenetics","pytorch","variational-inference"],"created_at":"2024-11-07T04:10:24.630Z","updated_at":"2025-06-25T06:05:13.538Z","avatar_url":"https://github.com/4ment.png","language":"Jupyter Notebook","readme":"# torchtree\n\n[![Python package](https://github.com/4ment/torchtree/actions/workflows/python-package.yml/badge.svg)](https://github.com/4ment/torchtree/actions/workflows/python-package.yml)\n[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n[![docs](https://github.com/4ment/torchtree/actions/workflows/publish_documentation.yml/badge.svg)](https://github.com/4ment/torchtree/actions/workflows/publish_documentation.yml)\n![PyPI](https://img.shields.io/pypi/v/torchtree)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/torchtree)\n\n\ntorchtree is a program designed for developing and inferring phylogenetic models. Implemented in Python, it leverages [PyTorch] for automatic differentiation. The suite of inference algorithms encompasses variational inference, Hamiltonian Monte Carlo, maximum *a posteriori*, and Markov chain Monte Carlo.\n\nFor a comprehensive assessment of torchtree's performance and use cases, please see our evaluation repository, [torchtree-experiments](https://github.com/4ment/torchtree-experiments), where torchtree was rigorously tested on various datasets and benchmarked for accuracy and speed.\n\n\n- [Getting Started](#getting-started)\n  - [Dependencies](#dependencies)\n  - [Installation](#installation)\n- [Quick start](#quick-start)\n- [Documentation](#documentation)\n- [Plug-ins](#torchtree-plug-in)\n\n## Getting Started\n\n### Dependencies\n - [DendroPy]\n - [PyTorch]\n\n ### Installation\nUse an Anaconda environment (Optional)\n```bash\nconda env create -f environment.yml\nconda activate torchtree\n```\n\nTo install the latest stable version you can run\n```bash\npip install torchtree\n```\n\nTo build torchtree from source you can run\n```bash\ngit clone https://github.com/4ment/torchtree\npip install torchtree/\n```\n\nCheck install\n```bash\ntorchtree --help\n```\n\n## Documentation\nFor detailed information on how to use `torchtree` and its features, please refer to the official documentation and API reference.\n - [Documentation](https://4ment.github.io/torchtree)\n - [API Reference](https://4ment.github.io/torchtree/autoapi/torchtree/index.html)\n\n## Quick start\n`torchtree` requires a JSON file containing models and algorithms. A configuration file can be generated using `torchtree-cli`, a command line-based tool. This two-step process allows the user to adjust values in the configuration file, such as hyperparameters.\n\n`torchtree-cli` implements several subcommands, each corresponding to a different type of inference algorithm.\nA list of available subcommands can be obtained by running `torchtree-cli --help`.\n\nThe following subcommands are available:\n\n* `advi`: Automatic differentiation variational inference\n* `hmc`: Hamiltonian Monte Carlo\n* `map`: Maximum *a posteriori*\n* `mcmc`: Markov chain Monte Carlo\n\nEach subcommand/algorithm requires a different set of arguments which can be obtained by running `torchtree-cli \u003csubcommand\u003e --help`.\n\n`torchtree-cli` requires an alignment file in FASTA format and a tree file in either [Newick](https://en.wikipedia.org/wiki/Newick_format) or [NEXUS](https://en.wikipedia.org/wiki/Nexus_file) format.\nWhile *torchtree* uses the [DendroPy](https://jeetsukumaran.github.io/DendroPy) library to parse and manipulate phylogenetic trees, it is recommended to use a Newick file due to the numerous variations of the NEXUS format.\n\nLet's explore a few examples of how to use these programs using an influenza A virus dataset containing 69 DNA sequences.\nThe alignment and tree files are located in the [data](data) directory.\n\n### 1 - Generating a configuration file\nSome examples of models using variational inference:\n\n#### Unrooted tree with GTR+W4 model\n*W4* refers to a site model with 4 rates categories coming from a discretized Weibull distribution. This is similar to the more commonly used discretized Gamma distribution site model.\n\n```bash\ntorchtree-cli advi -i data/fluA.fa -t data/fluA.tree -m GTR -C 4 \u003e fluA.json\n```\n\n#### Time tree with strict clock and constant coalescent model\n```bash\ntorchtree-cli advi -i data/fluA.fa -t data/fluA.tree -m JC69 --clock strict --coalescent constant \u003e fluA.json\n```\n\n### 2 - Running torchtree\nThis will generate `sample.csv` and `sample.trees` files containing parameter and tree samples drawn from the variational distribution\n```bash\ntorchtree fluA.json\n```\n\n## torchtree plug-in\ntorchtree can be easily extended without modifying the code base thanks its modular implementation. Some examples of plug-ins:\n\n- [torchtree-bito]\n- [torchtree-physher]\n- [torchtree-scipy]\n- [torchtree-tensorflow]\n\nA GitHub [template](https://github.com/4ment/torchtree-plugin-template) is available to assist in the development of a plug-in, and it is highly recommended to use it. This template provides a structured starting point, ensuring consistency and compatibility with `torchtree` while streamlining the development process.\n\n## How to cite\n\nIf you use torchtree, please consider citing:\n\n```\n\n@misc{fourment2024torchtree,\n      title={torchtree: flexible phylogenetic model development and inference using {PyTorch}}, \n      author={Mathieu Fourment and Matthew Macaulay and Christiaan J Swanepoel and Xiang Ji and Marc A Suchard and Frederick A Matsen IV},\n      year={2024},\n      eprint={2406.18044},\n      archivePrefix={arXiv},\n      primaryClass={q-bio.PE},\n      url={https://arxiv.org/abs/2406.18044}\n}\n```\n\n## License\n\nDistributed under the GPLv3 License. See [LICENSE](LICENSE) for more information.\n\n## Acknowledgements\n\ntorchtree makes use of the following libraries and tools, which are under their own respective licenses:\n\n - [PyTorch]\n - [DendroPy]\n\n[DendroPy]: https://github.com/jeetsukumaran/DendroPy\n[PyTorch]: https://pytorch.org\n[torchtree-bito]: https://github.com/4ment/torchtree-bito\n[torchtree-physher]: https://github.com/4ment/torchtree-physher\n[torchtree-scipy]: https://github.com/4ment/torchtree-scipy\n[torchtree-tensorflow]: https://github.com/4ment/torchtree-tensorflow","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F4ment%2Ftorchtree","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F4ment%2Ftorchtree","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F4ment%2Ftorchtree/lists"}