phylogenie 3.1.7__tar.gz → 3.1.18__tar.gz

{phylogenie-3.1.7/src/phylogenie.egg-info → phylogenie-3.1.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phylogenie
-Version: 3.1.7
+Version: 3.1.18
 Summary: Generate phylogenetic datasets with minimal setup effort
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -23,7 +23,6 @@ Dynamic: license-file
 [![PyPI version](https://img.shields.io/pypi/v/phylogenie)](https://pypi.org/project/phylogenie/)
 ![Downloads](https://img.shields.io/pypi/dm/phylogenie)
 
-
 Phylogenie is a [Python](https://www.python.org/) package designed to easily simulate phylogenetic datasets—such as trees and multiple sequence alignments (MSAs)—with minimal setup effort. Simply specify the distributions from which your parameters should be sampled, and Phylogenie will handle the rest!
 
 ## ✨ Features
@@ -73,21 +72,21 @@ Phylogenie relies on [AliSim](https://iqtree.github.io/doc/AliSim) for simulatin
 
 ## 🚀 Quick Start
 
-Once you have installed Phylogenie, check out the [examples](https://github.com/gabriele-marino/phylogenie/tree/main/examples) folder.  
+Once you have installed Phylogenie, check out the [tutorials](https://github.com/gabriele-marino/phylogenie/tree/main/tutorials) folder.  
 It includes a collection of thoroughly commented configuration files, organized as a step-by-step tutorial. These examples will help you understand how to use Phylogenie in practice and can be easily adapted to fit your own workflow.
 
 For quick start, pick your favorite config file and run Phylogenie with:
 ```bash
-phylogenie examples/config_file.yaml
+phylogenie tutorials/config_file.yaml
 ```
 This command will create the output dataset in the folder specified inside the configuration file, including data directories and metadata files for each dataset split defined in the config.
 
 >❗ *Tip*: Can’t choose just one config file?
-You can run them all at once by pointing Phylogenie to the folder! Just use: `phylogenie examples`. In this mode, Phylogenie will automatically find all `.yaml` files in the folder you specified and run for each of them!
+You can run them all at once by pointing Phylogenie to the folder! Just use: `phylogenie tutorials`. In this mode, Phylogenie will automatically find all `.yaml` files in the folder you specified and run for each of them!
 
 ## 📖 Documentation
 
-- The [examples](https://github.com/gabriele-marino/phylogenie/tree/main/examples) folder contains many ready-to-use, extensively commented configuration files that serve as a step-by-step tutorial to guide you through using Phylogenie. You can explore them to learn how it works or adapt them directly to your own workflows.
+- The [tutorials](https://github.com/gabriele-marino/phylogenie/tree/main/tutorials) folder contains many ready-to-use, extensively commented configuration files that serve as a step-by-step tutorial to guide you through using Phylogenie. You can explore them to learn how it works or adapt them directly to your own workflows.
 - A complete user guide and API reference are under development. In the meantime, feel free to [reach out](mailto:gabmarino.8601@email.com) if you have any questions about integrating Phylogenie into your workflows.
 
 ## 📄 License

{phylogenie-3.1.7 → phylogenie-3.1.18}/README.md

@@ -8,7 +8,6 @@
 [![PyPI version](https://img.shields.io/pypi/v/phylogenie)](https://pypi.org/project/phylogenie/)
 ![Downloads](https://img.shields.io/pypi/dm/phylogenie)
 
-
 Phylogenie is a [Python](https://www.python.org/) package designed to easily simulate phylogenetic datasets—such as trees and multiple sequence alignments (MSAs)—with minimal setup effort. Simply specify the distributions from which your parameters should be sampled, and Phylogenie will handle the rest!
 
 ## ✨ Features
@@ -58,21 +57,21 @@ Phylogenie relies on [AliSim](https://iqtree.github.io/doc/AliSim) for simulatin
 
 ## 🚀 Quick Start
 
-Once you have installed Phylogenie, check out the [examples](https://github.com/gabriele-marino/phylogenie/tree/main/examples) folder.  
+Once you have installed Phylogenie, check out the [tutorials](https://github.com/gabriele-marino/phylogenie/tree/main/tutorials) folder.  
 It includes a collection of thoroughly commented configuration files, organized as a step-by-step tutorial. These examples will help you understand how to use Phylogenie in practice and can be easily adapted to fit your own workflow.
 
 For quick start, pick your favorite config file and run Phylogenie with:
 ```bash
-phylogenie examples/config_file.yaml
+phylogenie tutorials/config_file.yaml
 ```
 This command will create the output dataset in the folder specified inside the configuration file, including data directories and metadata files for each dataset split defined in the config.
 
 >❗ *Tip*: Can’t choose just one config file?
-You can run them all at once by pointing Phylogenie to the folder! Just use: `phylogenie examples`. In this mode, Phylogenie will automatically find all `.yaml` files in the folder you specified and run for each of them!
+You can run them all at once by pointing Phylogenie to the folder! Just use: `phylogenie tutorials`. In this mode, Phylogenie will automatically find all `.yaml` files in the folder you specified and run for each of them!
 
 ## 📖 Documentation
 
-- The [examples](https://github.com/gabriele-marino/phylogenie/tree/main/examples) folder contains many ready-to-use, extensively commented configuration files that serve as a step-by-step tutorial to guide you through using Phylogenie. You can explore them to learn how it works or adapt them directly to your own workflows.
+- The [tutorials](https://github.com/gabriele-marino/phylogenie/tree/main/tutorials) folder contains many ready-to-use, extensively commented configuration files that serve as a step-by-step tutorial to guide you through using Phylogenie. You can explore them to learn how it works or adapt them directly to your own workflows.
 - A complete user guide and API reference are under development. In the meantime, feel free to [reach out](mailto:gabmarino.8601@email.com) if you have any questions about integrating Phylogenie into your workflows.
 
 ## 📄 License

{phylogenie-3.1.7 → phylogenie-3.1.18}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "phylogenie"
-version = "3.1.7"
+version = "3.1.18"
 description = "Generate phylogenetic datasets with minimal setup effort"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -29,4 +29,4 @@ phylogenie = "phylogenie.main:main"
 
 [build-system]
 requires = ["setuptools>=42"]
-build-backend = "setuptools.build_meta"
+build-backend = "setuptools.build_meta"

{phylogenie-3.1.7 → phylogenie-3.1.18}/src/phylogenie/__init__.py

@@ -1,11 +1,3 @@
-from phylogenie.draw import (
-    draw_colored_dated_tree_categorical,
-    draw_colored_dated_tree_continuous,
-    draw_colored_tree_categorical,
-    draw_colored_tree_continuous,
-    draw_dated_tree,
-    draw_tree,
-)
 from phylogenie.generators import (
     AliSimDatasetGenerator,
     BDEITreeDatasetGenerator,
@@ -46,6 +38,7 @@ from phylogenie.treesimulator import (
     Tree,
     compute_mean_leaf_pairwise_distance,
     compute_sackin_index,
+    count_hops,
     dump_newick,
     generate_trees,
     get_BD_events,
@@ -58,12 +51,15 @@ from phylogenie.treesimulator import (
     get_FBD_events,
     get_mrca,
     get_mutation_id,
+    get_node_ages,
     get_node_depth_levels,
     get_node_depths,
     get_node_height_levels,
     get_node_heights,
     get_node_leaf_counts,
     get_node_state,
+    get_node_times,
+    get_path,
     load_newick,
     load_nexus,
     set_features,
@@ -71,12 +67,6 @@ from phylogenie.treesimulator import (
 )
 
 __all__ = [
-    "draw_colored_dated_tree_categorical",
-    "draw_colored_dated_tree_continuous",
-    "draw_colored_tree_categorical",
-    "draw_colored_tree_continuous",
-    "draw_dated_tree",
-    "draw_tree",
     "AliSimDatasetGenerator",
     "BDEITreeDatasetGenerator",
     "BDSSTreeDatasetGenerator",
@@ -114,6 +104,7 @@ __all__ = [
     "Tree",
     "compute_mean_leaf_pairwise_distance",
     "compute_sackin_index",
+    "count_hops",
     "dump_newick",
     "generate_trees",
     "get_BD_events",
@@ -126,12 +117,15 @@ __all__ = [
     "get_FBD_events",
     "get_mrca",
     "get_mutation_id",
+    "get_node_ages",
     "get_node_depth_levels",
     "get_node_depths",
     "get_node_height_levels",
     "get_node_heights",
     "get_node_leaf_counts",
     "get_node_state",
+    "get_node_times",
+    "get_path",
     "load_newick",
     "load_nexus",
     "set_features",

{phylogenie-3.1.7 → phylogenie-3.1.18}/src/phylogenie/draw.py

@@ -1,5 +1,6 @@
+import datetime
+from collections.abc import Mapping
 from dataclasses import dataclass
-from datetime import datetime
 from typing import Any, Literal, overload
 
 import matplotlib.colors as mcolors
@@ -10,13 +11,18 @@ from matplotlib.axes import Axes
 from matplotlib.colors import Colormap
 from mpl_toolkits.axes_grid1.inset_locator import inset_axes  # pyright: ignore
 
-from phylogenie.treesimulator import Tree, get_node_depth_levels, get_node_depths
+from phylogenie.treesimulator import (
+    Tree,
+    get_node_ages,
+    get_node_depth_levels,
+    get_node_depths,
+)
 
 
 @dataclass
 class CalibrationNode:
     node: Tree
-    date: datetime
+    date: datetime.date
 
 
 Color = str | tuple[float, float, float] | tuple[float, float, float, float]
@@ -25,8 +31,10 @@ Color = str | tuple[float, float, float] | tuple[float, float, float, float]
 def draw_tree(
     tree: Tree,
     ax: Axes | None = None,
-    colors: Color | dict[Tree, Color] = "black",
+    colors: Color | Mapping[Tree, Color] = "black",
     backward_time: bool = False,
+    branch_kwargs: dict[str, Any] | None = None,
+    sampled_ancestor_kwargs: dict[str, Any] | None = None,
 ) -> Axes:
     """
     Draw a phylogenetic tree with colored branches.
@@ -37,10 +45,14 @@ def draw_tree(
         The phylogenetic tree to draw.
     ax : Axes | None, optional
         The matplotlib Axes to draw on. If None, uses the current Axes.
-    colors : Color | dict[Tree, Color], optional
-        A single color for all branches or a dictionary mapping each node to a color.
+    colors : Color | Mapping[Tree, Color], optional
+        A single color for all branches or a mapping from each node to a color.
     backward_time : bool, optional
         If True, the x-axis is inverted to represent time going backward.
+    branch_kwargs : dict[str, Any] | None, optional
+        Additional keyword arguments to pass to the branch drawing functions.
+    sampled_ancestor_kwargs : dict[str, Any] | None, optional
+        Additional keyword arguments to highlight sampled ancestors.
 
     Returns
     -------
@@ -49,33 +61,51 @@ def draw_tree(
     """
     if ax is None:
         ax = plt.gca()
-
-    if not isinstance(colors, dict):
+    if branch_kwargs is None:
+        branch_kwargs = {}
+    if sampled_ancestor_kwargs is None:
+        sampled_ancestor_kwargs = {}
+    if "marker" not in sampled_ancestor_kwargs:
+        sampled_ancestor_kwargs["marker"] = "o"
+
+    if not isinstance(colors, Mapping):
         colors = {node: colors for node in tree}
 
     xs = (
-        get_node_depth_levels(tree)
+        get_node_ages(tree)
+        if backward_time
+        else get_node_depth_levels(tree)
         if any(node.branch_length is None for node in tree.iter_descendants())
         else get_node_depths(tree)
     )
-    if backward_time:
-        max_x = max(xs.values())
-        xs = {node: max_x - x for node, x in xs.items()}
 
-    ys: dict[Tree, float] = {node: i for i, node in enumerate(tree.get_leaves())}
+    leaves = tree.get_leaves()
+    ys: dict[Tree, float] = {
+        node: i
+        for i, node in enumerate(leaves)
+        if node.parent is None or node.branch_length != 0
+    }
     for node in tree.postorder_traversal():
         if node.is_internal():
-            ys[node] = sum(ys[child] for child in node.children) / len(node.children)
+            children = [child for child in node.children if child.branch_length != 0]
+            ys[node] = sum(ys[child] for child in children) / len(children)
+    for leaf in leaves:
+        if leaf.parent is not None and leaf.branch_length == 0:
+            ys[leaf] = ys[leaf.parent]
 
     if tree.branch_length is not None:
         xmin = xs[tree] + tree.branch_length if backward_time else 0
-        ax.hlines(y=ys[tree], xmin=xmin, xmax=xs[tree], color=colors[tree])  # pyright: ignore
+        ax.hlines(  # pyright: ignore
+            y=ys[tree], xmin=xmin, xmax=xs[tree], color=colors[tree], **branch_kwargs
+        )
     for node in tree:
         x1, y1 = xs[node], ys[node]
+        if node.parent is not None and node.branch_length == 0:
+            ax.plot(x1, y1, color=colors[node], **sampled_ancestor_kwargs)  # pyright: ignore
         for child in node.children:
             x2, y2 = xs[child], ys[child]
-            ax.hlines(y=y2, xmin=x1, xmax=x2, color=colors[child])  # pyright: ignore
-            ax.vlines(x=x1, ymin=y1, ymax=y2, color=colors[child])  # pyright: ignore
+            ax.hlines(y=y2, xmin=x1, xmax=x2, color=colors[child], **branch_kwargs)  # pyright: ignore
+            ax.vlines(x=x1, ymin=y1, ymax=y2, color=colors[child], **branch_kwargs)  # pyright: ignore
 
     if backward_time:
         ax.invert_xaxis()
@@ -86,7 +116,7 @@ def draw_tree(
 
 def _depth_to_date(
     depth: float, calibration_nodes: tuple[CalibrationNode, CalibrationNode]
-) -> datetime:
+) -> datetime.date:
     """
     Convert a depth value to a date using linear interpolation between two calibration nodes.
 
@@ -99,7 +129,7 @@ def _depth_to_date(
 
     Returns
     -------
-    datetime
+    datetime.date
         The interpolated date corresponding to the given depth.
     """
     node1, node2 = calibration_nodes
@@ -112,7 +142,8 @@ def draw_dated_tree(
     tree: Tree,
     calibration_nodes: tuple[CalibrationNode, CalibrationNode],
     ax: Axes | None = None,
-    colors: Color | dict[Tree, Color] = "black",
+    colors: Color | Mapping[Tree, Color] = "black",
+    branch_kwargs: dict[str, Any] | None = None,
 ) -> Axes:
     """
     Draw a phylogenetic tree with branches positioned according to calibrated dates.
@@ -125,8 +156,10 @@ def draw_dated_tree(
         Two calibration nodes defining the mapping from depth to date.
     ax : Axes | None, optional
         The matplotlib Axes to draw on. If None, uses the current Axes.
-    colors : Color | dict[Tree, Color], optional
-        A single color for all branches or a dictionary mapping each node to a color.
+    colors : Color | Mapping[Tree, Color], optional
+        A single color for all branches or a mapping from each node to a color.
+    branch_kwargs : dict[str, Any] | None, optional
+        Additional keyword arguments to pass to the branch drawing functions.
 
     Returns
     -------
@@ -135,8 +168,10 @@ def draw_dated_tree(
     """
     if ax is None:
         ax = plt.gca()
+    if branch_kwargs is None:
+        branch_kwargs = {}
 
-    if not isinstance(colors, dict):
+    if not isinstance(colors, Mapping):
         colors = {node: colors for node in tree}
 
     xs = {
@@ -156,6 +191,7 @@ def draw_dated_tree(
             xmin=mdates.date2num(origin_date),  # pyright: ignore
             xmax=mdates.date2num(xs[tree]),  # pyright: ignore
             color=colors[tree],
+            **branch_kwargs,
         )
     for node in tree:
         x1, y1 = xs[node], ys[node]
@@ -166,8 +202,15 @@ def draw_dated_tree(
                 xmin=mdates.date2num(x1),  # pyright: ignore
                 xmax=mdates.date2num(x2),  # pyright: ignore
                 color=colors[child],
+                **branch_kwargs,
+            )
+            ax.vlines(  # pyright: ignore
+                x=mdates.date2num(x1),  # pyright: ignore
+                ymin=y1,
+                ymax=y2,
+                color=colors[child],
+                **branch_kwargs,
             )
-            ax.vlines(x=mdates.date2num(x1), ymin=y1, ymax=y2, color=colors[child])  # pyright: ignore
 
     ax.xaxis.set_major_locator(mdates.AutoDateLocator())
     ax.xaxis.set_major_formatter(mdates.DateFormatter("%Y-%m-%d"))
@@ -182,9 +225,9 @@ def _init_colored_tree_categorical(
     color_by: str,
     ax: Axes | None = None,
     default_color: Color = "black",
-    colormap: str | Colormap = "tab20",
+    colormap: str | Mapping[str, Color] | Colormap = "tab20",
     show_legend: bool = True,
-    labels: dict[Any, str] | None = None,
+    labels: Mapping[Any, str] | None = None,
     legend_kwargs: dict[str, Any] | None = None,
 ) -> tuple[Axes, dict[Tree, Color]]:
     """
@@ -200,11 +243,14 @@ def _init_colored_tree_categorical(
         The matplotlib Axes to draw on. If None, uses the current Axes.
     default_color : Color, optional
         The color to use for nodes without the specified metadata.
-    colormap : str | Colormap, optional
-        The colormap to use for coloring categories. Defaults to 'tab20'.
+    colormap : str | Mapping[str, Color] | Colormap, optional
+        The colormap to use for coloring categories.
+        If a string, it is used to get a matplotlib colormap.
+        If a mapping, it maps category values to colors directly.
+        Defaults to 'tab20'.
     show_legend : bool, optional
         Whether to display a legend for the categories.
-    labels : dict[Any, str] | None, optional
+    labels : Mapping[Any, str] | None, optional
         A mapping from category values to labels for the legend.
     legend_kwargs : dict[str, Any] | None, optional
         Additional keyword arguments to pass to the legend.
@@ -217,13 +263,16 @@ def _init_colored_tree_categorical(
     if ax is None:
         ax = plt.gca()
 
+    features = {node: node[color_by] for node in tree if color_by in node.metadata}
     if isinstance(colormap, str):
         colormap = plt.get_cmap(colormap)
+    if isinstance(colormap, Colormap):
+        feature_colors = {
+            f: mcolors.to_hex(colormap(i)) for i, f in enumerate(set(features.values()))
+        }
+    else:
+        feature_colors = colormap
 
-    features = {node: node[color_by] for node in tree if color_by in node.metadata}
-    feature_colors = {
-        f: mcolors.to_hex(colormap(i)) for i, f in enumerate(set(features.values()))
-    }
     colors = {
         node: feature_colors[features[node]] if node in features else default_color
         for node in tree
@@ -252,10 +301,12 @@ def draw_colored_tree_categorical(
     ax: Axes | None = None,
     backward_time: bool = False,
     default_color: Color = "black",
-    colormap: str | Colormap = "tab20",
+    colormap: str | Mapping[str, Color] | Colormap = "tab20",
     show_legend: bool = True,
-    labels: dict[Any, str] | None = None,
+    labels: Mapping[Any, str] | None = None,
     legend_kwargs: dict[str, Any] | None = None,
+    branch_kwargs: dict[str, Any] | None = None,
+    sampled_ancestor_kwargs: dict[str, Any] | None = None,
 ):
     """
     Draw a phylogenetic tree with branches colored based on categorical metadata.
@@ -272,14 +323,21 @@ def draw_colored_tree_categorical(
         If True, the x-axis is inverted to represent time going backward.
     default_color : Color, optional
         The color to use for nodes without the specified metadata.
-    colormap : str | Colormap, optional
-        The colormap to use for coloring categories. Defaults to 'tab20'.
+    colormap : str | Mapping[str, Color] | Colormap, optional
+        The colormap to use for coloring categories.
+        If a string, it is used to get a matplotlib colormap.
+        If a mapping, it maps category values to colors directly.
+        Defaults to 'tab20'.
     show_legend : bool, optional
         Whether to display a legend for the categories.
-    labels : dict[Any, str] | None, optional
+    labels : Mapping[Any, str] | None, optional
         A mapping from category values to labels for the legend.
     legend_kwargs : dict[str, Any] | None, optional
         Additional keyword arguments to pass to the legend.
+    branch_kwargs : dict[str, Any] | None, optional
+        Additional keyword arguments to pass to the branch drawing functions.
+    sampled_ancestor_kwargs : dict[str, Any] | None, optional
+        Additional keyword arguments to highlight sampled ancestors.
 
     Returns
     -------
@@ -296,7 +354,14 @@ def draw_colored_tree_categorical(
         labels=labels,
         legend_kwargs=legend_kwargs,
     )
-    return draw_tree(tree=tree, ax=ax, colors=colors, backward_time=backward_time)
+    return draw_tree(
+        tree=tree,
+        ax=ax,
+        colors=colors,
+        backward_time=backward_time,
+        branch_kwargs=branch_kwargs,
+        sampled_ancestor_kwargs=sampled_ancestor_kwargs,
+    )
 
 
 def draw_colored_dated_tree_categorical(
@@ -305,10 +370,11 @@ def draw_colored_dated_tree_categorical(
     color_by: str,
     ax: Axes | None = None,
     default_color: Color = "black",
-    colormap: str | Colormap = "tab20",
+    colormap: str | Mapping[str, Color] | Colormap = "tab20",
     show_legend: bool = True,
-    labels: dict[Any, str] | None = None,
+    labels: Mapping[Any, str] | None = None,
     legend_kwargs: dict[str, Any] | None = None,
+    branch_kwargs: dict[str, Any] | None = None,
 ) -> Axes:
     """
     Draw a dated phylogenetic tree with branches colored based on categorical metadata.
@@ -325,14 +391,19 @@ def draw_colored_dated_tree_categorical(
         The matplotlib Axes to draw on. If None, uses the current Axes.
     default_color : Color, optional
         The color to use for nodes without the specified metadata.
-    colormap : str | Colormap, optional
-        The colormap to use for coloring categories. Defaults to 'tab20'.
+    colormap : str | Mapping[str, Color] | Colormap, optional
+        The colormap to use for coloring categories.
+        If a string, it is used to get a matplotlib colormap.
+        If a mapping, it maps category values to colors directly.
+        Defaults to 'tab20'.
     show_legend : bool, optional
         Whether to display a legend for the categories.
-    labels : dict[Any, str] | None, optional
+    labels : Mapping[Any, str] | None, optional
         A mapping from category values to labels for the legend.
     legend_kwargs : dict[str, Any] | None, optional
         Additional keyword arguments to pass to the legend.
+    branch_kwargs : dict[str, Any] | None, optional
+        Additional keyword arguments to pass to the branch drawing functions.
 
     Returns
     -------
@@ -350,7 +421,11 @@ def draw_colored_dated_tree_categorical(
         legend_kwargs=legend_kwargs,
     )
     return draw_dated_tree(
-        tree=tree, calibration_nodes=calibration_nodes, ax=ax, colors=colors
+        tree=tree,
+        calibration_nodes=calibration_nodes,
+        ax=ax,
+        colors=colors,
+        branch_kwargs=branch_kwargs,
     )
 
 
@@ -378,7 +453,7 @@ def _init_colored_tree_continuous(
     vmin: float | None = ...,
     vmax: float | None = ...,
     *,
-    show_hist: Literal[True],
+    show_hist: Literal[True] = True,
     hist_kwargs: dict[str, Any] | None = ...,
     hist_axes_kwargs: dict[str, Any] | None = ...,
 ) -> tuple[Axes, dict[Tree, Color], Axes]: ...
@@ -390,7 +465,6 @@ def _init_colored_tree_continuous(
     colormap: str | Colormap = "viridis",
     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,
@@ -474,6 +548,8 @@ def draw_colored_tree_continuous(
     colormap: str | Colormap = "viridis",
     vmin: float | None = None,
     vmax: float | None = None,
+    branch_kwargs: dict[str, Any] | None = None,
+    sampled_ancestor_kwargs: dict[str, Any] | None = None,
     *,
     show_hist: Literal[False],
     hist_kwargs: dict[str, Any] | None = None,
@@ -489,8 +565,9 @@ def draw_colored_tree_continuous(
     colormap: str | Colormap = "viridis",
     vmin: float | None = None,
     vmax: float | None = None,
-    *,
-    show_hist: Literal[True],
+    branch_kwargs: dict[str, Any] | None = None,
+    sampled_ancestor_kwargs: dict[str, Any] | None = None,
+    show_hist: Literal[True] = True,
     hist_kwargs: dict[str, Any] | None = None,
     hist_axes_kwargs: dict[str, Any] | None = None,
 ) -> tuple[Axes, Axes]: ...
@@ -503,6 +580,8 @@ def draw_colored_tree_continuous(
     colormap: str | Colormap = "viridis",
     vmin: float | None = None,
     vmax: float | None = None,
+    branch_kwargs: dict[str, Any] | None = None,
+    sampled_ancestor_kwargs: dict[str, Any] | None = None,
     show_hist: bool = True,
     hist_kwargs: dict[str, Any] | None = None,
     hist_axes_kwargs: dict[str, Any] | None = None,
@@ -528,6 +607,10 @@ def draw_colored_tree_continuous(
         The minimum value for normalization. If None, uses the minimum of the data.
     vmax : float | None, optional
         The maximum value for normalization. If None, uses the maximum of the data.
+    branch_kwargs : dict[str, Any] | None, optional
+        Additional keyword arguments to pass to the branch drawing functions.
+    sampled_ancestor_kwargs : dict[str, Any] | None, optional
+        Additional keyword arguments to highlight sampled ancestors.
     show_hist : bool, optional
         Whether to display a histogram of the continuous values.
     hist_kwargs : dict[str, Any] | None, optional
@@ -555,7 +638,12 @@ def draw_colored_tree_continuous(
             hist_axes_kwargs=hist_axes_kwargs,
         )
         return draw_tree(
-            tree=tree, ax=ax, colors=colors, backward_time=backward_time
+            tree=tree,
+            ax=ax,
+            colors=colors,
+            backward_time=backward_time,
+            branch_kwargs=branch_kwargs,
+            sampled_ancestor_kwargs=sampled_ancestor_kwargs,
         ), hist_ax
 
     ax, colors = _init_colored_tree_continuous(
@@ -570,7 +658,14 @@ def draw_colored_tree_continuous(
         hist_kwargs=hist_kwargs,
         hist_axes_kwargs=hist_axes_kwargs,
     )
-    return draw_tree(tree=tree, ax=ax, colors=colors, backward_time=backward_time)
+    return draw_tree(
+        tree=tree,
+        ax=ax,
+        colors=colors,
+        backward_time=backward_time,
+        branch_kwargs=branch_kwargs,
+        sampled_ancestor_kwargs=sampled_ancestor_kwargs,
+    )
 
 
 @overload
@@ -583,6 +678,7 @@ def draw_colored_dated_tree_continuous(
     colormap: str | Colormap = "viridis",
     vmin: float | None = None,
     vmax: float | None = None,
+    branch_kwargs: dict[str, Any] | None = None,
     *,
     show_hist: Literal[False],
     hist_kwargs: dict[str, Any] | None = None,
@@ -598,8 +694,8 @@ def draw_colored_dated_tree_continuous(
     colormap: str | Colormap = "viridis",
     vmin: float | None = None,
     vmax: float | None = None,
-    *,
-    show_hist: Literal[True],
+    branch_kwargs: dict[str, Any] | None = None,
+    show_hist: Literal[True] = True,
     hist_kwargs: dict[str, Any] | None = None,
     hist_axes_kwargs: dict[str, Any] | None = None,
 ) -> tuple[Axes, Axes]: ...
@@ -612,6 +708,7 @@ def draw_colored_dated_tree_continuous(
     colormap: str | Colormap = "viridis",
     vmin: float | None = None,
     vmax: float | None = None,
+    branch_kwargs: dict[str, Any] | None = None,
     show_hist: bool = True,
     hist_kwargs: dict[str, Any] | None = None,
     hist_axes_kwargs: dict[str, Any] | None = None,
@@ -637,6 +734,8 @@ def draw_colored_dated_tree_continuous(
         The minimum value for normalization. If None, uses the minimum of the data.
     vmax : float | None, optional
         The maximum value for normalization. If None, uses the maximum of the data.
+    branch_kwargs : dict[str, Any] | None, optional
+        Additional keyword arguments to pass to the branch drawing functions.
     show_hist : bool, optional
         Whether to display a histogram of the continuous values.
     hist_kwargs : dict[str, Any] | None, optional
@@ -668,6 +767,7 @@ def draw_colored_dated_tree_continuous(
             calibration_nodes=calibration_nodes,
             ax=ax,
             colors=colors,
+            branch_kwargs=branch_kwargs,
         ), hist_ax
 
     ax, colors = _init_colored_tree_continuous(
@@ -687,4 +787,5 @@ def draw_colored_dated_tree_continuous(
         calibration_nodes=calibration_nodes,
         ax=ax,
         colors=colors,
+        branch_kwargs=branch_kwargs,
     )

{phylogenie-3.1.7 → phylogenie-3.1.18}/src/phylogenie/generators/factories.py

@@ -19,18 +19,22 @@ from phylogenie.skyline import (
 from phylogenie.treesimulator import EventType, Mutation
 
 
-def _eval_expression(expression: str, data: dict[str, Any]) -> Any:
+def eval_expression(
+    expression: str, data: dict[str, Any], extra_globals: dict[str, Any] | None = None
+) -> Any:
+    if extra_globals is None:
+        extra_globals = {}
     return np.array(
         eval(
             expression,
-            {"np": np, **{k: np.array(v) for k, v in data.items()}},
+            {"np": np, **{k: np.array(v) for k, v in data.items()}, **extra_globals},
         )
     ).tolist()
 
 
 def integer(x: cfg.Integer, data: dict[str, Any]) -> int:
     if isinstance(x, str):
-        e = _eval_expression(x, data)
+        e = eval_expression(x, data)
         if isinstance(e, int):
             return e
         raise ValueError(
@@ -41,7 +45,7 @@ def integer(x: cfg.Integer, data: dict[str, Any]) -> int:
 
 def scalar(x: cfg.Scalar, data: dict[str, Any]) -> pgt.Scalar:
     if isinstance(x, str):
-        e = _eval_expression(x, data)
+        e = eval_expression(x, data)
         if isinstance(e, pgt.Scalar):
             return e
         raise ValueError(
@@ -54,13 +58,13 @@ def string(s: Any, data: dict[str, Any]) -> str:
     if not isinstance(s, str):
         return str(s)
     return re.sub(
-        r"\{([^{}]+)\}", lambda match: str(_eval_expression(match.group(1), data)), s
+        r"\{([^{}]+)\}", lambda match: str(eval_expression(match.group(1), data)), s
     )  # Match content inside curly braces
 
 
 def many_scalars(x: cfg.ManyScalars, data: dict[str, Any]) -> pgt.ManyScalars:
     if isinstance(x, str):
-        e = _eval_expression(x, data)
+        e = eval_expression(x, data)
         if tg.is_many_scalars(e):
             return e
         raise ValueError(
@@ -73,7 +77,7 @@ def one_or_many_scalars(
     x: cfg.OneOrManyScalars, data: dict[str, Any]
 ) -> pgt.OneOrManyScalars:
     if isinstance(x, str):
-        e = _eval_expression(x, data)
+        e = eval_expression(x, data)
         if tg.is_one_or_many_scalars(e):
             return e
         raise ValueError(
@@ -99,7 +103,7 @@ def skyline_vector(
     x: cfg.SkylineVector, data: dict[str, Any]
 ) -> SkylineVectorCoercible:
     if isinstance(x, str):
-        e = _eval_expression(x, data)
+        e = eval_expression(x, data)
         if tg.is_one_or_many_scalars(e):
             return e
         raise ValueError(
@@ -114,7 +118,7 @@ def skyline_vector(
 
     change_times = many_scalars(x.change_times, data)
     if isinstance(x.value, str):
-        e = _eval_expression(x.value, data)
+        e = eval_expression(x.value, data)
         if tg.is_many_one_or_many_scalars(e):
             value = e
         else:
@@ -142,7 +146,7 @@ def one_or_many_2D_scalars(
     x: cfg.OneOrMany2DScalars, data: dict[str, Any]
 ) -> pgt.OneOrMany2DScalars:
     if isinstance(x, str):
-        e = _eval_expression(x, data)
+        e = eval_expression(x, data)
         if tg.is_one_or_many_2D_scalars(e):
             return e
         raise ValueError(
@@ -160,7 +164,7 @@ def skyline_matrix(
         return None
 
     if isinstance(x, str):
-        e = _eval_expression(x, data)
+        e = eval_expression(x, data)
         if tg.is_one_or_many_2D_scalars(e):
             return e
         raise ValueError(
@@ -175,7 +179,7 @@ def skyline_matrix(
 
     change_times = many_scalars(x.change_times, data)
     if isinstance(x.value, str):
-        e = _eval_expression(x.value, data)
+        e = eval_expression(x.value, data)
         if tg.is_many_one_or_many_2D_scalars(e):
             value = e
         else:
@@ -213,7 +217,7 @@ def distribution(x: cfg.Distribution, data: dict[str, Any]) -> cfg.Distribution:
     args = x.args
     for arg_name, arg_value in args.items():
         if isinstance(arg_value, str):
-            args[arg_name] = _eval_expression(arg_value, data)
+            args[arg_name] = eval_expression(arg_value, data)
     return cfg.Distribution(type=x.type, **args)
 
 

{phylogenie-3.1.7 → phylogenie-3.1.18}/src/phylogenie/generators/trees.py

@@ -12,6 +12,7 @@ from phylogenie.generators.configs import Distribution
 from phylogenie.generators.dataset import DatasetGenerator, DataType
 from phylogenie.generators.factories import (
     data,
+    eval_expression,
     integer,
     mutations,
     scalar,
@@ -57,6 +58,7 @@ class TreeDatasetGenerator(DatasetGenerator):
     timeout: float = np.inf
     node_features: list[Feature] | None = None
     acceptance_criterion: str | None = None
+    logs: dict[str, str] | None = None
 
     @abstractmethod
     def _get_events(self, data: dict[str, Any]) -> list[Event]: ...
@@ -77,10 +79,21 @@ class TreeDatasetGenerator(DatasetGenerator):
         acceptance_criterion: None | Callable[[Tree], bool] = (
             None
             if self.acceptance_criterion is None
-            else lambda tree: eval(
-                self.acceptance_criterion, {}, {"tree": tree}  # pyright: ignore
+            else lambda tree: eval_expression(
+                self.acceptance_criterion,  # pyright: ignore
+                data,
+                {"tree": tree},
             )
         )
+        logs: None | dict[str, Callable[[Tree], Any]] = (
+            None
+            if self.logs is None
+            else {
+                key: lambda tree, expr=expr: eval_expression(expr, data, {"tree": tree})
+                for key, expr in self.logs.items()
+            }
+        )
+
         return simulate_tree(
             events=events,
             n_tips=None if self.n_tips is None else integer(self.n_tips, data),
@@ -92,6 +105,7 @@ class TreeDatasetGenerator(DatasetGenerator):
             seed=seed,
             timeout=self.timeout,
             acceptance_criterion=acceptance_criterion,
+            logs=logs,
         )
 
     def generate_one(
@@ -111,7 +125,7 @@ class TreeDatasetGenerator(DatasetGenerator):
                 dump_newick(tree, f"{filename}.nwk")
                 break
             except TimeoutError:
-                print("Simulation timed out, retrying with different parameters...")
+                print("Simulation timed out. Retrying with different parameters...")
         return d | metadata
 
 

{phylogenie-3.1.7 → phylogenie-3.1.18}/src/phylogenie/io/fasta.py

@@ -1,3 +1,4 @@
+from datetime import date
 from pathlib import Path
 from typing import Callable
 
@@ -5,7 +6,8 @@ from phylogenie.msa import MSA, Sequence
 
 
 def load_fasta(
-    fasta_file: str | Path, extract_time_from_id: Callable[[str], float] | None = None
+    fasta_file: str | Path,
+    extract_time_from_id: Callable[[str], float | date] | None = None,
 ) -> MSA:
     sequences: list[Sequence] = []
     with open(fasta_file, "r") as f:
@@ -17,10 +19,14 @@ def load_fasta(
             if extract_time_from_id is not None:
                 time = extract_time_from_id(id)
             elif "|" in id:
+                last_metadata = id.split("|")[-1]
                 try:
-                    time = float(id.split("|")[-1])
+                    time = float(last_metadata)
                 except ValueError:
-                    pass
+                    try:
+                        time = date.fromisoformat(last_metadata)
+                    except ValueError:
+                        pass
             chars = next(f).strip()
             sequences.append(Sequence(id, chars, time))
     return MSA(sequences)

{phylogenie-3.1.7 → phylogenie-3.1.18}/src/phylogenie/msa.py

@@ -1,5 +1,6 @@
-from collections.abc import Iterator
+from collections.abc import Iterable, Iterator
 from dataclasses import dataclass
+from datetime import date
 
 import numpy as np
 
@@ -8,25 +9,32 @@ import numpy as np
 class Sequence:
     id: str
     chars: str
-    time: float | None = None
+    time: float | date | None = None
+
+    def __len__(self) -> int:
+        return len(self.chars)
 
 
 class MSA:
-    def __init__(self, sequences: list[Sequence]):
-        self.sequences = sequences
-        lengths = {len(sequence.chars) for sequence in sequences}
+    def __init__(self, sequences: Iterable[Sequence]):
+        self._sequences = sequences
+        lengths = {len(sequence) for sequence in sequences}
         if len(lengths) > 1:
             raise ValueError(
                 f"All sequences in the alignment must have the same length (got lengths: {lengths})"
             )
 
+    @property
+    def sequences(self) -> tuple[Sequence, ...]:
+        return tuple(self._sequences)
+
     @property
     def ids(self) -> list[str]:
         return [sequence.id for sequence in self.sequences]
 
     @property
-    def times(self) -> list[float]:
-        times: list[float] = []
+    def times(self) -> list[float | date]:
+        times: list[float | date] = []
         for sequence in self:
             if sequence.time is None:
                 raise ValueError(f"Time is not set for sequence {sequence.id}.")

{phylogenie-3.1.7 → phylogenie-3.1.18}/src/phylogenie/treesimulator/__init__.py

@@ -25,13 +25,17 @@ from phylogenie.treesimulator.tree import Tree
 from phylogenie.treesimulator.utils import (
     compute_mean_leaf_pairwise_distance,
     compute_sackin_index,
+    count_hops,
     get_distance,
     get_mrca,
+    get_node_ages,
     get_node_depth_levels,
     get_node_depths,
     get_node_height_levels,
     get_node_heights,
     get_node_leaf_counts,
+    get_node_times,
+    get_path,
 )
 
 __all__ = [
@@ -63,11 +67,15 @@ __all__ = [
     "Tree",
     "compute_mean_leaf_pairwise_distance",
     "compute_sackin_index",
+    "count_hops",
     "get_distance",
     "get_mrca",
+    "get_node_ages",
     "get_node_depth_levels",
     "get_node_depths",
     "get_node_height_levels",
     "get_node_heights",
     "get_node_leaf_counts",
+    "get_node_times",
+    "get_path",
 ]

{phylogenie-3.1.7 → phylogenie-3.1.18}/src/phylogenie/treesimulator/features.py

@@ -5,11 +5,13 @@ from phylogenie.treesimulator.events.mutations import get_mutation_id
 from phylogenie.treesimulator.model import get_node_state
 from phylogenie.treesimulator.tree import Tree
 from phylogenie.treesimulator.utils import (
+    get_node_ages,
     get_node_depth_levels,
     get_node_depths,
     get_node_height_levels,
     get_node_heights,
     get_node_leaf_counts,
+    get_node_times,
 )
 
 
@@ -22,6 +24,7 @@ def _get_mutations(tree: Tree) -> dict[Tree, int]:
 
 
 class Feature(str, Enum):
+    AGE = "age"
     DEPTH = "depth"
     DEPTH_LEVEL = "depth_level"
     HEIGHT = "height"
@@ -29,9 +32,11 @@ class Feature(str, Enum):
     MUTATION = "mutation"
     N_LEAVES = "n_leaves"
     STATE = "state"
+    TIME = "time"
 
 
 FEATURES_EXTRACTORS = {
+    Feature.AGE: get_node_ages,
     Feature.DEPTH: get_node_depths,
     Feature.DEPTH_LEVEL: get_node_depth_levels,
     Feature.HEIGHT: get_node_heights,
@@ -39,6 +44,7 @@ FEATURES_EXTRACTORS = {
     Feature.MUTATION: _get_mutations,
     Feature.N_LEAVES: get_node_leaf_counts,
     Feature.STATE: _get_states,
+    Feature.TIME: get_node_times,
 }
 
 

{phylogenie-3.1.7 → phylogenie-3.1.18}/src/phylogenie/treesimulator/gillespie.py

@@ -25,6 +25,7 @@ def simulate_tree(
     seed: int | None = None,
     timeout: float = np.inf,
     acceptance_criterion: Callable[[Tree], bool] | None = None,
+    logs: dict[str, Callable[[Tree], Any]] | None = None,
 ) -> tuple[Tree, dict[str, Any]]:
     if (max_time != np.inf) == (n_tips is not None):
         raise ValueError("Exactly one of max_time or n_tips must be specified.")
@@ -85,7 +86,13 @@ def simulate_tree(
                 model.sample(individual, current_time, True)
 
         tree = model.get_sampled_tree()
-        if acceptance_criterion is None or acceptance_criterion(tree):
+
+        if acceptance_criterion is not None and not acceptance_criterion(tree):
+            continue
+
+        if logs is not None:
+            for key, func in logs.items():
+                metadata[key] = func(tree)
             return (tree, metadata)
 
 
@@ -102,6 +109,7 @@ def generate_trees(
     n_jobs: int = -1,
     timeout: float = np.inf,
     acceptance_criterion: Callable[[Tree], bool] | None = None,
+    logs: dict[str, Callable[[Tree], Any]] | None = None,
 ) -> pd.DataFrame:
     if isinstance(output_dir, str):
         output_dir = Path(output_dir)
@@ -121,6 +129,7 @@ def generate_trees(
                     seed=seed,
                     timeout=timeout,
                     acceptance_criterion=acceptance_criterion,
+                    logs=logs,
                 )
                 metadata["file_id"] = i
                 if node_features is not None:
@@ -128,7 +137,7 @@ def generate_trees(
                 dump_newick(tree, output_dir / f"{i}.nwk")
                 return metadata
             except TimeoutError:
-                print("Simulation timed out, retrying with a different seed...")
+                print("Simulation timed out. Retrying with a different seed...")
             seed += 1
 
     rng = default_rng(seed)

{phylogenie-3.1.7 → phylogenie-3.1.18}/src/phylogenie/treesimulator/tree.py

@@ -153,6 +153,16 @@ class Tree(MetadataMixin):
             child.branch_length_or_raise() + child.height for child in self.children
         )
 
+    @property
+    def time(self) -> float:
+        return self.depth
+
+    @property
+    def age(self) -> float:
+        if self.parent is None:
+            return self.height
+        return self.parent.age - self.branch_length_or_raise()
+
     # -------------
     # Miscellaneous
     # -------------

{phylogenie-3.1.7 → phylogenie-3.1.18}/src/phylogenie/treesimulator/utils.py

@@ -51,6 +51,17 @@ def get_node_heights(tree: Tree) -> dict[Tree, float]:
     return heights
 
 
+def get_node_times(tree: Tree) -> dict[Tree, float]:
+    return get_node_depths(tree)
+
+
+def get_node_ages(tree: Tree) -> dict[Tree, float]:
+    ages: dict[Tree, float] = {tree: tree.height}
+    for node in tree.iter_descendants():
+        ages[node] = ages[node.parent] - node.branch_length  # pyright: ignore
+    return ages
+
+
 def get_mrca(node1: Tree, node2: Tree) -> Tree:
     node1_ancestors = set(node1.iter_upward())
     for node2_ancestor in node2.iter_upward():

{phylogenie-3.1.7 → phylogenie-3.1.18/src/phylogenie.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phylogenie
-Version: 3.1.7
+Version: 3.1.18
 Summary: Generate phylogenetic datasets with minimal setup effort
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -23,7 +23,6 @@ Dynamic: license-file
 [![PyPI version](https://img.shields.io/pypi/v/phylogenie)](https://pypi.org/project/phylogenie/)
 ![Downloads](https://img.shields.io/pypi/dm/phylogenie)
 
-
 Phylogenie is a [Python](https://www.python.org/) package designed to easily simulate phylogenetic datasets—such as trees and multiple sequence alignments (MSAs)—with minimal setup effort. Simply specify the distributions from which your parameters should be sampled, and Phylogenie will handle the rest!
 
 ## ✨ Features
@@ -73,21 +72,21 @@ Phylogenie relies on [AliSim](https://iqtree.github.io/doc/AliSim) for simulatin
 
 ## 🚀 Quick Start
 
-Once you have installed Phylogenie, check out the [examples](https://github.com/gabriele-marino/phylogenie/tree/main/examples) folder.  
+Once you have installed Phylogenie, check out the [tutorials](https://github.com/gabriele-marino/phylogenie/tree/main/tutorials) folder.  
 It includes a collection of thoroughly commented configuration files, organized as a step-by-step tutorial. These examples will help you understand how to use Phylogenie in practice and can be easily adapted to fit your own workflow.
 
 For quick start, pick your favorite config file and run Phylogenie with:
 ```bash
-phylogenie examples/config_file.yaml
+phylogenie tutorials/config_file.yaml
 ```
 This command will create the output dataset in the folder specified inside the configuration file, including data directories and metadata files for each dataset split defined in the config.
 
 >❗ *Tip*: Can’t choose just one config file?
-You can run them all at once by pointing Phylogenie to the folder! Just use: `phylogenie examples`. In this mode, Phylogenie will automatically find all `.yaml` files in the folder you specified and run for each of them!
+You can run them all at once by pointing Phylogenie to the folder! Just use: `phylogenie tutorials`. In this mode, Phylogenie will automatically find all `.yaml` files in the folder you specified and run for each of them!
 
 ## 📖 Documentation
 
-- The [examples](https://github.com/gabriele-marino/phylogenie/tree/main/examples) folder contains many ready-to-use, extensively commented configuration files that serve as a step-by-step tutorial to guide you through using Phylogenie. You can explore them to learn how it works or adapt them directly to your own workflows.
+- The [tutorials](https://github.com/gabriele-marino/phylogenie/tree/main/tutorials) folder contains many ready-to-use, extensively commented configuration files that serve as a step-by-step tutorial to guide you through using Phylogenie. You can explore them to learn how it works or adapt them directly to your own workflows.
 - A complete user guide and API reference are under development. In the meantime, feel free to [reach out](mailto:gabmarino.8601@email.com) if you have any questions about integrating Phylogenie into your workflows.
 
 ## 📄 License