phykit 2.1.87__tar.gz → 2.1.89__tar.gz

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

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

{phykit-2.1.87 → phykit-2.1.89}/phykit/cli_registry.py

@@ -21,6 +21,8 @@ ALIAS_TO_HANDLER: Dict[str, str] = {
     "recode": "alignment_recoding",
     "outlier_taxa": "alignment_outlier_taxa",
     "aot": "alignment_outlier_taxa",
+    "dtt": "dtt",
+    "disparity_through_time": "dtt",
     "dstat": "dstatistic",
     "abba_baba": "dstatistic",
     "dfoil": "dfoil",
@@ -70,6 +72,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.89/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.89}/phykit/phykit.py

@@ -192,6 +192,10 @@ 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
+                dtt (alias: disparity_through_time)
+                    - disparity through time analysis (Harmon et al. 2003)
                 bipartition_support_stats (alias: bss)
                     - calculates summary statistics for bipartition support
                 branch_length_multiplier (alias: blm)
@@ -2922,6 +2926,143 @@ 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 dtt(argv):
+        parser = _new_parser(
+            description=textwrap.dedent(
+                f"""\
+                {help_header}
+
+                Disparity through time (DTT) analysis. Computes how
+                morphological disparity partitions among subclades
+                through time (Harmon et al. 2003).
+
+                At each branching time, calculates the mean relative
+                subclade disparity. Under Brownian motion, this declines
+                linearly. The MDI (Morphological Disparity Index) is the
+                area between the observed DTT and the BM null median.
+
+                Positive MDI = late disparity accumulation
+                Negative MDI = early disparity accumulation (radiation)
+
+                Aliases:
+                  dtt, disparity_through_time
+                Command line interfaces:
+                  pk_dtt, pk_disparity_through_time
+
+                Usage:
+                phykit dtt -t <tree> --traits <traits_file>
+                  [--trait <column>] [--index avg_sq|avg_manhattan]
+                  [--nsim <int>] [--seed <int>]
+                  [--plot-output <file>] [--json]
+
+                Options
+                =====================================================
+                -t/--tree                   ultrametric tree file
+                                            (required)
+
+                --traits                    TSV file with trait data
+                                            (required)
+
+                --trait                     specific trait column name
+                                            (default: all traits)
+
+                --index                     disparity index: avg_sq
+                                            (average squared Euclidean
+                                            distance, default) or
+                                            avg_manhattan
+
+                --nsim                      number of BM simulations
+                                            for null DTT envelope and
+                                            MDI p-value (default: 0,
+                                            no simulations)
+
+                --seed                      random seed for
+                                            reproducibility
+
+                --plot-output               output figure path
+
+                --json                      output results as JSON
+                """
+            ),
+        )
+        parser.add_argument("-t", "--tree", type=str, required=True, help=SUPPRESS, metavar="")
+        parser.add_argument("--traits", type=str, required=True, help=SUPPRESS, metavar="")
+        parser.add_argument("--trait", type=str, default=None, help=SUPPRESS, metavar="")
+        parser.add_argument("--index", type=str, default="avg_sq", choices=["avg_sq", "avg_manhattan"], help=SUPPRESS, metavar="")
+        parser.add_argument("--nsim", type=int, default=0, help=SUPPRESS, metavar="")
+        parser.add_argument("--seed", type=int, default=None, help=SUPPRESS, metavar="")
+        parser.add_argument("--plot-output", type=str, default=None, help=SUPPRESS, metavar="")
+        add_plot_arguments(parser)
+        _add_json_argument(parser)
+        _run_service(parser, argv, Dtt)
+
     @staticmethod
     def bipartition_support_stats(argv):
         parser = _new_parser(
@@ -9069,6 +9210,14 @@ def concordance_asr(argv=None):
     Phykit.concordance_asr(sys.argv[1:])
 
 
+def chronogram(argv=None):
+    Phykit.chronogram(sys.argv[1:])
+
+
+def dtt(argv=None):
+    Phykit.dtt(sys.argv[1:])
+
+
 def bipartition_support_stats(argv=None):
     Phykit.bipartition_support_stats(sys.argv[1:])
 

{phykit-2.1.87 → phykit-2.1.89}/phykit/service_factories.py

@@ -29,6 +29,7 @@ CompositionalBiasPerSite = _LazyServiceFactory("phykit.services.alignment.compos
 CompositionPerTaxon = _LazyServiceFactory("phykit.services.alignment.composition_per_taxon", "CompositionPerTaxon")
 CreateConcatenationMatrix = _LazyServiceFactory("phykit.services.alignment.create_concatenation_matrix", "CreateConcatenationMatrix")
 DNAThreader = _LazyServiceFactory("phykit.services.alignment.dna_threader", "DNAThreader")
+Dtt = _LazyServiceFactory("phykit.services.tree.dtt", "Dtt")
 Dstatistic = _LazyServiceFactory("phykit.services.alignment.dstatistic", "Dstatistic")
 Dfoil = _LazyServiceFactory("phykit.services.alignment.dfoil", "Dfoil")
 EvolutionaryRatePerSite = _LazyServiceFactory("phykit.services.alignment.evolutionary_rate_per_site", "EvolutionaryRatePerSite")
@@ -59,6 +60,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.89}/phykit/services/tree/__init__.py

@@ -5,11 +5,13 @@ _EXPORTS = {
     "BipartitionSupportStats": "bipartition_support_stats",
     "BranchLengthMultiplier": "branch_length_multiplier",
     "CollapseBranches": "collapse_branches",
+    "Chronogram": "chronogram",
     "CovaryingEvolutionaryRates": "covarying_evolutionary_rates",
     "ConsensusNetwork": "consensus_network",
     "NeighborNet": "neighbor_net",
     "ConsensusTree": "consensus_tree",
     "DVMC": "dvmc",
+    "Dtt": "dtt",
     "DiscordanceAsymmetry": "discordance_asymmetry",
     "EvolutionaryRate": "evolutionary_rate",
     "EvoTempoMap": "evo_tempo_map",