phylogenie 2.1.19__tar.gz → 2.1.21__tar.gz

{phylogenie-2.1.19 → phylogenie-2.1.21}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: phylogenie
-Version: 2.1.19
+Version: 2.1.21
 Summary: Generate phylogenetic datasets with minimal setup effort
 Author: Gabriele Marino
 Author-email: gabmarino.8601@gmail.com

{phylogenie-2.1.19 → phylogenie-2.1.21}/phylogenie/__init__.py

@@ -1,3 +1,4 @@
+from phylogenie.draw import Coloring, draw_tree
 from phylogenie.generators import (
     AliSimDatasetGenerator,
     BDEITreeDatasetGenerator,
@@ -12,7 +13,6 @@ from phylogenie.generators import (
 )
 from phylogenie.io import dump_newick, load_fasta, load_newick
 from phylogenie.msa import MSA
-from phylogenie.plot import Coloring, plot_tree
 from phylogenie.skyline import (
     SkylineMatrix,
     SkylineMatrixCoercible,
@@ -46,6 +46,18 @@ from phylogenie.treesimulator import (
     get_FBD_events,
     simulate_tree,
 )
+from phylogenie.utils import (
+    compute_colless_index,
+    compute_mean_leaf_pairwise_distance,
+    compute_sackin_index,
+    get_distance,
+    get_mrca,
+    get_node_depth_levels,
+    get_node_depths,
+    get_node_height_levels,
+    get_node_heights,
+    get_node_leaf_counts,
+)
 
 __all__ = [
     "AliSimDatasetGenerator",
@@ -92,5 +104,15 @@ __all__ = [
     "load_newick",
     "MSA",
     "Coloring",
-    "plot_tree",
+    "draw_tree",
+    "compute_colless_index",
+    "compute_mean_leaf_pairwise_distance",
+    "compute_sackin_index",
+    "get_distance",
+    "get_mrca",
+    "get_node_depths",
+    "get_node_depth_levels",
+    "get_node_heights",
+    "get_node_height_levels",
+    "get_node_leaf_counts",
 ]

phylogenie-2.1.21/phylogenie/draw.py

@@ -0,0 +1,142 @@
+from enum import Enum
+from typing import Any
+
+import matplotlib.colors as mcolors
+import matplotlib.patches as mpatches
+import matplotlib.pyplot as plt
+from matplotlib.axes import Axes
+from mpl_toolkits.axes_grid1.inset_locator import inset_axes  # pyright: ignore
+
+from phylogenie.tree import Tree
+from phylogenie.utils import get_node_depth_levels, get_node_depths
+
+
+class Coloring(str, Enum):
+    DISCRETE = "discrete"
+    CONTINUOUS = "continuous"
+
+
+Color = str | tuple[float, float, float] | tuple[float, float, float, float]
+
+
+def _draw_colored_tree(tree: Tree, ax: Axes, colors: Color | dict[Tree, Color]) -> Axes:
+    if not isinstance(colors, dict):
+        colors = {node: colors for node in tree}
+
+    xs = (
+        get_node_depth_levels(tree)
+        if any(node.branch_length is None for node in tree)
+        else get_node_depths(tree)
+    )
+    ys = {node: i for i, node in enumerate(tree.inorder_traversal())}
+
+    for node in tree:
+        x1, y1 = xs[node], ys[node]
+        if node.parent is None:
+            ax.hlines(y=y1, xmin=0, xmax=x1, color=colors[node])  # pyright: ignore
+            continue
+        x0, y0 = xs[node.parent], ys[node.parent]
+        ax.vlines(x=x0, ymin=y0, ymax=y1, color=colors[node])  # pyright: ignore
+        ax.hlines(y=y1, xmin=x0, xmax=x1, color=colors[node])  # pyright: ignore
+
+    ax.set_yticks([])  # pyright: ignore
+    return ax
+
+
+def draw_tree(
+    tree: Tree,
+    ax: Axes | None = None,
+    color_by: str | None = None,
+    coloring: str | Coloring | None = None,
+    default_color: Color = "black",
+    cmap: str | None = None,
+    show_legend: bool = True,
+    vmin: float | None = None,
+    vmax: float | None = None,
+    show_hist: bool = True,
+    hist_kwargs: dict[str, Any] | None = None,
+    hist_axes_kwargs: dict[str, Any] | None = None,
+) -> Axes | tuple[Axes, Axes]:
+    if ax is None:
+        ax = plt.gca()
+
+    if color_by is None:
+        return _draw_colored_tree(tree, ax, colors=default_color)
+
+    features = [node.get(color_by) for node in tree if color_by in node.features]
+
+    if coloring is None:
+        coloring = (
+            Coloring.CONTINUOUS
+            if any(isinstance(f, float) for f in features)
+            else Coloring.DISCRETE
+        )
+
+    if coloring == Coloring.DISCRETE:
+        if any(isinstance(f, float) for f in features):
+            raise ValueError(
+                "Discrete coloring selected but feature values are not all categorical."
+            )
+
+        colormap = plt.get_cmap("tab20" if cmap is None else cmap)
+        feature_colors = {
+            f: mcolors.to_hex(colormap(i)) for i, f in enumerate(set(features))
+        }
+        colors = {
+            node: (
+                feature_colors[node.get(color_by)]
+                if color_by in node.features
+                else default_color
+            )
+            for node in tree
+        }
+
+        if show_legend:
+            legend_handles = [
+                mpatches.Patch(color=feature_colors[f], label=str(f))
+                for f in feature_colors
+            ]
+            if any(color_by not in node.features for node in tree):
+                legend_handles.append(mpatches.Patch(color=default_color, label="NA"))
+            ax.legend(handles=legend_handles)  # pyright: ignore
+
+        return _draw_colored_tree(tree, ax, colors)
+
+    if coloring == Coloring.CONTINUOUS:
+        vmin = min(features) if vmin is None else vmin
+        vmax = max(features) if vmax is None else vmax
+        norm = mcolors.Normalize(vmin=vmin, vmax=vmax)
+        colormap = plt.get_cmap("viridis" if cmap is None else cmap)
+        colors = {
+            node: (
+                colormap(norm(float(node.get(color_by))))
+                if color_by in node.features
+                else default_color
+            )
+            for node in tree
+        }
+
+        if show_hist:
+            default_hist_axes_kwargs = {"width": "25%", "height": "25%"}
+            if hist_axes_kwargs is not None:
+                default_hist_axes_kwargs.update(hist_axes_kwargs)
+            hist_ax = inset_axes(ax, **default_hist_axes_kwargs)  # pyright: ignore
+
+            hist_kwargs = {} if hist_kwargs is None else hist_kwargs
+            _, bins, patches = hist_ax.hist(features, **hist_kwargs)  # pyright: ignore
+
+            for patch, b0, b1 in zip(  # pyright: ignore
+                patches, bins[:-1], bins[1:]  # pyright: ignore
+            ):
+                midpoint = (b0 + b1) / 2  # pyright: ignore
+                patch.set_facecolor(colormap(norm(midpoint)))  # pyright: ignore
+            return _draw_colored_tree(tree, ax, colors), hist_ax  # pyright: ignore
+
+        else:
+            sm = plt.cm.ScalarMappable(cmap=colormap, norm=norm)
+            ax.get_figure().colorbar(sm, ax=ax)  # pyright: ignore
+            return _draw_colored_tree(tree, ax, colors)
+
+    raise ValueError(
+        f"Unknown coloring method: {coloring}. Choices are {list(Coloring)}."
+    )

{phylogenie-2.1.19 → phylogenie-2.1.21}/phylogenie/tree.py

@@ -73,6 +73,8 @@ class Tree:
         del self._features[key]
 
     def add_child(self, child: "Tree") -> "Tree":
+        if child.parent is not None:
+            raise ValueError(f"Node {child.name} already has a parent.")
         child._parent = self
         self._children.append(child)
         return self
@@ -81,10 +83,12 @@ class Tree:
         self._children.remove(child)
         child._parent = None
 
-    def set_parent(self, node: "Tree | None"):
-        self._parent = node
-        if node is not None:
-            node._children.append(self)
+    def set_parent(self, parent: "Tree | None"):
+        if self.parent is not None:
+            self.parent.remove_child(self)
+        self._parent = parent
+        if parent is not None:
+            parent._children.append(self)
 
     def inorder_traversal(self) -> Iterator["Tree"]:
         if self.is_leaf():
@@ -107,6 +111,12 @@ class Tree:
             yield from child.postorder_traversal()
         yield self
 
+    def iter_ancestors(self, stop: "Tree | None" = None) -> Iterator["Tree"]:
+        node = self
+        while node is not None and node is not stop:
+            yield node
+            node = node.parent
+
     def breadth_first_traversal(self) -> Iterator["Tree"]:
         queue: deque["Tree"] = deque([self])
         while queue:
@@ -126,6 +136,12 @@ class Tree:
     def get_leaves(self) -> tuple["Tree", ...]:
         return tuple(node for node in self if node.is_leaf())
 
+    def get_internal_nodes(self) -> tuple["Tree", ...]:
+        return tuple(node for node in self if not node.is_leaf())
+
+    def is_binary(self) -> bool:
+        return all(len(node.children) in (0, 2) for node in self)
+
     def ladderize(self, criterion: Callable[["Tree"], Any]) -> None:
         self._children.sort(key=criterion)
         for child in self.children:

phylogenie-2.1.21/phylogenie/utils.py

@@ -0,0 +1,176 @@
+from itertools import chain
+from math import comb
+
+from phylogenie.tree import Tree
+
+
+def get_node_leaf_counts(tree: Tree) -> dict[Tree, int]:
+    n_leaves: dict[Tree, int] = {}
+    for node in tree.postorder_traversal():
+        n_leaves[node] = sum(n_leaves[child] for child in node.children) or 1
+    return n_leaves
+
+
+def get_node_depth_levels(tree: Tree) -> dict[Tree, int]:
+    depth_levels: dict[Tree, int] = {}
+    for node in tree:
+        if node.parent is None:
+            depth_levels[node] = 0
+        else:
+            depth_levels[node] = depth_levels[node.parent] + 1
+    return depth_levels
+
+
+def get_node_depths(tree: Tree) -> dict[Tree, float]:
+    depths: dict[Tree, float] = {}
+    for node in tree:
+        if node.parent is None:
+            depths[node] = 0 if node.branch_length is None else node.branch_length
+        else:
+            if node.branch_length is None:
+                raise ValueError(f"Branch length of node {node.name} is not set.")
+            depths[node] = depths[node.parent] + node.branch_length
+    return depths
+
+
+def get_node_height_levels(tree: Tree) -> dict[Tree, int]:
+    height_levels: dict[Tree, int] = {}
+    for node in tree.postorder_traversal():
+        if node.is_leaf():
+            height_levels[node] = 0
+        else:
+            height_levels[node] = max(
+                1 + height_levels[child] for child in node.children
+            )
+    return height_levels
+
+
+def get_node_heights(tree: Tree) -> dict[Tree, float]:
+    heights: dict[Tree, float] = {}
+    for node in tree.postorder_traversal():
+        if node.is_leaf():
+            heights[node] = 0
+        else:
+            if any(child.branch_length is None for child in node.children):
+                raise ValueError(
+                    f"Branch length of one or more children of node {node.name} is not set."
+                )
+            heights[node] = max(
+                child.branch_length + heights[child]  # pyright: ignore
+                for child in node.children
+            )
+    return heights
+
+
+def get_mrca(node1: Tree, node2: Tree) -> Tree:
+    node1_ancestors = set(node1.iter_ancestors())
+    for node2_ancestor in node2.iter_ancestors():
+        if node2_ancestor in node1_ancestors:
+            return node2_ancestor
+    raise ValueError(f"No common ancestor found between node {node1} and node {node2}.")
+
+
+def get_distance(node1: Tree, node2: Tree) -> float:
+    mrca = get_mrca(node1, node2)
+    path = list(chain(node1.iter_ancestors(stop=mrca), node2.iter_ancestors(stop=mrca)))
+    if any(node.branch_length is None for node in path):
+        return len(path)
+    return sum(node.branch_length for node in path)  # pyright: ignore
+
+
+def compute_sackin_index(tree: Tree, normalize: bool = False) -> float:
+    """
+    Compute the Sackin index of a tree.
+
+    Parameters
+    ----------
+    tree : Tree
+        The input tree.
+    normalize : bool, optional
+        Whether to normalize the index between 0 and 1, by default False.
+
+    Returns
+    -------
+    float
+        The Sackin index of the tree.
+
+    References
+    ----------
+    - Kwang-Tsao Shao and Robert R Sokal. Tree Balance. Systematic Zoology, 39(3):266, 1990.
+    """
+    leaves = tree.get_leaves()
+    depth_levels = get_node_depth_levels(tree)
+    sackin_index = sum(depth_levels[leaf] for leaf in leaves)
+    if normalize:
+        n = len(leaves)
+        max_sackin_index = (n + 2) * (n - 1) / 2
+        return (sackin_index - n) / (max_sackin_index - n)
+    return sackin_index
+
+
+def compute_colless_index(tree: Tree, normalize: bool = False) -> float:
+    """
+    Compute the Colless index of a binary tree.
+
+    Parameters
+    ----------
+    tree : Tree
+        The input binary tree.
+    normalize : bool, optional
+        Whether to normalize the index between 0 and 1, by default False.
+
+    Returns
+    -------
+    float
+        The Colless index of the tree.
+
+    References
+    ----------
+    - Donald H. Colless. Review of phylogenetics: the theory and practice of phylogenetic systematics. Systematic Zoology, 31(1):100–104, 1982.
+    """
+    if not tree.is_binary():
+        raise ValueError("Colless index is only defined for binary trees.")
+
+    internal_nodes = tree.get_internal_nodes()
+    if not internal_nodes:
+        raise ValueError(
+            "Tree must have at least one internal node to compute the Colless index."
+        )
+
+    colless_index = 0
+    leaf_counts = get_node_leaf_counts(tree)
+    for node in internal_nodes:
+        left, right = node.children
+        colless_index += abs(leaf_counts[left] - leaf_counts[right])
+    if normalize:
+        n_leaves = len(leaf_counts) - len(internal_nodes)
+        max_colless_index = comb(n_leaves, 2)
+        return colless_index / max_colless_index
+    return colless_index
+
+
+def compute_mean_leaf_pairwise_distance(tree: Tree) -> float:
+    """
+    Compute the mean pairwise distance between all pairs of leaves in the tree.
+
+    Parameters
+    ----------
+    tree : Tree
+        The input tree.
+
+    Returns
+    -------
+    float
+        The mean pairwise distance between all pairs of leaves in the tree.
+    """
+    leaves = tree.get_leaves()
+    n_leaves = len(leaves)
+    if n_leaves < 2:
+        return 0.0
+
+    total_distance = sum(
+        get_distance(leaves[i], leaves[j])
+        for i in range(n_leaves)
+        for j in range(i + 1, n_leaves)
+    )
+    return total_distance / comb(n_leaves, 2)

{phylogenie-2.1.19 → phylogenie-2.1.21}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "phylogenie"
-version = "2.1.19"
+version = "2.1.21"
 description = "Generate phylogenetic datasets with minimal setup effort"
 authors = ["Gabriele Marino <gabmarino.8601@gmail.com>"]
 readme = "README.md"

phylogenie-2.1.19/phylogenie/plot.py

@@ -1,136 +0,0 @@
-from enum import Enum
-from typing import Any
-
-import matplotlib.colors as mcolors
-import matplotlib.patches as mpatches
-import matplotlib.pyplot as plt
-from matplotlib.axes import Axes
-from mpl_toolkits.axes_grid1.inset_locator import inset_axes  # pyright: ignore
-
-from phylogenie.tree import Tree
-from phylogenie.utils import get_node_depth_levels, get_node_depths
-
-
-class Coloring(str, Enum):
-    DISCRETE = "discrete"
-    CONTINUOUS = "continuous"
-
-
-def plot_tree(
-    tree: Tree,
-    ax: Axes | None = None,
-    color_by: str | None = None,
-    default_color: str = "black",
-    coloring: str | Coloring | None = None,
-    cmap: str | None = None,
-    show_legend: bool = True,
-    show_hist: bool = True,
-    hist_kwargs: dict[str, Any] | None = None,
-    hist_axes_kwargs: dict[str, Any] | None = None,
-) -> Axes | tuple[Axes, Axes]:
-    if ax is None:
-        ax = plt.gca()
-
-    xs = (
-        get_node_depth_levels(tree)
-        if any(node.branch_length is None for node in tree)
-        else get_node_depths(tree)
-    )
-    ys = {node: i for i, node in enumerate(tree.inorder_traversal())}
-
-    if color_by is not None:
-        features = [node.get(color_by) for node in tree if color_by in node.features]
-
-        if coloring is None and any(isinstance(f, float) for f in features):
-            coloring = Coloring.CONTINUOUS
-        elif coloring is None:
-            coloring = Coloring.DISCRETE
-
-        if coloring == Coloring.DISCRETE:
-            if any(isinstance(f, float) for f in features):
-                raise ValueError(
-                    "Discrete coloring selected but feature values are not all categorical."
-                )
-            colormap = plt.get_cmap("tab20" if cmap is None else cmap)
-            feature_colors = {
-                f: mcolors.to_hex(colormap(i)) for i, f in enumerate(set(features))
-            }
-            colors = {
-                node: (
-                    feature_colors[node.get(color_by)]
-                    if color_by in node.features
-                    else default_color
-                )
-                for node in tree
-            }
-
-            if show_legend:
-                legend_handles = [
-                    mpatches.Patch(color=feature_colors[f], label=str(f))
-                    for f in feature_colors
-                ]
-                if any(color_by not in node.features for node in tree):
-                    legend_handles.append(
-                        mpatches.Patch(color=default_color, label="NA")
-                    )
-                ax.legend(handles=legend_handles, title=color_by)  # pyright: ignore
-
-        elif coloring == Coloring.CONTINUOUS:
-            norm = mcolors.Normalize(vmin=min(features), vmax=max(features))
-            colormap = plt.get_cmap("viridis" if cmap is None else cmap)
-            colors = {
-                node: (
-                    colormap(norm(float(node.get(color_by))))
-                    if color_by in node.features
-                    else default_color
-                )
-                for node in tree
-            }
-
-            if show_hist:
-                default_hist_axes_kwargs = {"width": "25%", "height": "25%"}
-                if hist_axes_kwargs is not None:
-                    default_hist_axes_kwargs.update(hist_axes_kwargs)
-                hist_ax = inset_axes(ax, **default_hist_axes_kwargs)  # pyright: ignore
-
-                hist_kwargs = {} if hist_kwargs is None else hist_kwargs
-                _, bins, patches = hist_ax.hist(  # pyright: ignore
-                    features, **hist_kwargs
-                )
-
-                for patch, b0, b1 in zip(  # pyright: ignore
-                    patches, bins[:-1], bins[1:]  # pyright: ignore
-                ):
-                    midpoint = (b0 + b1) / 2  # pyright: ignore
-                    patch.set_facecolor(colormap(norm(midpoint)))  # pyright: ignore
-            else:
-                sm = plt.cm.ScalarMappable(cmap=colormap, norm=norm)
-                ax.get_figure().colorbar(sm, ax=ax)  # pyright: ignore
-
-        else:
-            raise ValueError(
-                f"Unknown coloring method: {coloring}. Choices are {list(Coloring)}."
-            )
-    else:
-        colors = {node: default_color for node in tree}
-
-    for node in tree:
-        x1, y1 = xs[node], ys[node]
-        if node.parent is None:
-            ax.hlines(y=y1, xmin=0, xmax=x1, color=colors[node])  # pyright: ignore
-            continue
-        x0, y0 = xs[node.parent], ys[node.parent]
-        ax.vlines(x=x0, ymin=y0, ymax=y1, color=colors[node])  # pyright: ignore
-        ax.hlines(y=y1, xmin=x0, xmax=x1, color=colors[node])  # pyright: ignore
-
-    for node in tree:
-        x1, y1 = xs[node], ys[node]
-        if node.parent is None:
-            ax.hlines(y=y1, xmin=0, xmax=x1, color=colors[node])  # pyright: ignore
-            continue
-        x0, y0 = xs[node.parent], ys[node.parent]
-        ax.vlines(x=x0, ymin=y0, ymax=y1, color=colors[node])  # pyright: ignore
-        ax.hlines(y=y1, xmin=x0, xmax=x1, color=colors[node])  # pyright: ignore
-
-    ax.set_yticks([])  # pyright: ignore
-    return ax

phylogenie-2.1.19/phylogenie/utils.py

@@ -1,59 +0,0 @@
-from phylogenie.tree import Tree
-
-
-def get_node_leaf_counts(tree: Tree) -> dict[Tree, int]:
-    n_leaves: dict[Tree, int] = {}
-    for node in tree.postorder_traversal():
-        n_leaves[node] = sum(n_leaves[child] for child in node.children) or 1
-    return n_leaves
-
-
-def get_node_depth_levels(tree: Tree) -> dict[Tree, int]:
-    depth_levels: dict[Tree, int] = {}
-    for node in tree:
-        if node.parent is None:
-            depth_levels[node] = 0
-        else:
-            depth_levels[node] = depth_levels[node.parent] + 1
-    return depth_levels
-
-
-def get_node_depths(tree: Tree) -> dict[Tree, float]:
-    depths: dict[Tree, float] = {}
-    for node in tree:
-        if node.parent is None:
-            depths[node] = 0 if node.branch_length is None else node.branch_length
-        else:
-            if node.branch_length is None:
-                raise ValueError(f"Branch length of node {node.name} is not set.")
-            depths[node] = depths[node.parent] + node.branch_length
-    return depths
-
-
-def get_node_height_levels(tree: Tree) -> dict[Tree, int]:
-    height_levels: dict[Tree, int] = {}
-    for node in tree.postorder_traversal():
-        if node.is_leaf():
-            height_levels[node] = 0
-        else:
-            height_levels[node] = max(
-                1 + height_levels[child] for child in node.children
-            )
-    return height_levels
-
-
-def get_node_heights(tree: Tree) -> dict[Tree, float]:
-    heights: dict[Tree, float] = {}
-    for node in tree.postorder_traversal():
-        if node.is_leaf():
-            heights[node] = 0
-        else:
-            if any(child.branch_length is None for child in node.children):
-                raise ValueError(
-                    f"Branch length of one or more children of node {node.name} is not set."
-                )
-            heights[node] = max(
-                child.branch_length + heights[child]  # pyright: ignore
-                for child in node.children
-            )
-    return heights