Skip to main content

A library for checking the limits of phylogenetic tree estimation.

Project description

phylim: a phylogenetic limit evaluation library built on cogent3

Coverage Status

phylim evaluates the identifiability when estimating the phylogenetic tree using the Markov model. The identifiability is the key condition of the Markov model used in phylogenetics to fulfil consistency.

Establishing identifiability relies on the arrangement of specific types of transition probability matrices (e.g., DLC and sympathetic) while avoiding other types. A key concern arises when a tree does not meet the condition that, for each node, a path to a tip must exist where all matrices along the path are DLC. Such trees are not identifiable 🪚🎄! For instance, in the figure below, tree T' contains a node surrounded by a specific type of non-DLC matrix, rendering it non-identifiable. In contrast, compare T' with tree T.

phylim provides a quick, handy method to check the identifiability of a model fit, where we developed a main cogent3 app, phylim. phylim is compatible with piqtree2, a python library that exposes features from iqtree2.

The following content will demonstrate how to set up phylim and give some tutorials on the main identifiability check app and other associated apps.

tree1

Installation

pip install phylim

Let's see if it has been done successfully. In the package directory:

pytest

Hope all tests passed! :blush:

Run the check of identifiability

If you fit a model to an alignment and get the model result:

>>> from cogent3 import get_app, make_aligned_seqs

>>> algn = make_aligned_seqs(
...    {
...        "Human": "ATGCGGCTCGCGGAGGCCGCGCTCGCGGAG",
...        "Gorilla": "ATGCGGCGCGCGGAGGCCGCGCTCGCGGAG",
...        "Mouse": "ATGCCCGGCGCCAAGGCAGCGCTGGCGGAG",
...    },
...    info={"moltype": "dna", "source": "foo"},
... )

>>> app_fit = get_app("model", "GTR")
>>> result = app_fit(algn)

You can easily check the identifiability by:

>>> app_ident_check = get_app("phylim")

>>> record = app_ident_check(result)
>>> record.is_identifiable

True

The phylim app wraps all information about phylogenetic limits.

>>> record
Source Model Name Identifiable Has Boundary Values Version
brca1.fasta GTR True True 2024.9.20

You can also use features like classifying all matrices or checking boundary values in a model fit.

Label all transition probability matrices in a model fit

You can call classify_model_psubs to give the category of all the matrices:

>>> from phylim import classify_model_psubs

>>> labelled = classify_model_psubs(result)
>>> labelled
Substitution Matrices Categories
edge namematrix category
GorillaDLC
HumanDLC
MouseDLC
Check if all parameter fits are within the boundary
>>> from phylim import check_fit_boundary

>>> violations = check_fit_boundary(result)
>>> violations
BoundsViolation(source='foo', vio=[{'par_name': 'C/T', 'init': np.float64(1.0000000147345554e-06), 'lower': 1e-06, 'upper': 50}, {'par_name': 'A/T', 'init': np.float64(1.0000000625906854e-06), 'lower': 1e-06, 'upper': 50}])

Check identifiability for piqtree2

phylim provides an app, phylim_to_lf, which allows you to build the likelihood function from a piqtree2 output tree.

>>> from piqtree2 import build_tree

>>> tree = build_tree(algn, model="GTR")
>>> app_inverter = get_app("phylim_to_lf")

>>> result = app_inverter(tree)
>>> record = app_ident_check(result)
>>> record.is_identifiable

True

Colour the edges for a phylogenetic tree based on matrix categories

If you obtain a model fit, phylim can visualise the tree with labelled matrices.

phylim provides an app, phylim_style_tree, which takes an edge-matrix category map and colours the edges:

>>> from phylim import classify_model_psubs

>>> edge_to_cat = classify_model_psubs(result)
>>> tree = result.tree

>>> app_colour_edge = get_app("phylim_style_tree", edge_to_cat)
>>> app_colour_edge(tree)
tree1

You can also colour edges using a user-defined edge-matrix category map, applicable to any tree object!

>>> from cogent3 import make_tree
>>> from phylim.classify_matrix import SYMPATHETIC, DLC

>>> tree = make_tree("(A, B, C);")
>>> edge_to_cat = {"A":SYMPATHETIC, "B":SYMPATHETIC, "C":DLC}

>>> app_colour_edge = get_app("phylim_style_tree", edge_to_cat)
>>> app_colour_edge(tree)
tree1

Project details


Download files

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

Source Distribution

phylim-2024.12.3.post1.tar.gz (11.3 kB view details)

Uploaded Source

Built Distribution

phylim-2024.12.3.post1-py3-none-any.whl (11.6 kB view details)

Uploaded Python 3

File details

Details for the file phylim-2024.12.3.post1.tar.gz.

File metadata

  • Download URL: phylim-2024.12.3.post1.tar.gz
  • Upload date:
  • Size: 11.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.1.1 CPython/3.12.7

File hashes

Hashes for phylim-2024.12.3.post1.tar.gz
Algorithm Hash digest
SHA256 89e0a934ebe257759b0cafefda4335e6efeac713ad9e1500ac0c4cac3a49d655
MD5 075de95fd09188e8c846f555bf38a979
BLAKE2b-256 428e1fa809b8fd9a0907fe7e84e276ead4fb3b0b55e76ea3a87b207845ed05f8

See more details on using hashes here.

Provenance

The following attestation bundles were made for phylim-2024.12.3.post1.tar.gz:

Publisher: release.yml on HuttleyLab/PhyLim

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file phylim-2024.12.3.post1-py3-none-any.whl.

File metadata

File hashes

Hashes for phylim-2024.12.3.post1-py3-none-any.whl
Algorithm Hash digest
SHA256 ccc2c8d23abdde0d42589184b48b15330403260d10c54cf5a80b033949454210
MD5 212a948a8fe522c4bbff870e714089fb
BLAKE2b-256 031af9d55aa4948386a4ee57cfa310371885160e621e181ad92e0e74b2801f33

See more details on using hashes here.

Provenance

The following attestation bundles were made for phylim-2024.12.3.post1-py3-none-any.whl:

Publisher: release.yml on HuttleyLab/PhyLim

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page