# 🌲 PhyloDM
[](https://pypi.org/project/phylodm/)
[](https://anaconda.org/bioconda/phylodm)
[](https://crates.io/crates/phylodm)
[](https://zenodo.org/badge/latestdoi/251473194)
PhyloDM is a high-performance library that converts a phylogenetic tree into a pairwise distance matrix.
For a tree with 30,000 taxa, PhyloDM will use:
* ~14GB of memory (94% less than DendroPy)
* ~1 minute of CPU time (183x faster than DendroPy).
PhyloDM is written in Rust and is exposed to Python via the Python PyO3 API. This means it
can be used in either Python or Rust, however, the documentation below is written for use in Python. For Rust documentation, see [Crates.io](https://docs.rs/phylodm/latest/phylodm/).
## ⚙ Installation
*Requires Python 3.7+*
### PyPI
Pre-compiled binaries are packaged for most 64-bit Unix platforms. If you are installing on a different platform then you
will need to have [Rust](https://www.rust-lang.org/tools/install) installed to compile the binaries.
```shell
python -m pip install phylodm
```
### Conda
```shell
conda install -c b bioconda phylodm
```
## 🐍 Quick-start
A pairwise distance matrix can be created from either a Newick file, or DendroPy tree.
```python
from phylodm import PhyloDM
# PREPARATION: Create a test tree
with open('/tmp/newick.tree', 'w') as fh:
fh.write('(A:4,(B:3,C:4):1);')
# 1a. From a Newick file
pdm = PhyloDM.load_from_newick_path('/tmp/newick.tree')
# 1b. From a DendroPy tree
import dendropy
tree = dendropy.Tree.get_from_path('/tmp/newick.tree', schema='newick')
pdm = PhyloDM.load_from_dendropy(tree)
# 2. Calculate the PDM
dm = pdm.dm(norm=False)
labels = pdm.taxa()
"""
/------------[4]------------ A
+
| /---------[3]--------- B
\---[1]---+
\------------[4]------------- C
labels = ('A', 'B', 'C')
dm = [[0. 8. 9.]
[8. 0. 7.]
[9. 7. 0.]]
"""
```
### Accessing data
The `dm` method generates a symmetrical NumPy matrix and returns a tuple of
keys in the matrix row/column order.
```python
# Calculate the PDM
dm = pdm.dm(norm=False)
labels = pdm.taxa()
"""
/------------[4]------------ A
+
| /---------[3]--------- B
\---[1]---+
\------------[4]------------- C
labels = ('A', 'B', 'C')
dm = [[0. 8. 9.]
[8. 0. 7.]
[9. 7. 0.]]
"""
# e.g. The following commands (equivalent) get the distance between A and B
dm[0, 1] # 8
dm[labels.index('A'), labels.index('B')] # 8
```
### Normalisation
If the `norm` argument of `dm` is set to `True`, then the data will be normalised
by the sum of all edges in the tree.
## ⏱ Performance
Tests were executed using `scripts/performance/Snakefile` on an Intel(R) Xeon(R) CPU E5-2650 v3 @ 2.30GHz.
For large numbers of taxa it is beneficial to use PhyloDM, however, if you have a small number
of taxa in the tree it is beneficial to use DendroPy for the great features it provides.
Raw data
{
"_id": null,
"home_page": "https://github.com/aaronmussig/PhyloDM",
"name": "phylodm",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "phylogenetic distance matrix symmetric",
"author": "Aaron Mussig",
"author_email": "aaronmussig@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/8b/cb/fb6182545ebab3e5cce6dc3f8982411a9fdd221823e4ebef197efae0da06/phylodm-3.0.0.tar.gz",
"platform": null,
"description": "# \ud83c\udf32 PhyloDM\n\n[](https://pypi.org/project/phylodm/)\n[](https://anaconda.org/bioconda/phylodm)\n[](https://crates.io/crates/phylodm)\n[](https://zenodo.org/badge/latestdoi/251473194)\n\nPhyloDM is a high-performance library that converts a phylogenetic tree into a pairwise distance matrix. \n\nFor a tree with 30,000 taxa, PhyloDM will use:\n\n* ~14GB of memory (94% less than DendroPy)\n* ~1 minute of CPU time (183x faster than DendroPy).\n\nPhyloDM is written in Rust and is exposed to Python via the Python PyO3 API. This means it \ncan be used in either Python or Rust, however, the documentation below is written for use in Python. For Rust documentation, see [Crates.io](https://docs.rs/phylodm/latest/phylodm/).\n\n## \u2699 Installation\n\n*Requires Python 3.7+*\n\n### PyPI\n\nPre-compiled binaries are packaged for most 64-bit Unix platforms. If you are installing on a different platform then you\nwill need to have [Rust](https://www.rust-lang.org/tools/install) installed to compile the binaries. \n\n```shell\npython -m pip install phylodm\n```\n\n### Conda\n\n```shell\nconda install -c b bioconda phylodm\n```\n\n\n## \ud83d\udc0d Quick-start\n\nA pairwise distance matrix can be created from either a Newick file, or DendroPy tree.\n\n```python\nfrom phylodm import PhyloDM\n\n# PREPARATION: Create a test tree\nwith open('/tmp/newick.tree', 'w') as fh:\n fh.write('(A:4,(B:3,C:4):1);')\n\n# 1a. From a Newick file\npdm = PhyloDM.load_from_newick_path('/tmp/newick.tree')\n\n# 1b. From a DendroPy tree\nimport dendropy\ntree = dendropy.Tree.get_from_path('/tmp/newick.tree', schema='newick')\npdm = PhyloDM.load_from_dendropy(tree)\n\n# 2. Calculate the PDM\ndm = pdm.dm(norm=False)\nlabels = pdm.taxa()\n\n\"\"\"\n/------------[4]------------ A\n+\n| /---------[3]--------- B\n\\---[1]---+\n \\------------[4]------------- C\n \nlabels = ('A', 'B', 'C')\n dm = [[0. 8. 9.]\n [8. 0. 7.]\n [9. 7. 0.]]\n\"\"\"\n```\n\n### Accessing data\nThe `dm` method generates a symmetrical NumPy matrix and returns a tuple of\nkeys in the matrix row/column order.\n\n```python\n# Calculate the PDM\ndm = pdm.dm(norm=False)\nlabels = pdm.taxa()\n\n\"\"\"\n/------------[4]------------ A\n+\n| /---------[3]--------- B\n\\---[1]---+\n \\------------[4]------------- C\n \nlabels = ('A', 'B', 'C')\n dm = [[0. 8. 9.]\n [8. 0. 7.]\n [9. 7. 0.]]\n\"\"\"\n\n# e.g. The following commands (equivalent) get the distance between A and B\ndm[0, 1] # 8\ndm[labels.index('A'), labels.index('B')] # 8\n```\n\n### Normalisation\n\nIf the `norm` argument of `dm` is set to `True`, then the data will be normalised \nby the sum of all edges in the tree.\n\n\n## \u23f1 Performance\nTests were executed using `scripts/performance/Snakefile` on an Intel(R) Xeon(R) CPU E5-2650 v3 @ 2.30GHz.\n\nFor large numbers of taxa it is beneficial to use PhyloDM, however, if you have a small number \nof taxa in the tree it is beneficial to use DendroPy for the great features it provides.\n\n\n\n\n",
"bugtrack_url": null,
"license": "GPL3",
"summary": "Efficient calculation of phylogenetic distance matrices.",
"version": "3.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/aaronmussig/PhyloDM/issues",
"Documentation": "https://github.com/aaronmussig/PhyloDM",
"Homepage": "https://github.com/aaronmussig/PhyloDM",
"Source Code": "https://github.com/aaronmussig/PhyloDM"
},
"split_keywords": [
"phylogenetic",
"distance",
"matrix",
"symmetric"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "cab3c1e88a6a31e86907916ad648324ce1851ef757b7938230fc182d8c79e4a6",
"md5": "c86ecdf587803a556bac8fd6df4a8d7e",
"sha256": "e0897684bd9e9498468c977b91b29abb45d49e6290495c45b8884fba264ee42b"
},
"downloads": -1,
"filename": "phylodm-3.0.0-cp310-cp310-macosx_10_9_x86_64.whl",
"has_sig": false,
"md5_digest": "c86ecdf587803a556bac8fd6df4a8d7e",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.7",
"size": 270048,
"upload_time": "2023-06-17T04:03:01",
"upload_time_iso_8601": "2023-06-17T04:03:01.250889Z",
"url": "https://files.pythonhosted.org/packages/ca/b3/c1e88a6a31e86907916ad648324ce1851ef757b7938230fc182d8c79e4a6/phylodm-3.0.0-cp310-cp310-macosx_10_9_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ef181c0444197e452216ab1ffa4bd743a171a6ded80dce401b1ac13fba969745",
"md5": "4bc528daa8bc377c12fa0e70882bdb34",
"sha256": "ac2cb1ece58a1316841cdf494661b5932d256d6541c5bcb5a3e8af692b0c4095"
},
"downloads": -1,
"filename": "phylodm-3.0.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "4bc528daa8bc377c12fa0e70882bdb34",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.7",
"size": 284237,
"upload_time": "2023-06-17T04:03:02",
"upload_time_iso_8601": "2023-06-17T04:03:02.958448Z",
"url": "https://files.pythonhosted.org/packages/ef/18/1c0444197e452216ab1ffa4bd743a171a6ded80dce401b1ac13fba969745/phylodm-3.0.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "58474cf18f2ea8000057e6164d1bb43927f14ea9ffb14727e58216a91b114849",
"md5": "003d1a899ac92fdd4fce8068ddbd9cf0",
"sha256": "459d5621a82fc1907780759129c9cfbefaf3760f52a693ac91631098cdfe26d3"
},
"downloads": -1,
"filename": "phylodm-3.0.0-cp311-cp311-macosx_10_9_x86_64.whl",
"has_sig": false,
"md5_digest": "003d1a899ac92fdd4fce8068ddbd9cf0",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.7",
"size": 270052,
"upload_time": "2023-06-17T04:03:04",
"upload_time_iso_8601": "2023-06-17T04:03:04.498867Z",
"url": "https://files.pythonhosted.org/packages/58/47/4cf18f2ea8000057e6164d1bb43927f14ea9ffb14727e58216a91b114849/phylodm-3.0.0-cp311-cp311-macosx_10_9_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "85a261c219570231f5ddb142beabb3bdcde60a6ecb0f25234be0feb2a82368ba",
"md5": "c242d953e464a1586f98f56fbc37133c",
"sha256": "92285602189873034f43ece0cfc3dc3a2c50b95c7dd232dd185b34f27ec866b3"
},
"downloads": -1,
"filename": "phylodm-3.0.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "c242d953e464a1586f98f56fbc37133c",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.7",
"size": 284234,
"upload_time": "2023-06-17T04:03:06",
"upload_time_iso_8601": "2023-06-17T04:03:06.077941Z",
"url": "https://files.pythonhosted.org/packages/85/a2/61c219570231f5ddb142beabb3bdcde60a6ecb0f25234be0feb2a82368ba/phylodm-3.0.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3f9443ff9dd74a42b0e23e6b86b719be81a306432ef6ac41d4f8c109e914bbe4",
"md5": "0e350b50b5ed85006399a3c190b22afc",
"sha256": "4e49a95ffc101e0ef59930eba8a24a0aa29e33893d3999357d9afe80d272d642"
},
"downloads": -1,
"filename": "phylodm-3.0.0-cp37-cp37m-macosx_10_9_x86_64.whl",
"has_sig": false,
"md5_digest": "0e350b50b5ed85006399a3c190b22afc",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": ">=3.7",
"size": 270646,
"upload_time": "2023-06-17T04:03:07",
"upload_time_iso_8601": "2023-06-17T04:03:07.518781Z",
"url": "https://files.pythonhosted.org/packages/3f/94/43ff9dd74a42b0e23e6b86b719be81a306432ef6ac41d4f8c109e914bbe4/phylodm-3.0.0-cp37-cp37m-macosx_10_9_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7620abd2a8beef0e543b230cc1059a6c7a7b992a8c8dd0659c7d018f15c0ce70",
"md5": "8c4aa903d1f6196edf988f0ca3700eb5",
"sha256": "85957fd176c2025cd661bd49c43652d5e19e3aef002878a113b5648723554117"
},
"downloads": -1,
"filename": "phylodm-3.0.0-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "8c4aa903d1f6196edf988f0ca3700eb5",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": ">=3.7",
"size": 284786,
"upload_time": "2023-06-17T04:03:09",
"upload_time_iso_8601": "2023-06-17T04:03:09.075997Z",
"url": "https://files.pythonhosted.org/packages/76/20/abd2a8beef0e543b230cc1059a6c7a7b992a8c8dd0659c7d018f15c0ce70/phylodm-3.0.0-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8a2697cf8b37f670b865bcd9e00821c286ae4dfa4dcf19366ffff88e7a5acc8b",
"md5": "ad2fe19d3297cbdb5cd0ed27a67fdf57",
"sha256": "5d22097c980fa58844a9db576fe0ec26ae7ac915739fcdfd74d9a19983d5b436"
},
"downloads": -1,
"filename": "phylodm-3.0.0-cp38-cp38-macosx_10_9_x86_64.whl",
"has_sig": false,
"md5_digest": "ad2fe19d3297cbdb5cd0ed27a67fdf57",
"packagetype": "bdist_wheel",
"python_version": "cp38",
"requires_python": ">=3.7",
"size": 270557,
"upload_time": "2023-06-17T04:03:10",
"upload_time_iso_8601": "2023-06-17T04:03:10.643964Z",
"url": "https://files.pythonhosted.org/packages/8a/26/97cf8b37f670b865bcd9e00821c286ae4dfa4dcf19366ffff88e7a5acc8b/phylodm-3.0.0-cp38-cp38-macosx_10_9_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ea2552db0cabcf594eb7cfcb60d50a1947f0b9e082b7bde8639422eeb52441c3",
"md5": "b530ecd09c40ae915d8c61fc2d6200bf",
"sha256": "6c7f6e27228d336e737e47f9eeb94207b2439cf2e13caa7c0eb5c8f3478d1501"
},
"downloads": -1,
"filename": "phylodm-3.0.0-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "b530ecd09c40ae915d8c61fc2d6200bf",
"packagetype": "bdist_wheel",
"python_version": "cp38",
"requires_python": ">=3.7",
"size": 284712,
"upload_time": "2023-06-17T04:03:12",
"upload_time_iso_8601": "2023-06-17T04:03:12.270060Z",
"url": "https://files.pythonhosted.org/packages/ea/25/52db0cabcf594eb7cfcb60d50a1947f0b9e082b7bde8639422eeb52441c3/phylodm-3.0.0-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "44794c67fec87485b3392c084696eac6d8cf154c0eb8753ce68faf7c5be07493",
"md5": "ffba24636b6984a8da86d88e27f89af9",
"sha256": "63fc865e485fc766347e0f6b51d0fa31cf83afa1340563e5cccf7cd139e6b4fa"
},
"downloads": -1,
"filename": "phylodm-3.0.0-cp39-cp39-macosx_10_9_x86_64.whl",
"has_sig": false,
"md5_digest": "ffba24636b6984a8da86d88e27f89af9",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.7",
"size": 270306,
"upload_time": "2023-06-17T04:03:14",
"upload_time_iso_8601": "2023-06-17T04:03:14.104265Z",
"url": "https://files.pythonhosted.org/packages/44/79/4c67fec87485b3392c084696eac6d8cf154c0eb8753ce68faf7c5be07493/phylodm-3.0.0-cp39-cp39-macosx_10_9_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f4af45acde516bce616f1e7efaf4036e275963b4f14391c746f9dd118286ed98",
"md5": "deedb2b5bc24c6ac5a850a77afeecf61",
"sha256": "c60265817101d0f2bfdecafdc4176ed7e710da8c076f8dfa6be84ebbade2709e"
},
"downloads": -1,
"filename": "phylodm-3.0.0-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "deedb2b5bc24c6ac5a850a77afeecf61",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.7",
"size": 284504,
"upload_time": "2023-06-17T04:03:15",
"upload_time_iso_8601": "2023-06-17T04:03:15.778987Z",
"url": "https://files.pythonhosted.org/packages/f4/af/45acde516bce616f1e7efaf4036e275963b4f14391c746f9dd118286ed98/phylodm-3.0.0-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8bcbfb6182545ebab3e5cce6dc3f8982411a9fdd221823e4ebef197efae0da06",
"md5": "16a8861e30ce0e173e074888a48b40bc",
"sha256": "c7e051ba1350a947bd72382181aafd1a75bc3a0faa7019dbe8cd1febf5df6069"
},
"downloads": -1,
"filename": "phylodm-3.0.0.tar.gz",
"has_sig": false,
"md5_digest": "16a8861e30ce0e173e074888a48b40bc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 32523,
"upload_time": "2023-06-17T04:03:17",
"upload_time_iso_8601": "2023-06-17T04:03:17.390931Z",
"url": "https://files.pythonhosted.org/packages/8b/cb/fb6182545ebab3e5cce6dc3f8982411a9fdd221823e4ebef197efae0da06/phylodm-3.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-17 04:03:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aaronmussig",
"github_project": "PhyloDM",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "phylodm"
}
JSON
