phykit 2.1.85__tar.gz → 2.1.88__tar.gz

{phykit-2.1.85 → phykit-2.1.88}/PKG-INFO

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

{phykit-2.1.85 → phykit-2.1.88}/phykit/cli_registry.py

@@ -70,6 +70,9 @@ ALIAS_TO_HANDLER: Dict[str, str] = {
     "blm": "branch_length_multiplier",
     "collapse": "collapse_branches",
     "cb": "collapse_branches",
+    "chronogram": "chronogram",
+    "chrono": "chronogram",
+    "time_tree": "chronogram",
     "cover": "covarying_evolutionary_rates",
     "consnet": "consensus_network",
     "splitnet": "consensus_network",

phykit-2.1.88/phykit/helpers/geological_timescale.py

@@ -0,0 +1,119 @@
+"""
+Geological timescale data (ICS 2024).
+
+Provides era, period, and epoch boundaries for plotting chronograms
+with geological time bands.
+"""
+
+# Muted pastel color palette for geological epochs
+# Inspired by ICS colors but softened for publication figures
+EPOCH_COLORS = {
+    "Holocene": "#FEF2CC",
+    "Pleistocene": "#FFF2AE",
+    "Pliocene": "#FFFF99",
+    "Miocene": "#FFFF00",
+    "Oligocene": "#FDC07A",
+    "Eocene": "#FDB46C",
+    "Paleocene": "#FDA75F",
+    "Late Cretaceous": "#A6D84A",
+    "Early Cretaceous": "#8CCD57",
+    "Late Jurassic": "#B3E1EB",
+    "Middle Jurassic": "#80CFD8",
+    "Early Jurassic": "#42B2D0",
+    "Late Triassic": "#BD8CC2",
+    "Middle Triassic": "#B07FB7",
+    "Early Triassic": "#A372AB",
+}
+
+PERIOD_COLORS = {
+    "Quaternary": "#F9F97F",
+    "Neogene": "#FFE619",
+    "Paleogene": "#FD9A52",
+    "Cretaceous": "#7FC64E",
+    "Jurassic": "#34B2C9",
+    "Triassic": "#812B92",
+    "Permian": "#F04028",
+    "Carboniferous": "#67A599",
+    "Devonian": "#CB8C37",
+    "Silurian": "#B3E1B6",
+    "Ordovician": "#009270",
+    "Cambrian": "#7FA056",
+}
+
+ERA_COLORS = {
+    "Cenozoic": "#F2F91D",
+    "Mesozoic": "#67C5CA",
+    "Paleozoic": "#99C08D",
+}
+
+EPOCHS = [
+    ("Holocene", 0.0117, 0),
+    ("Pleistocene", 2.58, 0.0117),
+    ("Pliocene", 5.333, 2.58),
+    ("Miocene", 23.03, 5.333),
+    ("Oligocene", 33.9, 23.03),
+    ("Eocene", 56.0, 33.9),
+    ("Paleocene", 66.0, 56.0),
+    ("Late Cretaceous", 100.5, 66.0),
+    ("Early Cretaceous", 145.0, 100.5),
+    ("Late Jurassic", 163.5, 145.0),
+    ("Middle Jurassic", 174.7, 163.5),
+    ("Early Jurassic", 201.4, 174.7),
+    ("Late Triassic", 237.0, 201.4),
+    ("Middle Triassic", 247.2, 237.0),
+    ("Early Triassic", 251.902, 247.2),
+]
+
+PERIODS = [
+    ("Quaternary", 2.58, 0),
+    ("Neogene", 23.03, 2.58),
+    ("Paleogene", 66.0, 23.03),
+    ("Cretaceous", 145.0, 66.0),
+    ("Jurassic", 201.4, 145.0),
+    ("Triassic", 251.902, 201.4),
+    ("Permian", 298.9, 251.902),
+    ("Carboniferous", 358.9, 298.9),
+    ("Devonian", 419.2, 358.9),
+    ("Silurian", 443.8, 419.2),
+    ("Ordovician", 485.4, 443.8),
+    ("Cambrian", 538.8, 485.4),
+]
+
+ERAS = [
+    ("Cenozoic", 66.0, 0),
+    ("Mesozoic", 251.902, 66.0),
+    ("Paleozoic", 538.8, 251.902),
+]
+
+
+def get_timescale_for_range(root_age, level="auto"):
+    """Return appropriate timescale intervals for a given root age.
+
+    Parameters
+    ----------
+    root_age : float, Ma
+    level : "epoch", "period", "era", or "auto"
+
+    Returns
+    -------
+    list of (name, start_ma, end_ma), color_dict
+    """
+    if level == "auto":
+        if root_age <= 66:
+            level = "epoch"
+        elif root_age <= 252:
+            level = "period"
+        else:
+            level = "era"
+
+    if level == "epoch":
+        intervals = [(n, s, e) for n, s, e in EPOCHS if s > 0 and e < root_age * 1.1]
+        # Include any epoch that overlaps the tree's range
+        intervals = [(n, s, e) for n, s, e in EPOCHS if e < root_age * 1.05]
+        return intervals, EPOCH_COLORS
+    elif level == "period":
+        intervals = [(n, s, e) for n, s, e in PERIODS if e < root_age * 1.05]
+        return intervals, PERIOD_COLORS
+    else:
+        intervals = [(n, s, e) for n, s, e in ERAS if e < root_age * 1.05]
+        return intervals, ERA_COLORS

{phykit-2.1.85 → phykit-2.1.88}/phykit/phykit.py

@@ -192,6 +192,8 @@ class Phykit:
                 concordance_asr (alias: conc_asr; casr)
                     - concordance-aware ancestral state reconstruction
                       incorporating gene tree discordance
+                chronogram (alias: chrono; time_tree)
+                    - plot a time-calibrated tree with geological timescale
                 bipartition_support_stats (alias: bss)
                     - calculates summary statistics for bipartition support
                 branch_length_multiplier (alias: blm)
@@ -2825,6 +2827,14 @@ class Phykit:
                 --plot                      output path for concordance
                                             ASR plot
 
+                --plot-uncertainty          output path for uncertainty
+                                            plot showing the distribution
+                                            of ancestral estimates across
+                                            gene trees (distribution
+                                            method) or concordance
+                                            sources (weighted method)
+                                            as violin + boxplots
+
                 --missing-taxa              how to handle taxa mismatches:
                                             shared (default) or error
 
@@ -2902,6 +2912,10 @@ class Phykit:
             "--plot", type=str, required=False, default=None,
             help=SUPPRESS, metavar=""
         )
