phykit 2.1.62__tar.gz → 2.1.64__tar.gz

{phykit-2.1.62 → phykit-2.1.64}/PKG-INFO

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

{phykit-2.1.62 → phykit-2.1.64}/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",
+    "dstat": "dstatistic",
+    "abba_baba": "dstatistic",
     "cs": "column_score",
     "comp_bias_per_site": "compositional_bias_per_site",
     "cbps": "compositional_bias_per_site",
@@ -182,6 +184,9 @@ ALIAS_TO_HANDLER: Dict[str, str] = {
     "trait_correlation": "trait_correlation",
     "trait_corr": "trait_correlation",
     "phylo_corr": "trait_correlation",
+    "trait_rate_map": "trait_rate_map",
+    "rate_map": "trait_rate_map",
+    "branch_rates": "trait_rate_map",
     "tree_space": "tree_space",
     "tspace": "tree_space",
     "tree_landscape": "tree_space",

{phykit-2.1.62 → phykit-2.1.64}/phykit/phykit.py

@@ -119,6 +119,9 @@ class Phykit:
                     - recode alignments using reduced character schemes
                 alignment_subsample (alias: aln_subsample; subsample)
                     - randomly subsample genes, partitions, or sites
+                dstatistic (alias: dstat; abba_baba)
+                    - Patterson's D-statistic (ABBA-BABA test) for
+                      detecting introgression/gene flow
                 alignment_outlier_taxa (alias: outlier_taxa; aot)
                     - identify potential outlier taxa and why they were flagged
                 column_score (alias: cs)
@@ -234,6 +237,8 @@ class Phykit:
                     - stochastic character mapping (SIMMAP) of discrete traits
                 cont_map (alias: contmap; cmap)
                     - continuous trait map (contMap) visualization on a phylogeny
+                trait_rate_map (alias: rate_map; branch_rates)
+                    - per-branch evolutionary rate map for a continuous trait
                 density_map (alias: densitymap; dmap)
                     - density map of posterior state probabilities on a phylogeny
                 cophylo (alias: tanglegram; tangle)
@@ -1943,6 +1948,73 @@ class Phykit:
         _add_json_argument(parser)
         _run_service(parser, argv, AlignmentSubsample)
 
+    @staticmethod
+    def dstatistic(argv):
+        parser = _new_parser(
+            description=textwrap.dedent(
+                f"""\
+                {help_header}
+
+                Compute Patterson's D-statistic (ABBA-BABA test) for
+                detecting introgression or gene flow from a four-taxon
+                alignment.
+
+                The assumed topology is (((P1, P2), P3), Outgroup).
+                Under incomplete lineage sorting (ILS) alone, ABBA and
+                BABA site patterns should be equally frequent. A
+                significant excess of either pattern indicates gene
+                flow.
+
+                D > 0 suggests gene flow between P2 and P3.
+                D < 0 suggests gene flow between P1 and P3.
+                D = 0 is consistent with ILS alone.
+
+                Significance is assessed via block jackknife (Green
+                et al. 2010; Patterson et al. 2012).
+
+                Aliases:
+                  dstatistic, dstat, abba_baba
+                Command line interfaces:
+                  pk_dstatistic, pk_dstat, pk_abba_baba
+
+                Usage:
+                phykit dstatistic -a <alignment> --p1 <taxon> --p2 <taxon>
+                    --p3 <taxon> --outgroup <taxon>
+                    [--block-size 100] [--json]
+
+                Options
+                =====================================================
+                -a/--alignment              FASTA alignment file
+
+                --p1                        taxon name for P1
+                                            (sister to P2)
+
+                --p2                        taxon name for P2
+                                            (sister to P1; potential
+                                            recipient of gene flow)
+
+                --p3                        taxon name for P3
+                                            (donor lineage)
+
+                --outgroup                  outgroup taxon name
+
+                --block-size                block size for jackknife
+                                            estimation of standard
+                                            error (default: 100)
+
+                --json                      output results as JSON
+                """
+            ),
+        )
+        parser.add_argument("-a", "--alignment", type=str, required=True, help=SUPPRESS, metavar="")
+        parser.add_argument("--p1", type=str, required=True, help=SUPPRESS, metavar="")
+        parser.add_argument("--p2", type=str, required=True, help=SUPPRESS, metavar="")
+        parser.add_argument("--p3", type=str, required=True, help=SUPPRESS, metavar="")
+        parser.add_argument("--outgroup", type=str, required=True, help=SUPPRESS, metavar="")
+        parser.add_argument("--block-size", type=int, default=100, help=SUPPRESS, metavar="")
+        _add_json_argument(parser)
+        _run_service(parser, argv, Dstatistic)
+
     ## Tree functions
     @staticmethod
     def parsimony_score(argv):
@@ -7353,6 +7425,129 @@ class Phykit:
         _add_json_argument(parser)
         _run_service(parser, argv, SpectralDiscordance)
 
+    @staticmethod
+    def trait_rate_map(argv):
+        parser = _new_parser(
+            description=textwrap.dedent(
+                f"""\
+                {help_header}
+
+                Trait Rate Map — estimate per-branch evolutionary
+                rates for a continuous trait and display them as a
+                branch-colored phylogram.
+
+                Ancestral states are reconstructed via Felsenstein's
+                weighted-average method (inverse-branch-length
+                weighting, postorder traversal). Per-branch rate is
+                the squared standardized contrast:
+                  rate = (child_val - parent_val)^2 / branch_length
+
+                Input is a phylogenetic tree and either:
+                  (a) a two-column TSV (taxon<tab>value, no header), or
+                  (b) a multi-column TSV with header (use --trait to
+                      select a column)
+
+                Aliases:
+                  trait_rate_map, rate_map, branch_rates
+                Command line interfaces:
+                  pk_trait_rate_map, pk_rate_map, pk_branch_rates
+
+                Usage:
+                phykit trait_rate_map -t <tree> -d <trait_data> -o <output>
+                  [--trait <column>] [--json]
+                  [--fig-width <float>] [--fig-height <float>]
+                  [--dpi <int>] [--no-title] [--title <str>]
+                  [--legend-position <str>]
+                  [--ylabel-fontsize <float>] [--xlabel-fontsize <float>]
+                  [--title-fontsize <float>] [--axis-fontsize <float>]
+                  [--colors <str>] [--ladderize] [--cladogram] [--circular] [--color-file <file>]
+
+                Options
+                =====================================================
+                -t/--tree                   a tree file
+
+                -d/--trait_data             tab-delimited trait file
+                                            (two-column: taxon<tab>value,
+                                            no header; or multi-column
+                                            with header when --trait is
+                                            used)
+
+                -o/--output                 output plot file path
+                                            (required)
+
+                --trait                     column name to use from a
+                                            multi-column trait file
+                                            (if omitted, two-column
+                                            format is expected)
+
+                --fig-width                 figure width in inches
+                                            (auto-scaled if omitted)
+
+                --fig-height                figure height in inches
+                                            (auto-scaled if omitted)
+
+                --dpi                       resolution in DPI
+                                            (default: 300)
+
+                --no-title                  hide the plot title
+
+                --title                     custom title text
+
+                --legend-position           legend location (e.g.,
+                                            "upper right", "none")
+
+                --ylabel-fontsize           font size for y-axis labels;
+                                            0 to hide
+
+                --xlabel-fontsize           font size for x-axis labels;
+                                            0 to hide
+
+                --title-fontsize            font size for the title
+
+                --axis-fontsize             font size for axis labels
+
+                --colors                    comma-separated colors
+                                            (hex or named, e.g.,
+                                            "#ff0000,blue,#00ff00")
+
+                --ladderize                 ladderize (sort) the tree
+                                            before plotting
+
+                --cladogram                 draw cladogram (equal branch
+                                            lengths, tips aligned)
+                                            instead of phylogram
+
+                --circular                  draw circular (radial/fan)
+                                            phylogram instead of
+                                            rectangular
+
+                --color-file                color annotation file for
+                                            tip labels, clade ranges,
+                                            and branch colors (iTOL-
+                                            inspired TSV format)
+
+                --json                      optional argument to also
+                                            output results as JSON
+                """
+            ),
+        )
+        parser.add_argument(
+            "-t", "--tree", type=str, required=True, help=SUPPRESS, metavar=""
+        )
+        parser.add_argument(
+            "-d", "--trait_data", type=str, required=True, help=SUPPRESS, metavar=""
+        )
+        parser.add_argument(
+            "-o", "--output", type=str, required=True, help=SUPPRESS, metavar=""
+        )
+        parser.add_argument(
+            "--trait", type=str, required=False, default=None,
+            help=SUPPRESS, metavar=""
+        )
+        add_plot_arguments(parser)
+        _add_json_argument(parser)
+        _run_service(parser, argv, TraitRateMap)
+
     @staticmethod
     def tree_space(argv):
         parser = _new_parser(
@@ -7756,6 +7951,10 @@ def alignment_subsample(argv=None):
     Phykit.alignment_subsample(sys.argv[1:])
 
 
+def dstatistic(argv=None):
+    Phykit.dstatistic(sys.argv[1:])
+
+
 # Tree-based functions
 def parsimony_score(argv=None):
     Phykit.parsimony_score(sys.argv[1:])
@@ -8029,3 +8228,7 @@ def spectral_discordance(argv=None):
 
 def tree_space(argv=None):
     Phykit.tree_space(sys.argv[1:])
+
+
+def trait_rate_map(argv=None):
+    Phykit.trait_rate_map(sys.argv[1:])

{phykit-2.1.62 → phykit-2.1.64}/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")
+Dstatistic = _LazyServiceFactory("phykit.services.alignment.dstatistic", "Dstatistic")
 EvolutionaryRatePerSite = _LazyServiceFactory("phykit.services.alignment.evolutionary_rate_per_site", "EvolutionaryRatePerSite")
 Faidx = _LazyServiceFactory("phykit.services.alignment.faidx", "Faidx")
 GCContent = _LazyServiceFactory("phykit.services.alignment.gc_content", "GCContent")
@@ -109,6 +110,7 @@ EvoTempoMap = _LazyServiceFactory("phykit.services.tree.evo_tempo_map", "EvoTemp
 DiscordanceAsymmetry = _LazyServiceFactory("phykit.services.tree.discordance_asymmetry", "DiscordanceAsymmetry")
 SpectralDiscordance = _LazyServiceFactory("phykit.services.tree.spectral_discordance", "SpectralDiscordance")
 TraitCorrelation = _LazyServiceFactory("phykit.services.tree.trait_correlation", "TraitCorrelation")
+TraitRateMap = _LazyServiceFactory("phykit.services.tree.trait_rate_map", "TraitRateMap")
 TreeSpace = _LazyServiceFactory("phykit.services.tree.tree_space", "TreeSpace")
 
 SERVICE_FACTORIES: Dict[str, _LazyServiceFactory] = {

{phykit-2.1.62 → phykit-2.1.64}/phykit/services/alignment/__init__.py

@@ -12,6 +12,7 @@ _EXPORTS = {
     "CompositionPerTaxon": "composition_per_taxon",
     "CreateConcatenationMatrix": "create_concatenation_matrix",
     "DNAThreader": "dna_threader",
+    "Dstatistic": "dstatistic",
     "EvolutionaryRatePerSite": "evolutionary_rate_per_site",
     "Faidx": "faidx",
     "GCContent": "gc_content",

phykit-2.1.64/phykit/services/alignment/dstatistic.py

@@ -0,0 +1,224 @@
+"""Patterson's D-statistic (ABBA-BABA test) for detecting introgression."""
+
+from typing import Dict
+
+import numpy as np
+from Bio import SeqIO
+
+from .base import Alignment
+from ...helpers.json_output import print_json
+from ...errors import PhykitUserError
+
+
+class Dstatistic(Alignment):
+    def __init__(self, args) -> None:
+        parsed = self.process_args(args)
+        super().__init__(alignment_file_path=parsed["alignment_path"])
+        self.p1 = parsed["p1"]
+        self.p2 = parsed["p2"]
+        self.p3 = parsed["p3"]
+        self.outgroup = parsed["outgroup"]
+        self.block_size = parsed["block_size"]
+        self.json_output = parsed["json_output"]
+
+    def process_args(self, args) -> Dict[str, object]:
+        return dict(
+            alignment_path=args.alignment,
+            p1=args.p1,
+            p2=args.p2,
+            p3=args.p3,
+            outgroup=args.outgroup,
+            block_size=getattr(args, "block_size", 100),
+            json_output=getattr(args, "json", False),
+        )
+
+    def run(self):
+        # Read alignment sequences
+        sequences = {}
+        for record in SeqIO.parse(self.alignment_file_path, "fasta"):
+            sequences[record.id] = str(record.seq).upper()
+
+        # Validate taxa are present
+        required = {"p1": self.p1, "p2": self.p2, "p3": self.p3, "outgroup": self.outgroup}
+        for label, taxon in required.items():
+            if taxon not in sequences:
+                raise PhykitUserError(
+                    [f"Taxon '{taxon}' ({label}) not found in alignment. "
+                     f"Available taxa: {', '.join(sorted(sequences.keys()))}"],
+                    code=2,
+                )
+
+        seq_p1 = sequences[self.p1]
+        seq_p2 = sequences[self.p2]
+        seq_p3 = sequences[self.p3]
+        seq_outgroup = sequences[self.outgroup]
+
+        # Validate equal lengths
+        lengths = {len(seq_p1), len(seq_p2), len(seq_p3), len(seq_outgroup)}
+        if len(lengths) != 1:
+            raise PhykitUserError(
+                ["Sequences have different lengths. All sequences must be aligned."],
+                code=2,
+            )
+
+        aln_length = len(seq_p1)
+        skip_chars = {"-", "N", "?", "X", "n", "x"}
+
+        # Count site patterns
+        abba_count = 0
+        baba_count = 0
+
+        for site in range(aln_length):
+            p1 = seq_p1[site]
+            p2 = seq_p2[site]
+            p3 = seq_p3[site]
+            o = seq_outgroup[site]
+
+            # Skip sites with gaps or ambiguous characters
+            if any(c in skip_chars for c in [p1, p2, p3, o]):
+                continue
+
+            # Skip sites that are not biallelic
+            alleles = {p1, p2, p3, o}
+            if len(alleles) != 2:
+                continue
+
+            # ABBA: P1=ancestral, P2=derived, P3=derived, O=ancestral
+            if p1 == o and p2 != o and p3 != o and p2 == p3:
+                abba_count += 1
+            # BABA: P1=derived, P2=ancestral, P3=derived, O=ancestral
+            elif p2 == o and p1 != o and p3 != o and p1 == p3:
+                baba_count += 1
+
+        informative_sites = abba_count + baba_count
+
+        # Compute D-statistic
+        if informative_sites == 0:
+            d_stat = 0.0
+        else:
+            d_stat = (abba_count - baba_count) / informative_sites
+
+        # Block jackknife for significance
+        n_blocks = aln_length // self.block_size
+        se = None
+        z_score = None
+        p_value = None
+
+        if n_blocks >= 2:
+            block_abba = np.zeros(n_blocks)
+            block_baba = np.zeros(n_blocks)
+
+            for site in range(aln_length):
+                block_idx = site // self.block_size
+                if block_idx >= n_blocks:
+                    break
+
+                p1 = seq_p1[site]
+                p2 = seq_p2[site]
+                p3 = seq_p3[site]
+                o = seq_outgroup[site]
+
+                if any(c in skip_chars for c in [p1, p2, p3, o]):
+                    continue
+                alleles = {p1, p2, p3, o}
+                if len(alleles) != 2:
+                    continue
+
+                if p1 == o and p2 != o and p3 != o and p2 == p3:
+                    block_abba[block_idx] += 1
+                elif p2 == o and p1 != o and p3 != o and p1 == p3:
+                    block_baba[block_idx] += 1
+
+            total_abba = np.sum(block_abba)
+            total_baba = np.sum(block_baba)
+
+            jackknife_d = np.zeros(n_blocks)
+            for i in range(n_blocks):
+                loo_abba = total_abba - block_abba[i]
+                loo_baba = total_baba - block_baba[i]
+                denom = loo_abba + loo_baba
+                if denom > 0:
+                    jackknife_d[i] = (loo_abba - loo_baba) / denom
+                else:
+                    jackknife_d[i] = 0.0
+
+            mean_d = np.mean(jackknife_d)
+            se = float(np.sqrt((n_blocks - 1) / n_blocks * np.sum((jackknife_d - mean_d) ** 2)))
+
+            if se > 0:
+                z_score = d_stat / se
+                from scipy.stats import norm
+                p_value = float(2.0 * norm.sf(abs(z_score)))
+            else:
+                z_score = float('inf') if d_stat != 0 else 0.0
+                p_value = 0.0 if d_stat != 0 else 1.0
+
+        # Output
+        if self.json_output:
+            payload = {
+                "p1": self.p1,
+                "p2": self.p2,
+                "p3": self.p3,
+                "outgroup": self.outgroup,
+                "alignment_length": aln_length,
+                "informative_sites": informative_sites,
+                "abba_count": abba_count,
+                "baba_count": baba_count,
+                "d_statistic": round(d_stat, 4),
+                "block_size": self.block_size,
+                "n_blocks": n_blocks if n_blocks >= 2 else n_blocks,
+                "standard_error": round(se, 4) if se is not None else None,
+                "z_score": round(z_score, 2) if z_score is not None and z_score != float('inf') else z_score,
+                "p_value": round(p_value, 6) if p_value is not None else None,
+            }
+            print_json(payload, sort_keys=False)
+            return
+
+        try:
+            print("Patterson's D-statistic (ABBA-BABA Test)")
+            print("=========================================")
+            print(f"Topology: ((({self.p1}, {self.p2}), {self.p3}), {self.outgroup})")
+            print(f"P1: {self.p1}")
+            print(f"P2: {self.p2}")
+            print(f"P3: {self.p3}")
+            print(f"Outgroup: {self.outgroup}")
+            print()
+            print(f"Alignment length: {aln_length}")
+            print(f"Informative sites: {informative_sites}")
+            print(f"ABBA sites: {abba_count}")
+            print(f"BABA sites: {baba_count}")
+            print(f"D-statistic: {d_stat:.4f}")
+
+            if se is not None:
+                print(f"Block jackknife (block size: {self.block_size}):")
+                print(f"  Standard error: {se:.4f}")
+                if z_score == float('inf'):
+                    print("  Z-score: inf")
+                else:
+                    print(f"  Z-score: {z_score:.2f}")
+                print(f"  p-value: {p_value:.6f}")
+                print()
+                print(f"Interpretation: {self._interpret(d_stat, p_value)}")
+            else:
+                print()
+                print("Not enough blocks for jackknife significance test.")
+        except BrokenPipeError:
+            pass
+
+    def _interpret(self, d_stat: float, p_value: float, alpha: float = 0.05) -> str:
+        if p_value < alpha:
+            if d_stat > 0:
+                return (
+                    f"Significant excess of ABBA patterns (p < {alpha}) "
+                    f"suggests introgression between P2 ({self.p2}) and "
+                    f"P3 ({self.p3}). Note: D cannot determine the "
+                    f"direction of gene flow."
+                )
+            else:
+                return (
+                    f"Significant excess of BABA patterns (p < {alpha}) "
+                    f"suggests introgression between P1 ({self.p1}) and "
+                    f"P3 ({self.p3}). Note: D cannot determine the "
+                    f"direction of gene flow."
+                )
+        return "No significant evidence of introgression (consistent with ILS)."

{phykit-2.1.62 → phykit-2.1.64}/phykit/services/tree/__init__.py

@@ -49,6 +49,7 @@ _EXPORTS = {
     "TreenessOverRCV": "treeness_over_rcv",
     "ConcordanceAsr": "concordance_asr",
     "TraitCorrelation": "trait_correlation",
+    "TraitRateMap": "trait_rate_map",
     "TreeSpace": "tree_space",
 }