phykit 2.1.87__tar.gz → 2.1.88__tar.gz

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

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

{phykit-2.1.87 → 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.87 → 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)
@@ -2922,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(
@@ -9069,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.87 → 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.87 → 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",