phykit 2.1.34__tar.gz → 2.1.37__tar.gz

{phykit-2.1.34 → phykit-2.1.37}/PKG-INFO

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

{phykit-2.1.34 → phykit-2.1.37}/phykit/cli_registry.py

@@ -157,6 +157,8 @@ ALIAS_TO_HANDLER: Dict[str, str] = {
     "etm": "evo_tempo_map",
     "disc_asym": "discordance_asymmetry",
     "da": "discordance_asymmetry",
+    "spec_disc": "spectral_discordance",
+    "sd": "spectral_discordance",
     # Helper aliases
     "create_concat": "create_concatenation_matrix",
     "cc": "create_concatenation_matrix",

{phykit-2.1.34 → phykit-2.1.37}/phykit/phykit.py

@@ -277,7 +277,10 @@ class Phykit:
                 treeness (alias: tness)
                     - reports treeness or stemminess, a measure of signal-to-
                       noise ratio in a phylogeny
-             
+                spectral_discordance (alias: spec_disc; sd)
+                    - PCA + spectral clustering of gene tree space via
+                      bipartition decomposition
+
                 Alignment- and tree-based commands
                 ==================================
                 saturation (alias: sat)
@@ -1474,19 +1477,24 @@ class Phykit:
                 f"""\
                 {help_header}
 
-                Estimate ancestral states for continuous traits using
-                maximum likelihood, analogous to R's phytools::fastAnc()
-                and ape::ace(type="ML"). Optionally produce a contMap
-                plot showing continuous trait values mapped onto the
-                phylogeny.
+                Estimate ancestral states using maximum likelihood.
 
-                Two methods are available:
-                - fast (default): Felsenstein's pruning/contrasts shortcut,
-                  O(n) time
+                Supports two trait types:
+                - continuous (default): Brownian Motion model, analogous
+                  to R's phytools::fastAnc() and ape::ace(type="ML").
+                  Optionally produce a contMap plot.
+                - discrete: Mk model with marginal posterior probabilities
+                  at each internal node, analogous to ape::ace(type="discrete").
+                  Optionally produce a pie-chart phylogeny plot.
+
+                Continuous methods (--type continuous):
+                - fast (default): Felsenstein's pruning/contrasts, O(n)
                 - ml: full VCV-based ML with exact conditional CIs, O(n^3)
 
-                Both methods produce identical point estimates; ml gives
-                exact conditional confidence intervals.
+                Discrete models (--type discrete):
+                - ER (default): equal rates
+                - SYM: symmetric rates
+                - ARD: all rates different
 
                 Input trait data can be either:
                 (1) A two-column file (taxon<tab>value) when -c is omitted
@@ -1499,7 +1507,7 @@ class Phykit:
                   pk_ancestral_state_reconstruction, pk_asr, pk_anc_recon
 
                 Usage:
-                phykit ancestral_state_reconstruction -t <tree> -d <trait_data> [-c <trait>] [-m <method>] [--ci] [--plot <output>] [--json]
+                phykit ancestral_state_reconstruction -t <tree> -d <trait_data> [-c <trait>] [--type <type>] [-m <method>] [--model <model>] [--ci] [--plot <output>] [--json]
 
                 Options
                 =====================================================
@@ -1511,13 +1519,19 @@ class Phykit:
                 -c/--trait                  trait column name (required
                                             for multi-trait files)
 
+                --type                      trait type: continuous or
+                                            discrete (default: continuous)
+
                 -m/--method                 method to use: fast or ml
-                                            (default: fast)
+                                            (continuous only; default: fast)
+
+                --model                     Mk model: ER, SYM, or ARD
+                                            (discrete only; default: ER)
 
                 --ci                        include 95% confidence
-                                            intervals
+                                            intervals (continuous only)
 
-                --plot                      output path for contMap plot
+                --plot                      output path for plot
 
                 --json                      output results as JSON
                 """
@@ -1533,10 +1547,18 @@ class Phykit:
             "-c", "--trait", type=str, required=False, default=None,
             help=SUPPRESS, metavar=""
         )
+        parser.add_argument(
+            "--type", type=str, required=False, default="continuous",
+            choices=["continuous", "discrete"], help=SUPPRESS, metavar=""
+        )
         parser.add_argument(
             "-m", "--method", type=str, required=False, default="fast",
             choices=["fast", "ml"], help=SUPPRESS, metavar=""
         )
+        parser.add_argument(
+            "--model", type=str, required=False, default="ER",
+            choices=["ER", "SYM", "ARD"], help=SUPPRESS, metavar=""
+        )
         parser.add_argument(
             "--ci", action="store_true", required=False, help=SUPPRESS
         )
