# ADViewpy
## Introduction
**ADViewpy** pip package is a Python port of ADView system, originally developed by Professor Zipeng Liu. ADViewpy aims to provide visual comparison of phylogenetic trees, usually between one reference tree and a collection of hundreds of trees.
- **ADView System by Professor Zipeng Liu:** [GitHub](https://github.com/zipengliu) | [ADView Website](http://phylo-adview.site/)
The alpha version of this tool has been uploaded to PyPI.
## Contributors
### [`Wengshan NG`](https://github.com/Coralnws)
## Features
- Visual comparison of phylogenetic trees
- Easy integration with existing Python workflows
## Installation
### Installation Steps
1. Install ADViewpy package from PyPI:
```
pip install adviewpy
```
2. Import the ADViewpy package and initialize it in your Python script:
```
import ADViewpy
# Initialize the ADViewpy tool
ADViewpy.init()
```
## Usage
#### `1.init(treefile)`
Initializes ADViewpy and creates the reference tree.
**Parameter:**
- `treefile` (str): Path to the reference tree file in Newick format.
**Return:**
- `ADViewpy` instance
#### `2.add_tree_collection(treefile,namefile)`
Add tree collection to ADViewpy
**Parameters:**
- `treefile` (str): Path to the tree collection file (each line contains a tree in newick format).
- `nanefile` (str): Path to the tree collection's name file, a name of tree each line corresponding to tree collection file.
#### `3.set_outgroup(outgroup_taxon[])`
Specify outgroup of phylogenetic tree, ADViewpy will re-root the trees according to outgroup provdied.
**Parameter:**
- `outgroup_taxon[]` (list): List of taxa names in outgroup
#### `4.reference_tree(exact_match_range[],support_value_range[])`
Visualization of reference tree, user can find branch with respect to attribute range.
**Parameters:**
- `exact_match_range[]` (list): A list to represent node exact match percentage range, for example [80, 100], which represents to find nodes with exact match percentage between 80% and 100%.
- `support_value_range` (list): A list to represent node support value range, for example [50, 80], which represents to find nodes with support value between 50 and 80.
#### `5.AD(view,scale,context_level,max_ad,ad_interval,tree_id,tree_name,sort,escape_taxa_as_context_block,show_block_proportional,subtree_independent,show_tree_name,filter,differentiate_inexact_match)`
Visualization of individual and cluster aggregated dendrograms, to show topological relationships between the selected focal subtree.
**Common parameters:**
- `view` (str): `AD Individual` to show individual aggregated dendrograms, `AD Cluster` to show cluster aggregated dendrograms.
- `scale` (foat): Set the scale of aggregated dendrograms, default scale is 0.1.
**Parameters in individual view:**
- `context_level` (int): Control how many context blocks to show.
- `max_ad` (int): Set the maximum number of aggregated dendrograms to display.
- `ad_interval`(list): List to represent tree id range, for example [1, 20], which represents to show aggregated dendrograms with tree id between 1 and 20.
- `tree_id` (list): Each integer in list represents a tree ID. Only trees matching these IDs will be displayed.
- `tree_name`(list): Each str in list represents a tree name. Only trees matching these names will be displayed.
- `sort`(str): Specify how to sort the displayed aggregated dendrograms, can choose from `id`, `name`, and `rf distance`.
- `escape_taxa_as_context_block`(Boolean): Determine whether escape taxa should be considered as a context block.
- `show_block_proportional` (Boolean): Determine whether to use color coverage to indicate the percentage of highlighted taxa within subtree
- `subtree_independent` (Boolean): Determine whether to merge overlapping subtrees into a single block.
- `show_tree_name` (Boolean): Determine whether to show tree id and tree name on top of each aggregated dendrogram.
- `filter` (str): Specify whether the conditions are inclusive or exclusive for the following parameters: ad_interval, tree_id,tree_name.
**Parameter in cluster view:**
- `differentiate_inexact_match` (Boolean): Choose whether to further distinguish exact and inexact matches in cluster
#### `6.pairwise_comparison(compare_tree)`
Pairwise compare two trees in detail. Allow to pairwise compare one tree in the collection with the reference tree or compare two trees in tree collection.
To compare a tree in the collection with the reference tree, user can choose a tree from AD()'s output view with mouse click.
**Parameter:**
`compare_tree` (int/str/list): Specify the trees for pairwise comparison. A tree can be specified using IDs or names. Providing an ID or name selects a single tree from the tree collection to compare with a reference tree. If a list is provided containing two trees, it indicates comparison between trees within the collection.
#### `7.tree_distribution()`
Showing distributions of trees in terms of their agreement and conflicts of leaf memberships for user-selected subtrees.
#### `8.tree_distance()`
Display the distances between each trees using a scatter plot.
**Return:**
- `Plotly` scatter showing distances between trees computed by the t-SNE dimensionality reduction technique.
#### `9.export_image(view,filename,*args)`
Exports generated view as an image
**Parameter:**
`view` (str): Selects which view to export. Choices include `Reference Tree`,`AD Individual`,`AD Cluster`,`Tree Distribution`,`Tree Distance`,`Pairwise Comparison`.
Raw data
{
"_id": null,
"home_page": null,
"name": "ADViewpy",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "python, phylogenetic tree, aggregrated dendrogram, tree comparison",
"author": "Ng Weng Shan",
"author_email": "ngwengshan025@hotmail.com",
"download_url": "https://files.pythonhosted.org/packages/06/6c/db1b5213737b76e10135a1dba4381f022fec2dfde7bb60b4696d3c293a92/ADViewpy-0.8a0.tar.gz",
"platform": null,
"description": "# ADViewpy\r\n\r\n## Introduction\r\n\r\n**ADViewpy** pip package is a Python port of ADView system, originally developed by Professor Zipeng Liu. ADViewpy aims to provide visual comparison of phylogenetic trees, usually between one reference tree and a collection of hundreds of trees.\r\n\r\n- **ADView System by Professor Zipeng Liu:** [GitHub](https://github.com/zipengliu) | [ADView Website](http://phylo-adview.site/)\r\n\r\nThe alpha version of this tool has been uploaded to PyPI.\r\n\r\n## Contributors\r\n\r\n### [`Wengshan NG`](https://github.com/Coralnws)\r\n\r\n## Features\r\n\r\n- Visual comparison of phylogenetic trees\r\n- Easy integration with existing Python workflows\r\n\r\n## Installation\r\n\r\n### Installation Steps\r\n\r\n1. Install ADViewpy package from PyPI:\r\n\r\n ```\r\n pip install adviewpy\r\n ```\r\n\r\n2. Import the ADViewpy package and initialize it in your Python script:\r\n\r\n ```\r\n import ADViewpy\r\n \r\n # Initialize the ADViewpy tool\r\n ADViewpy.init()\r\n ```\r\n\r\n## Usage\r\n\r\n#### `1.init(treefile)`\r\n\r\nInitializes ADViewpy and creates the reference tree.\r\n\r\n**Parameter:**\r\n\r\n- `treefile` (str): Path to the reference tree file in Newick format.\r\n\r\n**Return:**\r\n\r\n- `ADViewpy` instance\r\n\r\n\r\n\r\n#### `2.add_tree_collection(treefile,namefile)`\r\n\r\nAdd tree collection to ADViewpy\r\n\r\n**Parameters:**\r\n\r\n- `treefile` (str): Path to the tree collection file (each line contains a tree in newick format).\r\n- `nanefile` (str): Path to the tree collection's name file, a name of tree each line corresponding to tree collection file.\r\n\r\n\r\n\r\n#### `3.set_outgroup(outgroup_taxon[])`\r\n\r\nSpecify outgroup of phylogenetic tree, ADViewpy will re-root the trees according to outgroup provdied.\r\n\r\n**Parameter:**\r\n\r\n- `outgroup_taxon[]` (list): List of taxa names in outgroup\r\n\r\n \r\n\r\n#### `4.reference_tree(exact_match_range[],support_value_range[])`\r\n\r\nVisualization of reference tree, user can find branch with respect to attribute range. \r\n\r\n**Parameters:**\r\n\r\n- `exact_match_range[]` (list): A list to represent node exact match percentage range, for example [80, 100], which represents to find nodes with exact match percentage between 80% and 100%.\r\n\r\n- `support_value_range` (list): A list to represent node support value range, for example [50, 80], which represents to find nodes with support value between 50 and 80.\r\n\r\n \r\n\r\n#### `5.AD(view,scale,context_level,max_ad,ad_interval,tree_id,tree_name,sort,escape_taxa_as_context_block,show_block_proportional,subtree_independent,show_tree_name,filter,differentiate_inexact_match)`\r\n\r\nVisualization of individual and cluster aggregated dendrograms, to show topological relationships between the selected focal subtree.\r\n\r\n**Common parameters:**\r\n\r\n- `view` (str): `AD Individual` to show individual aggregated dendrograms, `AD Cluster` to show cluster aggregated dendrograms.\r\n- `scale` (foat): Set the scale of aggregated dendrograms, default scale is 0.1.\r\n\r\n**Parameters in individual view:**\r\n\r\n- `context_level` (int): Control how many context blocks to show.\r\n- `max_ad` (int): Set the maximum number of aggregated dendrograms to display.\r\n- `ad_interval`(list): List to represent tree id range, for example [1, 20], which represents to show aggregated dendrograms with tree id between 1 and 20.\r\n- `tree_id` (list): Each integer in list represents a tree ID. Only trees matching these IDs will be displayed.\r\n- `tree_name`(list): Each str in list represents a tree name. Only trees matching these names will be displayed.\r\n- `sort`(str): Specify how to sort the displayed aggregated dendrograms, can choose from `id`, `name`, and `rf distance`.\r\n- `escape_taxa_as_context_block`(Boolean): Determine whether escape taxa should be considered as a context block.\r\n- `show_block_proportional` (Boolean): Determine whether to use color coverage to indicate the percentage of highlighted taxa within subtree\r\n- `subtree_independent` (Boolean): Determine whether to merge overlapping subtrees into a single block.\r\n- `show_tree_name` (Boolean): Determine whether to show tree id and tree name on top of each aggregated dendrogram.\r\n- `filter` (str): Specify whether the conditions are inclusive or exclusive for the following parameters: ad_interval, tree_id,tree_name.\r\n\r\n**Parameter in cluster view:**\r\n\r\n- `differentiate_inexact_match` (Boolean): Choose whether to further distinguish exact and inexact matches in cluster\r\n\r\n \r\n\r\n#### `6.pairwise_comparison(compare_tree)`\r\n\r\nPairwise compare two trees in detail. Allow to pairwise compare one tree in the collection with the reference tree or compare two trees in tree collection.\r\n\r\nTo compare a tree in the collection with the reference tree, user can choose a tree from AD()'s output view with mouse click.\r\n\r\n**Parameter:**\r\n\r\n`compare_tree` (int/str/list): Specify the trees for pairwise comparison. A tree can be specified using IDs or names. Providing an ID or name selects a single tree from the tree collection to compare with a reference tree. If a list is provided containing two trees, it indicates comparison between trees within the collection.\r\n\r\n\r\n\r\n#### `7.tree_distribution()`\r\n\r\nShowing distributions of trees in terms of their agreement and conflicts of leaf memberships for user-selected subtrees.\r\n\r\n\r\n\r\n#### `8.tree_distance()`\r\n\r\nDisplay the distances between each trees using a scatter plot.\r\n\r\n**Return:**\r\n\r\n- `Plotly` scatter showing distances between trees computed by the t-SNE dimensionality reduction technique.\r\n\r\n\r\n\r\n#### `9.export_image(view,filename,*args)`\r\n\r\nExports generated view as an image\r\n\r\n**Parameter:**\r\n\r\n`view` (str): Selects which view to export. Choices include `Reference Tree`,`AD Individual`,`AD Cluster`,`Tree Distribution`,`Tree Distance`,`Pairwise Comparison`. \r\n\r\n",
"bugtrack_url": null,
"license": null,
"summary": "ADViewpy is Python Library to visually compare phylogenetic trees",
"version": "0.8a0",
"project_urls": {
"Homepage": "https://github.com/Coralnws/ADViewpy-alpha.git"
},
"split_keywords": [
"python",
" phylogenetic tree",
" aggregrated dendrogram",
" tree comparison"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "066cdb1b5213737b76e10135a1dba4381f022fec2dfde7bb60b4696d3c293a92",
"md5": "00633e4880abf4ba7138741946aebb99",
"sha256": "a02dbfeb8a9f0365712becdbc53b9ed452c78db20824f51458ed6c2732ba08fe"
},
"downloads": -1,
"filename": "ADViewpy-0.8a0.tar.gz",
"has_sig": false,
"md5_digest": "00633e4880abf4ba7138741946aebb99",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 46684,
"upload_time": "2024-06-21T03:54:15",
"upload_time_iso_8601": "2024-06-21T03:54:15.381192Z",
"url": "https://files.pythonhosted.org/packages/06/6c/db1b5213737b76e10135a1dba4381f022fec2dfde7bb60b4696d3c293a92/ADViewpy-0.8a0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-21 03:54:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Coralnws",
"github_project": "ADViewpy-alpha",
"github_not_found": true,
"lcname": "adviewpy"
}