Skip to main content

Ancestral character reconstruction and visualisation for rooted phylogenetic trees.

Project description

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.

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.

How it works

For detailed description of the ACR methods, and visualization procedure used in PastML please visit our help page.

Try it online

Try PastML at pastml.pasteur.fr

Input data

As an input, one needs to provide a rooted phylogenetical tree in newick 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 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, singularity or in python3.

Run with docker

Basic usage

Once docker is installed, run the following command:

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:

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

docker run -t evolbioinfo/pastml -h

Run with singularity

Basic usage

Once singularity is installed, run the following command:

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:

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

singularity run docker://evolbioinfo/pastml -h

Run in python3

Windows

For Windows users, we recommend installing pastml via Cygwin environment. First instal python3 and pip3 from the Cygwin packages. Then install pastml:

pip3 install pastml

All other platforms

You can install pastml for python with or without conda, 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:

conda create --name pastmlenv python=3

Then activate it:

source activate pastmlenv

Then install pastml in it:

pip install pastml

Installing without conda

Make sure that pyhon3 and pip3 are installed, then install pastml:

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.

source activate pastmlenv

To run pastml:

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:

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:

pastml -h

Basic usage in python3

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 for ideas :)

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for pastml, version 1.9.20
Filename, size File type Python version Upload date Hashes
Filename, size pastml-1.9.20-py3-none-any.whl (71.9 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size pastml-1.9.20.tar.gz (50.0 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page