DOCSEARCHbyAlgolia
Submit Docs

DendroPy

repository·main·Indexed 42 days ago

https://github.com/jeetsukumaran/dendropy

A mature Python library for phylogenetic computing used for the simulation, processing, and manipulation of phylogenetic trees and character matrices. It supports various data formats including NEXUS, NEWICK, NeXML, Phylip, and FASTA, and can be used as a standalone tool or integrated into bioinformatics pipelines.

Tokens
75.4K
Snippets
243
Records
356
Agent score
52%

What's inside DendroPy

  1. Overview of DendroPy capabilities

    main

    DendroPy is a Python library designed for phylogenetic computing. It is suitable for use as a standalone library, a component in multi-library pipelines, or as glue code for assembling phylogenetic workflows.

    Core Capabilities:

    • Simulation, processing, and manipulation of phylogenetic trees and character matrices.
    • Data I/O: Supports reading and writing various phylogenetic data formats including:
      • NEXUS
      • NEWICK
      • NeXML
      • Phylip
      • FASTA
    • Application Scripts: Includes distributed scripts for common operations like data conversion and tree posterior distribution summarization.

  2. Overview of DendroPy 5 features

    main

    DendroPy is a Python library designed for phylogenetic computing, providing rich object-oriented representations for manipulating phylogenetic trees and character matrices.

    Key capabilities include:

    • Data Formats: Loading and saving common phylogenetic formats such as NEXUS, Newick, NeXML, Phylip, and FASTA.
    • Tree Representation: Efficient, bit-level representation of nodes' leaf bipartitions and user-extensible tree models.
    • Simulation: Simulating phylogenetic trees using various models, including coalescent models, birth-death models, and population genetics simulations of gene trees.
    • Utilities: Application scripts for data conversion, taxon label collation across multiple trees, and tree posterior distribution summarization.
    • Evolutionary Models: A broad portfolio of evolutionary models, including population genetics and sequence evolution utilities.

  4. Explore the DendroPy Library Reference

    main

    DendroPy is organized into four primary functional areas for phylogenetic analysis:

    1. Data Model: Core abstractions for representing phylogenetic data, including taxa, trees, tree collections, character states, matrices, and datasets.
    2. Process Models: Implementations of evolutionary and biological processes such as Birth-Death, Coalescent, Parsimony, and Speciation models.
    3. Calculations, Statistics, and Metrics: Tools for measuring tree properties, comparing trees, calculating scores, and performing population genetic statistics.
    4. Simulations: Frameworks for simulating trees and population genetic data.

  6. What is a TreeList and how does it work?

    main

    A TreeList is a collection of Tree objects that are constrained to share the same TaxonNamespace.

    When you add a Tree to a TreeList, DendroPy automatically ensures the tree's taxon_namespace attribute matches the TreeList's namespace. All referenced Taxon objects are mapped to the corresponding objects in the TreeList's namespace; if a match isn't found, new Taxon objects are created.

    TreeList objects also include an annotations attribute (an AnnotationSet) for tracking metadata across the collection.

  7. Understand Bipartition immutability and hashing

    main

    In DendroPy, Bipartition instances are immutable by default. This allows them to be used as efficient keys in sets or dictionaries (O(1) lookup).

    • Equality: Two Bipartition objects are considered equivalent if their Bipartition.split_bitmask values are identical, even if they belong to different trees or edges.
    • Hashing: The hash value of a Bipartition is derived from its split_bitmask.
    • Modification: If you must modify a Bipartition, you must set Bipartition.is_mutable = True.

    CRITICAL WARNING: Never modify a Bipartition instance if it is already being used as a key in a set or dictionary, as this will make the instance (and potentially other members of the container) inaccessible.

  8. Understand Bipartitions in DendroPy

    main

    A Bipartition is a division of a tree's leaves into two mutually-exclusive and collectively-exhaustive subsets. In evolutionary trees, every edge corresponds to a bipartition: splitting the tree at that edge creates two sets of taxa.

    In DendroPy, bipartitions are represented as integers interpreted as bitmasks (or bit vectors). Each bit position corresponds to a taxon index, and the bit value (0 or 1) indicates which of the two groups that taxon belongs to.

  9. Manage shared TaxonNamespaces across matrices

    main

    When creating multiple character matrices (or trees) that refer to the same set of taxa, you must pass a common TaxonNamespace instance to each. If you do not specify one, DendroPy will create a new, independent namespace for every object, preventing them from being linked correctly.

    import dendropy

