# PastML
__PastML__ provides fast methods for Ancestral Character Reconstruction (ACR) and visualisation
on rooted phylogenetic trees. Given a rooted tree and its node annotations, it can either visualise them as-is,
or infer ancestral node states based on the tip states, with a selection of maximum likelihood and parsimonious methods.
The result is then visualised as a zoomable html map.
[](https://doi.org/10.1093/molbev/msz131)
[](https://github.com/evolbioinfo/pastml/releases)
[](https://anaconda.org/bioconda/pastml)
[](https://pypi.org/project/pastml/)
[](https://pypi.org/project/pastml/)
[](https://hub.docker.com/r/evolbioinfo/pastml/tags)
[](tests)
#### Article
Ishikawa SA, Zhukova A, Iwasaki W, Gascuel O (2019) __A Fast Likelihood Method to Reconstruct and Visualize Ancestral Scenarios__. [_Molecular Biology and Evolution_, msz131](https://doi.org/10.1093/molbev/msz131).
## How it works
For detailed description of the ACR methods, and visualization procedure used in __PastML__ please visit our [help page](https://pastml.pasteur.fr/help).
## Try it online
Try __PastML__ at [pastml.pasteur.fr](https://pastml.pasteur.fr)
# Input data
As an input, one needs to provide a **rooted** phylogenetical tree in [newick](https://en.wikipedia.org/wiki/Newick_format) format,
and a table containing tip states,
in tab-delimited (by default) or csv format (to be specified with *--data_sep ,* option).
### Example
You can download [HIV1-A in Albania data](examples/Albania/data) as an example.
Let's assume that the tree and annotation files are in the Downloads folder,
and are named respectively Albanian.tree.152tax.tre and data.txt.
The data.txt is a comma-separated file, containing tip ids in the first column,
and Country in the second column, i.e.:
id | Country
----- | -----
98CMAJ6932 | Africa
98CMAJ6933 | Africa
96CMAJ6134 | Africa
00SEAY5240 | WestEurope
... | ...
02GRAY0303 | Greece
97YUAF9960 | EastEurope
# Installation
There are 3 alternative ways to run __pastml__ on your computer: with [docker](https://www.docker.com/community-edition), [singularity](https://www.sylabs.io/singularity/) or in python3.
## Run with docker
### Basic usage
Once [docker](https://www.docker.com/community-edition) is installed, run the following command:
```bash
docker run -v <path_to_the_folder_containing_the_tree_and_the_annotations>:/data:rw -t evolbioinfo/pastml --tree /data/<tree_file.nwk> --data /data/<annotation_file.csv> --data_sep <separator_eg_,> --columns <column1 column2 ...> --html_compressed /data/<output_map.html>
```
For example, to reconstruct and visualise the ancestral Country states for Albanian data,
one needs to run the following command:
```bash
docker run -v ~/Downloads:/data:rw -t evolbioinfo/pastml --tree /data/Albanian.tree.152tax.tre --data /data/data.txt --columns Country --html_compressed /data/Albanian_map.html --data_sep ,
```
This will produce a file Albanian_map.html in the Downloads folder,
that can be viewed with a browser.
#### Help
To see advanced options, run
```bash
docker run -t evolbioinfo/pastml -h
```
## Run with singularity
### Basic usage
Once [singularity](https://www.sylabs.io/guides/2.6/user-guide/quick_start.html#quick-installation-steps) is installed, run the following command:
```bash
singularity run docker://evolbioinfo/pastml --tree <path/to/tree_file.nwk> --data <path/to/annotation_file.csv> --columns <column1 column2 ...> --html_compressed <path/to/output/map.html> --data_sep <separator_eg_,>
```
For example, to reconstruct and visualise the ancestral Country states for Albanian data,
one needs to run the following command:
```bash
singularity run docker://evolbioinfo/pastml --tree ~/Downloads/Albanian.tree.152tax.tre --data ~/Downloads/data.txt --columns Country --html_compressed ~/Downloads/Albanian_map.html --data_sep ,
```
This will produce a file Albanian_map.html in the Downloads folder,
that can be viewed with a browser.
#### Help
To see advanced options, run
```bash
singularity run docker://evolbioinfo/pastml -h
```
## Run in python3
### Windows
For **Windows** users, we recommend installing __pastml__ via [Cygwin environment](https://www.cygwin.com/).
First instal python3 and pip3 from the Cygwin packages. Then install __pastml__:
```bash
pip3 install pastml
```
### All other platforms
You can install __pastml__ for python with or without [conda](https://conda.io/docs/), following the procedures described below:
#### Installing with conda
Once you have conda installed create an environment for __pastml__ with python3, here we name it pastmlenv:
```bash
conda create --name pastmlenv python=3
```
Then activate it:
```bash
source activate pastmlenv
```
Then install __pastml__ in it:
```bash
pip install pastml
```
#### Installing without conda
Make sure that pyhon3 and pip3 are installed, then install __pastml__:
```bash
pip3 install pastml
```
### Basic usage in a command line
If you installed __pastml__ via conda, do not forget to first activate the dedicated environment (here named pastmlenv), e.g.
```bash
source activate pastmlenv
```
To run __pastml__:
```bash
pastml --tree <path/to/tree_file.nwk> --data <path/to/annotation_file.csv> --columns <column1 column2 ...> --html_compressed <path/to/output/map.html> --data_sep <separator_eg_,>
```
For example, to reconstruct and visualise the ancestral Country states for Albanian data,
one needs to run the following command:
```bash
pastml --tree ~/Downloads/Albanian.tree.152tax.tre --data ~/Downloads/data.txt --columns Country --html_compressed ~/Downloads/Albanian_map.html --data_sep ,
```
This will produce a file Albanian_map.html in the Downloads folder,
that can be viewed with a browser.
#### Help
To see advanced options, run:
```bash
pastml -h
```
### Basic usage in python3
```python
from pastml.acr import pastml_pipeline
# Path to the table containing tip/node annotations, in csv or tab format
data = "~/Downloads/data.txt"
# Path to the tree in newick format
tree = "~/Downloads/Albanian.tree.152tax.tre"
# Columns present in the annotation table,
# for which we want to reconstruct ancestral states
# (for Albanian data we only have one column, but multiple columns are also allowed)
columns = ['Country']
# Path to the output compressed map visualisation
html_compressed = "~/Downloads/Albanian_map.html"
# (Optional) path to the output tree visualisation
html = "~/Downloads/Albanian_tree.html"
pastml_pipeline(data=data, data_sep=',', columns=columns, name_column='Country', tree=tree,
html_compressed=html_compressed, html=html, verbose=True)
```
### Examples
See the [examples folder](https://github.com/evolbioinfo/pastml/tree/master/examples) for ideas :)
Raw data
{
"_id": null,
"home_page": "https://github.com/evolbioinfo/pastml",
"name": "pastml",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "PASTML,visualisation,phylogeny,ancestral character reconstruction",
"author": "Anna Zhukova",
"author_email": "anna.zhukova@pasteur.fr",
"download_url": "",
"platform": null,
"description": "# PastML\n\n__PastML__ provides fast methods for Ancestral Character Reconstruction (ACR) and visualisation\non rooted phylogenetic trees. Given a rooted tree and its node annotations, it can either visualise them as-is, \nor infer ancestral node states based on the tip states, with a selection of maximum likelihood and parsimonious methods. \nThe result is then visualised as a zoomable html map.\n\n\n[](https://doi.org/10.1093/molbev/msz131)\n[](https://github.com/evolbioinfo/pastml/releases)\n[](https://anaconda.org/bioconda/pastml)\n[](https://pypi.org/project/pastml/)\n[](https://pypi.org/project/pastml/)\n[](https://hub.docker.com/r/evolbioinfo/pastml/tags)\n[](tests)\n\n\n\n#### Article\n\nIshikawa SA, Zhukova A, Iwasaki W, Gascuel O (2019) __A Fast Likelihood Method to Reconstruct and Visualize Ancestral Scenarios__. [_Molecular Biology and Evolution_, msz131](https://doi.org/10.1093/molbev/msz131).\n\n## How it works\n\nFor detailed description of the ACR methods, and visualization procedure used in __PastML__ please visit our [help page](https://pastml.pasteur.fr/help).\n\n## Try it online\nTry __PastML__ at [pastml.pasteur.fr](https://pastml.pasteur.fr)\n\n# Input data\nAs an input, one needs to provide a **rooted** phylogenetical tree in [newick](https://en.wikipedia.org/wiki/Newick_format) format,\nand a table containing tip states, \nin tab-delimited (by default) or csv format (to be specified with *--data_sep ,* option).\n\n### Example\nYou can download [HIV1-A in Albania data](examples/Albania/data) as an example.\nLet's assume that the tree and annotation files are in the Downloads folder, \nand are named respectively Albanian.tree.152tax.tre\tand data.txt.\n\nThe data.txt is a comma-separated file, containing tip ids in the first column, \nand Country in the second column, i.e.:\n\nid | Country\n----- | -----\n98CMAJ6932 | Africa\n98CMAJ6933 | Africa\n96CMAJ6134 | Africa\n00SEAY5240 | WestEurope\n... | ...\n02GRAY0303 | Greece\n97YUAF9960 | EastEurope\n\n# Installation\n\nThere are 3 alternative ways to run __pastml__ on your computer: with [docker](https://www.docker.com/community-edition), [singularity](https://www.sylabs.io/singularity/) or in python3.\n\n## Run with docker\n\n### Basic usage\nOnce [docker](https://www.docker.com/community-edition) is installed, run the following command:\n\n```bash\ndocker run -v <path_to_the_folder_containing_the_tree_and_the_annotations>:/data:rw -t evolbioinfo/pastml --tree /data/<tree_file.nwk> --data /data/<annotation_file.csv> --data_sep <separator_eg_,> --columns <column1 column2 ...> --html_compressed /data/<output_map.html>\n```\n\nFor example, to reconstruct and visualise the ancestral Country states for Albanian data, \none needs to run the following command:\n\n```bash\ndocker run -v ~/Downloads:/data:rw -t evolbioinfo/pastml --tree /data/Albanian.tree.152tax.tre --data /data/data.txt --columns Country --html_compressed /data/Albanian_map.html --data_sep , \n```\n\nThis will produce a file Albanian_map.html in the Downloads folder, \nthat can be viewed with a browser.\n\n\n#### Help\n\nTo see advanced options, run\n```bash\ndocker run -t evolbioinfo/pastml -h\n```\n\n## Run with singularity\n\n### Basic usage\nOnce [singularity](https://www.sylabs.io/guides/2.6/user-guide/quick_start.html#quick-installation-steps) is installed, run the following command:\n\n```bash\nsingularity run docker://evolbioinfo/pastml --tree <path/to/tree_file.nwk> --data <path/to/annotation_file.csv> --columns <column1 column2 ...> --html_compressed <path/to/output/map.html> --data_sep <separator_eg_,>\n```\n\nFor example, to reconstruct and visualise the ancestral Country states for Albanian data, \none needs to run the following command:\n\n```bash\nsingularity run docker://evolbioinfo/pastml --tree ~/Downloads/Albanian.tree.152tax.tre --data ~/Downloads/data.txt --columns Country --html_compressed ~/Downloads/Albanian_map.html --data_sep , \n```\n\nThis will produce a file Albanian_map.html in the Downloads folder, \nthat can be viewed with a browser.\n\n\n#### Help\n\nTo see advanced options, run\n```bash\nsingularity run docker://evolbioinfo/pastml -h\n```\n\n## Run in python3\n\n### Windows\nFor **Windows** users, we recommend installing __pastml__ via [Cygwin environment](https://www.cygwin.com/).\nFirst instal python3 and pip3 from the Cygwin packages. Then install __pastml__:\n```bash\npip3 install pastml\n```\n\n### All other platforms\n\nYou can install __pastml__ for python with or without [conda](https://conda.io/docs/), following the procedures described below:\n\n#### Installing with conda\n\nOnce you have conda installed create an environment for __pastml__ with python3, here we name it pastmlenv:\n\n```bash\nconda create --name pastmlenv python=3\n```\n\nThen activate it:\n```bash\nsource activate pastmlenv\n```\n\nThen install __pastml__ in it:\n\n```bash\npip install pastml\n```\n\n#### Installing without conda\n\nMake sure that pyhon3 and pip3 are installed, then install __pastml__:\n\n```bash\npip3 install pastml\n```\n\n### Basic usage in a command line\nIf you installed __pastml__ via conda, do not forget to first activate the dedicated environment (here named pastmlenv), e.g.\n\n```bash\nsource activate pastmlenv\n```\n\nTo run __pastml__:\n\n```bash\npastml --tree <path/to/tree_file.nwk> --data <path/to/annotation_file.csv> --columns <column1 column2 ...> --html_compressed <path/to/output/map.html> --data_sep <separator_eg_,>\n```\n\nFor example, to reconstruct and visualise the ancestral Country states for Albanian data, \none needs to run the following command:\n\n```bash\npastml --tree ~/Downloads/Albanian.tree.152tax.tre --data ~/Downloads/data.txt --columns Country --html_compressed ~/Downloads/Albanian_map.html --data_sep , \n```\n\nThis will produce a file Albanian_map.html in the Downloads folder, \nthat can be viewed with a browser.\n\n#### Help\n\nTo see advanced options, run:\n```bash\npastml -h\n```\n\n### Basic usage in python3\n```python\nfrom pastml.acr import pastml_pipeline\n\n# Path to the table containing tip/node annotations, in csv or tab format\ndata = \"~/Downloads/data.txt\"\n\n# Path to the tree in newick format\ntree = \"~/Downloads/Albanian.tree.152tax.tre\"\n\n# Columns present in the annotation table,\n# for which we want to reconstruct ancestral states\n# (for Albanian data we only have one column, but multiple columns are also allowed)\ncolumns = ['Country']\n\n# Path to the output compressed map visualisation\nhtml_compressed = \"~/Downloads/Albanian_map.html\"\n\n# (Optional) path to the output tree visualisation\nhtml = \"~/Downloads/Albanian_tree.html\"\n\npastml_pipeline(data=data, data_sep=',', columns=columns, name_column='Country', tree=tree,\n html_compressed=html_compressed, html=html, verbose=True)\n```\n\n### Examples\n\nSee the [examples folder](https://github.com/evolbioinfo/pastml/tree/master/examples) for ideas :)\n",
"bugtrack_url": null,
"license": "",
"summary": "Ancestral character reconstruction and visualisation for rooted phylogenetic trees.",
"version": "1.9.42",
"project_urls": {
"Homepage": "https://github.com/evolbioinfo/pastml"
},
"split_keywords": [
"pastml",
"visualisation",
"phylogeny",
"ancestral character reconstruction"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f4a592608584ba671b82172cbc65c585a46f1b26e925e4d6f1f2fdf22cf8410d",
"md5": "4e0f042872b53061d1e49b8725aeb7d0",
"sha256": "88d2b4d4300f2e8f9ac78edd90937405057744c54401dd0e8ed269fd183111f4"
},
"downloads": -1,
"filename": "pastml-1.9.42-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4e0f042872b53061d1e49b8725aeb7d0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 463922,
"upload_time": "2023-07-10T15:18:07",
"upload_time_iso_8601": "2023-07-10T15:18:07.120675Z",
"url": "https://files.pythonhosted.org/packages/f4/a5/92608584ba671b82172cbc65c585a46f1b26e925e4d6f1f2fdf22cf8410d/pastml-1.9.42-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-10 15:18:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "evolbioinfo",
"github_project": "pastml",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pastml"
}
JSON