+        parser.add_argument(
+            "--plot-uncertainty", type=str, required=False, default=None,
+            help=SUPPRESS, metavar=""
+        )
         parser.add_argument(
             "--missing-taxa", type=str, required=False, default="shared",
             choices=["error", "shared"], help=SUPPRESS, metavar=""
@@ -2910,6 +2924,72 @@ class Phykit:
         _add_json_argument(parser)
         _run_service(parser, argv, ConcordanceAsr)
 
+    @staticmethod
+    def chronogram(argv):
+        parser = _new_parser(
+            description=textwrap.dedent(
+                f"""\
+                {help_header}
+
+                Plot a chronogram (time-calibrated phylogeny) with
+                geological timescale bands. Requires an ultrametric
+                tree and the root age in millions of years (Ma).
+
+                Geological epoch/period/era bands are drawn behind
+                the tree as colored stripes, with labels along the
+                top. The time axis runs from past (left) to present
+                (right).
+
+                Aliases:
+                  chronogram, chrono, time_tree
+                Command line interfaces:
+                  pk_chronogram, pk_chrono, pk_time_tree
+
+                Usage:
+                phykit chronogram -t <tree> --root-age <float>
+                  --plot-output <file> [--timescale auto|epoch|period|era]
+                  [--node-ages] [--circular] [--ladderize]
+                  [--color-file <file>] [--json]
+
+                Options
+                =====================================================
+                -t/--tree                   ultrametric tree file
+                                            (required)
+
+                --root-age                  age of the root in Ma
+                                            (required)
+
+                --plot-output               output figure path
+                                            (required; .png, .pdf, .svg)
+
+                --timescale                 timescale level: auto
+                                            (default), epoch, period,
+                                            or era. Auto selects based
+                                            on root age.
+
+                --node-ages                 label internal nodes with
+                                            divergence times (Ma)
+
+                --circular                  draw circular chronogram
+
+                --ladderize                 ladderize the tree
+
+                --color-file                color annotation file
+                                            (iTOL-inspired TSV)
+
+                --json                      output node ages as JSON
+                """
+            ),
+        )
+        parser.add_argument("-t", "--tree", type=str, required=True, help=SUPPRESS, metavar="")
+        parser.add_argument("--root-age", type=float, required=True, help=SUPPRESS, metavar="")
+        parser.add_argument("--plot-output", type=str, required=True, help=SUPPRESS, metavar="")
+        parser.add_argument("--timescale", type=str, default="auto", choices=["auto", "epoch", "period", "era"], help=SUPPRESS, metavar="")
+        parser.add_argument("--node-ages", action="store_true", help=SUPPRESS)
+        add_plot_arguments(parser)
+        _add_json_argument(parser)
+        _run_service(parser, argv, Chronogram)
+
     @staticmethod
     def bipartition_support_stats(argv):
         parser = _new_parser(
@@ -9057,6 +9137,10 @@ def concordance_asr(argv=None):
     Phykit.concordance_asr(sys.argv[1:])
 
 
+def chronogram(argv=None):
+    Phykit.chronogram(sys.argv[1:])
+
+
 def bipartition_support_stats(argv=None):
     Phykit.bipartition_support_stats(sys.argv[1:])
 

{phykit-2.1.85 → phykit-2.1.88}/phykit/service_factories.py

@@ -59,6 +59,7 @@ BipartitionSupportStats = _LazyServiceFactory("phykit.services.tree.bipartition_
 BranchLengthMultiplier = _LazyServiceFactory("phykit.services.tree.branch_length_multiplier", "BranchLengthMultiplier")
 CollapseBranches = _LazyServiceFactory("phykit.services.tree.collapse_branches", "CollapseBranches")
 CovaryingEvolutionaryRates = _LazyServiceFactory("phykit.services.tree.covarying_evolutionary_rates", "CovaryingEvolutionaryRates")
+Chronogram = _LazyServiceFactory("phykit.services.tree.chronogram", "Chronogram")
 ConsensusNetwork = _LazyServiceFactory("phykit.services.tree.consensus_network", "ConsensusNetwork")
 NeighborNet = _LazyServiceFactory("phykit.services.tree.neighbor_net", "NeighborNet")
 ConsensusTree = _LazyServiceFactory("phykit.services.tree.consensus_tree", "ConsensusTree")

{phykit-2.1.85 → phykit-2.1.88}/phykit/services/tree/__init__.py

@@ -5,6 +5,7 @@ _EXPORTS = {
     "BipartitionSupportStats": "bipartition_support_stats",
     "BranchLengthMultiplier": "branch_length_multiplier",
     "CollapseBranches": "collapse_branches",
+    "Chronogram": "chronogram",
     "CovaryingEvolutionaryRates": "covarying_evolutionary_rates",
     "ConsensusNetwork": "consensus_network",
     "NeighborNet": "neighbor_net",

{phykit-2.1.85 → phykit-2.1.88}/phykit/services/tree/ancestral_reconstruction.py

@@ -1,5 +1,5 @@
-import copy
 import math
+import pickle
 import sys
 from typing import Dict, List, Tuple
 
@@ -78,7 +78,7 @@ class AncestralReconstruction(Tree):
         x = np.array([trait_values[name] for name in ordered_names])
 
         # Prune tree to shared taxa
-        tree_copy = copy.deepcopy(tree)
+        tree_copy = pickle.loads(pickle.dumps(tree, protocol=pickle.HIGHEST_PROTOCOL))
         tip_names_in_tree = [t.name for t in tree_copy.get_terminals()]
         tips_to_prune = [t for t in tip_names_in_tree if t not in trait_values]
         if tips_to_prune:
@@ -1368,7 +1368,7 @@ class AncestralReconstruction(Tree):
             trait_name = "trait"
 
         # Prune tree to shared taxa
-        tree_copy = copy.deepcopy(tree)
+        tree_copy = pickle.loads(pickle.dumps(tree, protocol=pickle.HIGHEST_PROTOCOL))
         tip_names_in_tree = [t.name for t in tree_copy.get_terminals()]
         tips_to_prune = [t for t in tip_names_in_tree if t not in tip_states]
         if tips_to_prune:

{phykit-2.1.85 → phykit-2.1.88}/phykit/services/tree/base.py

@@ -1,4 +1,5 @@
 import copy
+import pickle
 from typing import List
 from functools import lru_cache
 import os
@@ -80,12 +81,29 @@ class Tree(BaseService):
     def read_reference_tree_file(self):
         return self._read_tree_with_error(self.reference, "reference")
 
+    @staticmethod
+    def _fast_copy(tree):
+        """Copy a tree using pickle instead of deepcopy.
+
+        Avoids RecursionError on deeply nested trees (e.g., ladder-like
+        topologies with hundreds of cascading bifurcations) where
+        copy.deepcopy exceeds Python's default recursion limit.
+        Falls back to deepcopy for objects that can't be pickled (e.g.,
+        mocks in unit tests).
+        """
+        try:
+            return pickle.loads(pickle.dumps(tree, protocol=pickle.HIGHEST_PROTOCOL))
+        except (pickle.PicklingError, TypeError, AttributeError):
+            return copy.deepcopy(tree)
+
     def _read_tree_with_error(self, tree_path: str, attr_name: str):
         try:
             file_hash = self._get_file_hash(tree_path)
             tree = self._cached_tree_read(tree_path, self.tree_format, file_hash)
-            # Return a deep copy to prevent modifications to the cached tree
-            return copy.deepcopy(tree)
+            # Return a copy to prevent modifications to the cached tree.
+            # Uses pickle instead of deepcopy to avoid RecursionError on
+            # deeply nested trees.
+            return self._fast_copy(tree)
         except FileNotFoundError:
             path = getattr(self, attr_name)
             raise PhykitUserError(

{phykit-2.1.85 → phykit-2.1.88}/phykit/services/tree/branch_length_multiplier.py

@@ -1,5 +1,5 @@
 from typing import Dict
-import copy
+import pickle
 
 from Bio.Phylo import Newick
 
@@ -20,7 +20,7 @@ class BranchLengthMultiplier(Tree):
     def run(self) -> None:
         tree = self.read_tree_file()
         # Make a deep copy to avoid modifying the cached tree
-        tree_copy = copy.deepcopy(tree)
+        tree_copy = pickle.loads(pickle.dumps(tree, protocol=pickle.HIGHEST_PROTOCOL))
         scaled_count = self.multiply_branch_lengths_by_factor(tree_copy, self.factor)
         self.write_tree_file(tree_copy, self.output_file_path)
 

{phykit-2.1.85 → phykit-2.1.88}/phykit/services/tree/character_map.py

@@ -7,7 +7,7 @@ produces a phylogram/cladogram plot with annotated character changes.
 
 Uses the generalized parsimony utilities in phykit.helpers.parsimony_utils.
 """
-import copy
+import pickle
 from collections import Counter
 from typing import Dict, List, Optional, Set, Tuple
 
@@ -79,7 +79,7 @@ class CharacterMap(Tree):
 
     def run(self) -> None:
         tree = self.read_tree_file()
-        tree = copy.deepcopy(tree)
+        tree = pickle.loads(pickle.dumps(tree, protocol=pickle.HIGHEST_PROTOCOL))
 
         char_names, tip_states = self._parse_character_matrix(self.data_path)
         n_chars = len(char_names)