phykit 2.1.26__tar.gz → 2.1.27__tar.gz

{phykit-2.1.26 → phykit-2.1.27}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: phykit
-Version: 2.1.26
+Version: 2.1.27
 Home-page: https://github.com/jlsteenwyk/phykit
 Author: Jacob L. Steenwyk
 Author-email: jlsteenwyk@gmail.com

{phykit-2.1.26 → phykit-2.1.27}/phykit/cli_registry.py

@@ -112,6 +112,9 @@ ALIAS_TO_HANDLER: Dict[str, str] = {
     "quartet_net": "quartet_network",
     "qnet": "quartet_network",
     "nanuq": "quartet_network",
+    "ltt": "ltt",
+    "gamma_stat": "ltt",
+    "gamma": "ltt",
     "netsig": "network_signal",
     "net_signal": "network_signal",
     "rrt": "relative_rate_test",

{phykit-2.1.26 → phykit-2.1.27}/phykit/phykit.py

@@ -235,6 +235,9 @@ class Phykit:
                 quartet_network (alias: quartet_net; qnet; nanuq)
                     - quartet-based network inference (NANUQ-style)
                       distinguishing ILS from hybridization
+                ltt (alias: gamma_stat; gamma)
+                    - lineage-through-time plot and Pybus & Harvey
+                      gamma statistic for diversification rate testing
                 network_signal (alias: netsig; net_signal)
                     - phylogenetic signal on a network
                 polytomy_test (alias: polyt_test; polyt; ptt)
@@ -3834,6 +3837,65 @@ class Phykit:
         _add_json_argument(parser)
         _run_service(parser, argv, NetworkSignal)
 
+    @staticmethod
+    def ltt(argv):
+        parser = _new_parser(
+            description=textwrap.dedent(
+                f"""\
+                {help_header}
+
+                Lineage-through-time plot and gamma statistic.
+
+                Computes the Pybus & Harvey (2000) gamma statistic
+                to test for temporal variation in diversification
+                rates.  Under a constant-rate pure-birth process,
+                gamma ~ N(0,1).  Negative values indicate early
+                diversification (decelerating); positive values
+                indicate late diversification (accelerating).
+
+                Optionally generates a lineage-through-time plot.
+
+                Aliases:
+                  ltt, gamma_stat, gamma
+                Command line interfaces:
+                  pk_ltt, pk_gamma_stat, pk_gamma
+
+                Usage:
+                phykit ltt -t <tree> [-v/--verbose]
+                    [--plot-output <file>] [--json]
+
+                Options
+                =====================================================
+                -t/--tree                   a rooted phylogeny file
+                                            with branch lengths
+                                            (required)
+
+                -v/--verbose                print branching times
+                                            and LTT data points
+
+                --plot-output               output filename for the
+                                            lineage-through-time
+                                            plot (optional)
+
+                --json                      optional argument to output
+                                            results as JSON
+                """
+            ),
+        )
+        parser.add_argument("-t", "--tree", type=str, required=True, help=SUPPRESS)
+        parser.add_argument(
+            "-v", "--verbose", action="store_true", required=False, help=SUPPRESS
+        )
+        parser.add_argument(
+            "--plot-output",
+            type=str,
+            default=None,
+            required=False,
+            help=SUPPRESS,
+        )
+        _add_json_argument(parser)
+        _run_service(parser, argv, LTT)
+
     @staticmethod
     def prune_tree(argv):
         parser = _new_parser(
@@ -4926,6 +4988,10 @@ def quartet_network(argv=None):
     Phykit.quartet_network(sys.argv[1:])
 
 
+def ltt(argv=None):
+    Phykit.ltt(sys.argv[1:])
+
+
 def network_signal(argv=None):
     Phykit.network_signal(sys.argv[1:])
 

{phykit-2.1.26 → phykit-2.1.27}/phykit/service_factories.py

@@ -77,6 +77,7 @@ OUwie = _LazyServiceFactory("phykit.services.tree.ouwie", "OUwie")
 OUShiftDetection = _LazyServiceFactory("phykit.services.tree.ou_shift_detection", "OUShiftDetection")
 QuartetNetwork = _LazyServiceFactory("phykit.services.tree.quartet_network", "QuartetNetwork")
 NetworkSignal = _LazyServiceFactory("phykit.services.tree.network_signal", "NetworkSignal")
+LTT = _LazyServiceFactory("phykit.services.tree.ltt", "LTT")
 RelativeRateTest = _LazyServiceFactory("phykit.services.tree.relative_rate_test", "RelativeRateTest")
 PolytomyTest = _LazyServiceFactory("phykit.services.tree.polytomy_test", "PolytomyTest")
 PrintTree = _LazyServiceFactory("phykit.services.tree.print_tree", "PrintTree")

{phykit-2.1.26 → phykit-2.1.27}/phykit/services/tree/__init__.py

@@ -15,6 +15,7 @@ _EXPORTS = {
     "InternodeLabeler": "internode_labeler",
     "LastCommonAncestorSubtree": "last_common_ancestor_subtree",
     "LBScore": "lb_score",
+    "LTT": "ltt",
     "MonophylyCheck": "monophyly_check",
     "NearestNeighborInterchange": "nearest_neighbor_interchange",
     "PatristicDistances": "patristic_distances",

phykit-2.1.27/phykit/services/tree/ltt.py

@@ -0,0 +1,217 @@
+import math
+from typing import Dict, List, Tuple
+
+from .base import Tree
+from ...helpers.json_output import print_json
+from ...errors import PhykitUserError
+
+
+class LTT(Tree):
+    def __init__(self, args) -> None:
+        parsed = self.process_args(args)
+        super().__init__(tree_file_path=parsed["tree_file_path"])
+        self.verbose = parsed["verbose"]
+        self.json_output = parsed["json_output"]
+        self.plot_output = parsed["plot_output"]
+
+    def run(self) -> None:
+        tree = self.read_tree_file()
+        self._validate_tree(tree)
+
+        gamma, p_value, bt, g = self._compute_gamma(tree)
+        ltt_data = self._compute_ltt(tree)
+
+        if self.json_output:
+            self._output_json(gamma, p_value, ltt_data, bt, g)
+            return
+
+        self._output_text(gamma, p_value, ltt_data, bt, g)
+
+        if self.plot_output:
+            self._plot_ltt(ltt_data, self.plot_output, gamma=gamma, p_value=p_value)
+
+    def process_args(self, args) -> Dict[str, str]:
+        return dict(
+            tree_file_path=args.tree,
+            verbose=getattr(args, "verbose", False),
+            json_output=getattr(args, "json", False),
+            plot_output=getattr(args, "plot_output", None),
+        )
+
+    def _validate_tree(self, tree) -> None:
+        tips = list(tree.get_terminals())
+        if len(tips) < 3:
+            raise PhykitUserError(
+                ["Tree must have at least 3 tips for gamma statistic."],
+                code=2,
+            )
+        for clade in tree.find_clades():
+            if clade.branch_length is None and clade != tree.root:
+                raise PhykitUserError(
+                    ["All branches in the tree must have lengths."],
+                    code=2,
+                )
+
+    @staticmethod
+    def _compute_gamma(tree):
+        """Pybus & Harvey (2000) gamma statistic, matching ape::gammaStat().
+
+        Replicates the exact algorithm from R's ape source (gammaStat.R):
+            N <- length(phy$tip.label)
+            bt <- sort(branching.times(phy))
+            g <- rev(c(bt[1], diff(bt)))
+            ST <- sum((2:N) * g)
+            stat <- sum(cumsum((2:(N-1)) * g[-(N-1)])) / (N-2)
+            m <- ST / 2
+            s <- ST * sqrt(1 / (12 * (N - 2)))
+            (stat - m) / s
+        """
+        tips = list(tree.get_terminals())
+        N = len(tips)
+
+        if N < 3:
+            raise PhykitUserError(
+                ["Tree must have at least 3 tips for gamma statistic."],
+                code=2,
+            )
+
+        # Get branching times (node ages = distance from present/tips)
+        root = tree.root
+        max_height = max(tree.distance(root, tip) for tip in tips)
+
+        bt = []
+        for clade in tree.find_clades(order="level"):
+            if clade.is_terminal():
+                continue
+            node_dist_from_root = tree.distance(root, clade)
+            node_age = max_height - node_dist_from_root
+            bt.append(node_age)
+
+        bt.sort()  # ascending: most recent nodes first
+
+        # Internode intervals reversed (ape: g <- rev(c(bt[1], diff(bt))))
+        # This orders intervals from past to present (root interval first)
+        g_unreversed = [bt[0]] + [bt[i] - bt[i - 1] for i in range(1, len(bt))]
+        g = list(reversed(g_unreversed))
+
+        # ST = sum((2:N) * g)
+        ST = sum((k + 2) * g[k] for k in range(N - 1))
+
+        # stat = sum(cumsum((2:(N-1)) * g[-(N-1)])) / (N-2)
+        # g[-(N-1)] in R removes the last element
+        g_partial = g[:-1]
+        partial = [(k + 2) * g_partial[k] for k in range(N - 2)]
+        cumsum_partial = []
+        running = 0.0
+        for val in partial:
+            running += val
+            cumsum_partial.append(running)
+
+        stat = sum(cumsum_partial) / (N - 2)
+
+        m = ST / 2
+        s = ST * math.sqrt(1.0 / (12 * (N - 2)))
+        gamma = (stat - m) / s
+
+        # Two-tailed p-value from standard normal
+        from scipy.stats import norm
+
+        p_value = 2 * norm.sf(abs(gamma))
+
+        return gamma, p_value, bt, g
+
+    @staticmethod
+    def _compute_ltt(tree):
+        """Compute lineage-through-time data.
+
+        Returns list of (time_from_root, n_lineages) tuples.
+        Time runs from 0 (root) to tree_height (present).
+        """
+        # Get branching times as distances from root
+        root = tree.root
+        max_height = max(
+            tree.distance(root, tip) for tip in tree.get_terminals()
+        )
+
+        branching_times_from_root = []
+        for clade in tree.find_clades(order="level"):
+            if clade.is_terminal():
+                continue
+            if clade == root:
+                continue
+            branching_times_from_root.append(tree.distance(root, clade))
+
+        branching_times_from_root.sort()
+
+        # LTT: start with 2 lineages at root (time=0)
+        ltt = [(0.0, 2)]
+        n_lineages = 2
+        for bt in branching_times_from_root:
+            n_lineages += 1
+            ltt.append((bt, n_lineages))
+        # End at present
+        ltt.append((max_height, n_lineages))
+
+        return ltt
+
+    @staticmethod
+    def _plot_ltt(ltt_data, output_path, gamma=None, p_value=None):
+        """Plot lineage-through-time as a step function."""
+        import matplotlib
+
+        matplotlib.use("Agg")
+        import matplotlib.pyplot as plt
+
+        times = [pt[0] for pt in ltt_data]
+        lineages = [pt[1] for pt in ltt_data]
+
+        fig, ax = plt.subplots(figsize=(8, 5))
+        ax.step(times, lineages, where="post", linewidth=2, color="black")
+        ax.set_xlabel("Time from root", fontsize=12)
+        ax.set_ylabel("Number of lineages", fontsize=12)
+        ax.set_yscale("log")
+
+        if gamma is not None:
+            label = f"\u03b3 = {gamma:.4f}"
+            if p_value is not None:
+                label += f" (p = {p_value:.4e})"
+            ax.text(
+                0.05,
+                0.95,
+                label,
+                transform=ax.transAxes,
+                fontsize=11,
+                verticalalignment="top",
+                bbox=dict(boxstyle="round", facecolor="wheat", alpha=0.8),
+            )
+
+        fig.tight_layout()
+        fig.savefig(output_path, dpi=300, bbox_inches="tight")
+        plt.close(fig)
+
+    def _output_text(self, gamma, p_value, ltt_data, bt, g):
+        try:
+            print(f"{round(gamma, 4)}\t{round(p_value, 4)}")
+            if self.verbose:
+                print("\nBranching times (node ages):")
+                for i, t in enumerate(bt):
+                    print(f"  {i + 1}\t{t:.6f}")
+                print("\nLineage-through-time:")
+                print("  time_from_root\tn_lineages")
+                for time_val, n_lin in ltt_data:
+                    print(f"  {time_val:.6f}\t{n_lin}")
+        except BrokenPipeError:
+            pass
+
+    def _output_json(self, gamma, p_value, ltt_data, bt, g):
+        result = dict(
+            gamma=float(gamma),
+            p_value=float(p_value),
+            branching_times=[float(t) for t in bt],
+            internode_intervals=[float(v) for v in g],
+            ltt=[
+                dict(time_from_root=float(t), n_lineages=int(n))
+                for t, n in ltt_data
+            ],
+        )
+        print_json(result)

phykit-2.1.27/phykit/version.py

@@ -0,0 +1 @@
+__version__ = "2.1.27"

{phykit-2.1.26 → phykit-2.1.27}/phykit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: phykit
-Version: 2.1.26
+Version: 2.1.27
 Home-page: https://github.com/jlsteenwyk/phykit
 Author: Jacob L. Steenwyk
 Author-email: jlsteenwyk@gmail.com

{phykit-2.1.26 → phykit-2.1.27}/phykit.egg-info/SOURCES.txt

@@ -69,6 +69,7 @@ phykit/services/tree/internal_branch_stats.py
 phykit/services/tree/internode_labeler.py
 phykit/services/tree/last_common_ancestor_subtree.py
 phykit/services/tree/lb_score.py
+phykit/services/tree/ltt.py
 phykit/services/tree/monophyly_check.py
 phykit/services/tree/nearest_neighbor_interchange.py
 phykit/services/tree/network_signal.py

{phykit-2.1.26 → phykit-2.1.27}/phykit.egg-info/entry_points.txt

@@ -64,6 +64,8 @@ pk_fc = phykit.phykit:fit_continuous
 pk_fit_continuous = phykit.phykit:fit_continuous
 pk_fit_ouwie = phykit.phykit:ouwie
 pk_fitcontinuous = phykit.phykit:fit_continuous
+pk_gamma = phykit.phykit:ltt
+pk_gamma_stat = phykit.phykit:ltt
 pk_gc = phykit.phykit:gc_content
 pk_gc_content = phykit.phykit:gc_content
 pk_ge = phykit.phykit:faidx
@@ -81,6 +83,7 @@ pk_lb_score = phykit.phykit:lb_score
 pk_lbs = phykit.phykit:lb_score
 pk_lca_subtree = phykit.phykit:last_common_ancestor_subtree
 pk_long_branch_score = phykit.phykit:lb_score
+pk_ltt = phykit.phykit:ltt
 pk_mask = phykit.phykit:mask_alignment
 pk_mask_alignment = phykit.phykit:mask_alignment
 pk_mask_aln = phykit.phykit:mask_alignment

{phykit-2.1.26 → phykit-2.1.27}/setup.py

@@ -196,6 +196,9 @@ setup(
             "pk_quartet_net = phykit.phykit:quartet_network",
             "pk_qnet = phykit.phykit:quartet_network",
             "pk_nanuq = phykit.phykit:quartet_network",
+            "pk_ltt = phykit.phykit:ltt",
+            "pk_gamma_stat = phykit.phykit:ltt",
+            "pk_gamma = phykit.phykit:ltt",
             "pk_network_signal = phykit.phykit:network_signal",
             "pk_netsig = phykit.phykit:network_signal",
             "pk_net_signal = phykit.phykit:network_signal",

phykit-2.1.26/phykit/version.py

@@ -1 +0,0 @@
-__version__ = "2.1.26"