@@ -4981,6 +5003,95 @@ class Phykit:
         _add_json_argument(parser)
         _run_service(parser, argv, DiscordanceAsymmetry)
 
+    @staticmethod
+    def spectral_discordance(argv):
+        parser = _new_parser(
+            description=textwrap.dedent(
+                f"""\
+                {help_header}
+
+                Spectral discordance decomposition — decompose gene tree
+                space via PCA on a bipartition presence/absence (or
+                branch-length) matrix, with spectral clustering and
+                automatic cluster detection via the eigengap heuristic.
+
+                Each gene tree is encoded as a vector over the union of
+                all bipartitions observed across gene trees. PCA reveals
+                the axes of topological variation, with loading vectors
+                identifying which bipartitions drive each PC. Spectral
+                clustering groups genes sharing similar topologies.
+
+                Two metrics are available:
+                - nrf (default): binary presence/absence (normalized RF)
+                - wrf: branch-length weighted
+
+                Aliases:
+                  spectral_discordance, spec_disc, sd
+                Command line interfaces:
+                  pk_spectral_discordance, pk_spec_disc, pk_sd
+
+                Usage:
+                phykit spectral_discordance -g <gene_trees> [-t <tree>] [--metric nrf|wrf] [--clusters K] [--n-pcs N] [--top-loadings N] [--plot <prefix>] [--json]
+
+                Options
+                =====================================================
+                -g/--gene-trees             file of gene trees (one
+                                            Newick per line, or file
+                                            of filenames)
+
+                -t/--tree                   species tree (optional; flags
+                                            species-tree bipartitions in
+                                            loading output)
+
+                --metric                    distance metric: nrf or wrf
+                                            (default: nrf)
+
+                --clusters                  override auto-detected K
+
+                --n-pcs                     number of PCs to report
+                                            (default: min(10, G-1))
+
+                --top-loadings              top bipartitions per PC
+                                            (default: 5)
+
+                --plot                      output prefix for plots
+                                            (generates _scatter.png and
+                                            _eigengap.png)
+
+                --json                      output results as JSON
+                """
+            ),
+        )
+        parser.add_argument(
+            "-g", "--gene-trees", type=str, required=True, help=SUPPRESS, metavar=""
+        )
+        parser.add_argument(
+            "-t", "--tree", type=str, required=False, default=None,
+            help=SUPPRESS, metavar=""
+        )
+        parser.add_argument(
+            "--metric", type=str, required=False, default="nrf",
+            choices=["nrf", "wrf"], help=SUPPRESS, metavar=""
+        )
+        parser.add_argument(
+            "--clusters", type=int, required=False, default=None,
+            help=SUPPRESS, metavar=""
+        )
+        parser.add_argument(
+            "--n-pcs", type=int, required=False, default=None,
+            help=SUPPRESS, metavar=""
+        )
+        parser.add_argument(
+            "--top-loadings", type=int, required=False, default=5,
+            help=SUPPRESS, metavar=""
+        )
+        parser.add_argument(
+            "--plot", type=str, required=False, default=None,
+            help=SUPPRESS, metavar=""
+        )
+        _add_json_argument(parser)
+        _run_service(parser, argv, SpectralDiscordance)
+
     ### Helper commands
     @staticmethod
     def create_concatenation_matrix(argv):
@@ -5434,3 +5545,15 @@ def create_concatenation_matrix(argv=None):
 
 def thread_dna(argv=None):
     Phykit.thread_dna(sys.argv[1:])
+
+
+def evo_tempo_map(argv=None):
+    Phykit.evo_tempo_map(sys.argv[1:])
+
+
+def discordance_asymmetry(argv=None):
+    Phykit.discordance_asymmetry(sys.argv[1:])
+
+
+def spectral_discordance(argv=None):
+    Phykit.spectral_discordance(sys.argv[1:])

{phykit-2.1.34 → phykit-2.1.37}/phykit/service_factories.py

@@ -98,6 +98,7 @@ Treeness = _LazyServiceFactory("phykit.services.tree.treeness", "Treeness")
 TreenessOverRCV = _LazyServiceFactory("phykit.services.tree.treeness_over_rcv", "TreenessOverRCV")
 EvoTempoMap = _LazyServiceFactory("phykit.services.tree.evo_tempo_map", "EvoTempoMap")
 DiscordanceAsymmetry = _LazyServiceFactory("phykit.services.tree.discordance_asymmetry", "DiscordanceAsymmetry")
+SpectralDiscordance = _LazyServiceFactory("phykit.services.tree.spectral_discordance", "SpectralDiscordance")
 
 SERVICE_FACTORIES: Dict[str, _LazyServiceFactory] = {
     name: value