taxa = dendropy.TaxonNamespace()
dna1 = dendropy.DnaCharacterMatrix.get(
    path="pythonidae_cytb.fasta",
    schema="fasta",
    taxon_namespace=taxa)
prot1 = dendropy.ProteinCharacterMatrix.get(
    path="pythonidae_morph.nex",
    schema="nexus",
    taxon_namespace=taxa)
trees = dendropy.TreeList.get(
    path="pythonidae.trees.nex",
    schema="nexus",
    taxon_namespace=taxa)

  10. Understand Primary Phylogenetic Data Objects

    main

    DendroPy represents phylogenetic data using several core classes. Understanding these abstractions is essential for navigating the library's data model:

    • Taxon: Represents an operational taxonomic unit. Use the label attribute to access its name.
    • TaxonNamespace: A collection of Taxon objects defining a specific set of taxa.
    • Tree: A collection of Node and Edge objects.
      • Each Tree has a taxon_namespace attribute.
      • Each Node has a taxon attribute (pointing to a Taxon or None), a parent_node attribute, and can access children via child_nodes().
    • TreeList: A list of Tree objects. It maintains a single taxon_namespace that all member trees must adhere to.
    • CharacterMatrix: Represents character data (e.g., DnaCharacterMatrix, ProteinCharacterMatrix). It behaves similarly to a dict, where Taxon objects are keys and character data are values.
    • DataSet: A meta-collection containing multiple taxon_namespaces, tree_lists, and char_matrices.
    • TreeArray: A high-performance container for managing large collections of trees efficiently.

  11. How Bipartition Bitmask Encoding Works

    main

    DendroPy uses a right-to-left (least-significant bit first) ordering for bitmasks. The first taxon (index 1) corresponds to the right-most bit (the least significant bit).

    Example Encoding

    For a tree (A,(B,(C,(D,E)))); with 5 taxa, the leaf bitmasks are assigned based on taxon indices:

    • A: 00001 (binary) = 1 (decimal)
    • B: 00011 (binary) = 3 (decimal)
    • C: 00111 (binary) = 7 (decimal)
    • D: 01111 (binary) = 15 (decimal)
    • E: 11111 (binary) = 31 (decimal)

    Internal nodes are calculated by performing a bitwise OR operation on the bitmasks of their children.

    [&R] (A,(B,(C,(D,E))));

/----------------------------- 00001 (A)
11111
|      /---------------------- 00010 (B)
\------11110
    |       /-------------- 00100 (C)
    \-------11100
            |       /------- 01000 (D)
            \-------11000
                    \------- 10000 (E)

  12. How metadata annotations work in DendroPy

    main

    DendroPy uses a hierarchical metadata system to decorate phylogenetic objects like DataSet, TaxonNamespace, Taxon, TreeList, Tree, and CharacterMatrix.

    Core Components

    • Annotation: The fundamental unit of metadata. Each object represents a single metadata item, storing at minimum a name and a value.
    • AnnotationSet: An "annotations manager" container (a specialized OrderedSet) that holds a collection of Annotation objects.

    Accessing Annotations

    Most phylogenetic data objects have an .annotations attribute which is an instance of AnnotationSet. You can iterate over this attribute to access individual metadata items.

    Serialization Behavior

    • NeXML: Annotations are rendered as meta elements. This format provides the most robust support for metadata and ensures stable round-tripping.
    • NEXUS/NEWICK: Annotations are rendered as ampersand-prepended comment strings.

    Note that full metadata expression and consistent round-tripping are best achieved using the NeXML format.

    import dendropy

# Example: Accessing annotations from a loaded dataset
ds = dendropy.DataSet.get_from_path("sample1.xml", "nexml")
for a in ds.annotations:
    print(f"{a.name} = '{a.value}'")

# Accessing annotations from trees within the dataset
for tree_list in ds.tree_lists:
    for tree in tree_list:
        print(f"\n-- (tree '{tree.label}') --\n")
        for a in tree.annotations:
            print(f"{a.name} = '{a.value}'")