theosanderson / chronumental Goto Github PK

View Code? Open in Web Editor NEW

24.0 3.0 4.0 2.53 MB

Estimating time trees from very large phylogenies

License: MIT License

Python 96.31% Shell 0.22% Dockerfile 3.48%

phylogenetics timetree jax numpyro

chronumental's Introduction

Chronumental

Chronologies from monumental phylogenetic trees

Chronumental is a tool for creating a "time-tree" (where distance on the tree represents time) from a phylogenetic divergence-tree (where distance on the tree reflects a number of genetic substitutions).

What sets Chronumental apart from most other tools is that it scales to extremely large trees, which can contain millions of nodes. Chronumental uses JAX to represent the task of computing a time tree in a differentiable graph for efficient calculation on a CPU or GPU.

📝 Read the preprint

📚 View the documentation

Installation

Method 1: Using pipx (recommended for basic use - installs in its own isolated environment)

pip install --local pipx
pipx install  chronumental

Method 2: In your python environment

pip install chronumental

Method 3: Bioconda

Chronumental is now available on bioconda

conda config --add channels bioconda
conda install chronumental

Usage

This demo uses trees and metadata collated by the UShER team.

wget https://hgwdev.gi.ucsc.edu/~angie/UShER_SARS-CoV-2/2021/10/06/public-2021-10-06.all.nwk.gz
wget https://hgwdev.gi.ucsc.edu/~angie/UShER_SARS-CoV-2/2021/10/06/public-2021-10-06.metadata.tsv.gz
chronumental --tree public-2021-10-06.all.nwk.gz --dates public-2021-10-06.metadata.tsv.gz --steps 100

📚 Please visit our documentation page to learn more about the parameters you can use to control Chronumental.

Integrations

Taxonium can automatically call Chronumental, and generate a combined visualisation that allows switching between distance and time phylogenies

Similar tools

TreeTime is a more advanced tool for inferring time trees. If you have a dataset of e.g. <10,000 rather than millions of nodes you are definitely best off trying it. The TreeTime readme also links to other similar tools.

Troubleshooting

Chronumental uses the earliest date in your dataset as an anchor to calibrate everything else. If this earliest date is wrong due to a metadata error things won't work well. You can set the reference node manually with --reference_node to avoid this issue.

chronumental's People

Contributors

Stargazers

Watchers

Forkers

ttl074 yceh ayixon jtmccrone

chronumental's Issues

License?

May I request the addition of a LICENSE to this repository so users know the terms under which it can be used and distributed? (MIT, BSD, GPLv3, etc.)

parameter to pass alternative to "strain" as key col

Surface better error when taxa don't match "strain"

Check behaviour with initial nodes named, unnamed

NaN clock rate

For some small data sets with relatively narrow sampling ranges (in time) we are seeing that the clock rate fails to be estimated by RTT and no time trees are output.
Specifying an initial clock rate resolves the issue. I suggest making an informative error message in this case and requesting the user to specif an initial rate.

Performing SVI:
Traceback (most recent call last):
File "/Library/Frameworks/Python.framework/Versions/3.7/bin/chronumental", line 8, in
sys.exit(main.main())
File "/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages/chronumental/main.py", line 289, in main
state = svi.init(jax.random.PRNGKey(0))
File "/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages/numpyro/infer/svi.py", line 182, in init
*args, **kwargs, **self.static_kwargs
File "/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages/numpyro/handlers.py", line 171, in get_trace
self(*args, **kwargs)
File "/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages/numpyro/primitives.py", line 105, in call
return self.fn(*args, **kwargs)
File "/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages/numpyro/primitives.py", line 105, in call
return self.fn(*args, **kwargs)
File "/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages/numpyro/primitives.py", line 105, in call
return self.fn(*args, **kwargs)
File "/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages/chronumental/models.py", line 76, in model
dist.Normal( loc=0.0, scale=1000.0))
File "/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages/numpyro/primitives.py", line 219, in sample
msg = apply_stack(initial_msg)
File "/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages/numpyro/primitives.py", line 47, in apply_stack
handler.process_message(msg)
File "/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages/numpyro/handlers.py", line 223, in process_message
raise RuntimeError(f"Site {name} must be sampled in trace.")
RuntimeError: Site root_date must be sampled in trace.

I also got the same error using the test_data in the repo.