phykit 2.1.44__tar.gz → 2.1.46__tar.gz

{phykit-2.1.44 → phykit-2.1.46}/PKG-INFO

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

{phykit-2.1.44 → phykit-2.1.46}/phykit/cli_registry.py

@@ -80,12 +80,16 @@ ALIAS_TO_HANDLER: Dict[str, str] = {
     "phylo_dimreduce": "phylogenetic_ordination",
     "dimreduce": "phylogenetic_ordination",
     "pdr": "phylogenetic_ordination",
+    "pheatmap": "phylo_heatmap",
+    "ph": "phylo_heatmap",
     "phylomorpho": "phylomorphospace",
     "phmo": "phylomorphospace",
     "phylo_regression": "phylogenetic_regression",
     "pgls": "phylogenetic_regression",
     "phylo_glm": "phylogenetic_glm",
     "pglm": "phylogenetic_glm",
+    "pic": "independent_contrasts",
+    "phylo_contrasts": "independent_contrasts",
     "asr": "ancestral_state_reconstruction",
     "anc_recon": "ancestral_state_reconstruction",
     "conc_asr": "concordance_asr",

{phykit-2.1.44 → phykit-2.1.46}/phykit/phykit.py

@@ -161,6 +161,8 @@ class Phykit:
 
                 Tree-based commands
                 ===================
+                independent_contrasts (alias: pic; phylo_contrasts)
+                    - Felsenstein's phylogenetically independent contrasts
                 ancestral_state_reconstruction (alias: asr; anc_recon)
                     - estimate ancestral states for continuous traits using
                       ML (fast or VCV-based) with optional contMap plot
@@ -207,6 +209,8 @@ class Phykit:
                     phylo_pca; phyl_pca; ppca; phylo_dimreduce; dimreduce; pdr)
                     - phylogenetic ordination (PCA, t-SNE, or UMAP) on
                       continuous multi-trait data
+                phylo_heatmap (alias: pheatmap; ph)
+                    - phylogeny alongside a heatmap of numeric trait values
                 phylomorphospace (alias: phylomorpho; phmo)
                     - plot raw traits with phylogeny overlaid via ancestral
                       reconstruction
@@ -1675,6 +1679,57 @@ class Phykit:
         _run_service(parser, argv, VariableSites)
 
     ## Tree functions
+    @staticmethod
+    def independent_contrasts(argv):
+        parser = _new_parser(
+            description=textwrap.dedent(
+                f"""\
+                {help_header}
+
+                Compute Felsenstein's (1985) phylogenetically independent
+                contrasts (PIC) for a continuous trait on a phylogeny.
+
+                Each internal node yields one standardized contrast,
+                producing n-1 contrasts for n tips. Contrasts are
+                computed by postorder traversal, dividing the trait
+                difference between sister clades by the square root of
+                the sum of their branch lengths.
+
+                Multifurcations are automatically resolved by adding
+                zero-length branches.
+
+                Cross-validated against R's ape::pic().
+
+                Aliases:
+                  independent_contrasts, pic, phylo_contrasts
+                Command line interfaces:
+                  pk_independent_contrasts, pk_pic
+
+                Usage:
+                phykit independent_contrasts -t <tree> -d <trait_data>
+                  [--json]
+
+                Options
+                =====================================================
+                -t/--tree                   tree file (required)
+
+                -d/--trait_data             trait data file, two columns:
+                                            taxon<tab>value (required)
+
+                --json                      optional argument to 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=""
+        )
+        _add_json_argument(parser)
+        _run_service(parser, argv, IndependentContrasts)
+
     @staticmethod
     def ancestral_state_reconstruction(argv):
         parser = _new_parser(
@@ -3013,6 +3068,100 @@ class Phykit:
     def phylogenetic_dimreduce(argv):
         Phykit.phylogenetic_ordination(argv)
 
+    @staticmethod
+    def phylo_heatmap(argv):
+        parser = _new_parser(
+            description=textwrap.dedent(
+                f"""\
+                {help_header}
+
+                Draw a phylogenetic heatmap: a phylogeny alongside a
+                color-coded matrix of numeric trait values. Rows are
+                aligned to tree tips.
+
+                Analogous to R's phytools::phylo.heatmap().
+
+                Aliases:
+                  phylo_heatmap, pheatmap, ph
+                Command line interfaces:
+                  pk_phylo_heatmap, pk_pheatmap, pk_ph
+
+                Usage:
+                phykit phylo_heatmap -t <tree> -d <data> -o <output>
+                  [--split 0.3] [--standardize] [--cmap viridis]
+                  [--json]
+                  [--fig-width <float>] [--fig-height <float>]
+                  [--dpi <int>] [--no-title] [--title <str>]
+                  [--ylabel-fontsize <float>] [--xlabel-fontsize <float>]
+
+                Options
+                =====================================================
+                -t/--tree                   tree file (required)
+
+                -d/--data                   numeric data matrix in TSV
+                                            format with header row
+                                            (required)
+
+                -o/--output                 output figure path (required;
+                                            supports .png, .pdf, .svg)
+
+                --split                     fraction of figure width for
+                                            the tree panel (default: 0.3)
+
+                --standardize               z-score each column before
+                                            coloring
+
+                --cmap                      matplotlib colormap name
+                                            (default: viridis)
+
+                --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
+
+                --ylabel-fontsize           font size for taxon labels;
+                                            0 to hide
+
+                --xlabel-fontsize           font size for trait column
+                                            labels; 0 to hide
+
+                --json                      optional argument to output
+                                            metadata as JSON
+                """
+            ),
+        )
+        parser.add_argument(
+            "-t", "--tree", type=str, required=True, help=SUPPRESS, metavar=""
+        )
+        parser.add_argument(
+            "-d", "--data", type=str, required=True, help=SUPPRESS, metavar=""
+        )
+        parser.add_argument(
+            "-o", "--output", type=str, required=True, help=SUPPRESS, metavar=""
+        )
+        parser.add_argument(
+            "--split", type=float, required=False, default=0.3,
+            help=SUPPRESS, metavar=""
+        )
+        parser.add_argument(
+            "--standardize", action="store_true", required=False, help=SUPPRESS
+        )
+        parser.add_argument(
+            "--cmap", type=str, required=False, default="viridis",
+            help=SUPPRESS, metavar=""
+        )
+        add_plot_arguments(parser)
+        _add_json_argument(parser)
+        _run_service(parser, argv, PhyloHeatmap)
+
     @staticmethod
     def phylomorphospace(argv):
         parser = _new_parser(
@@ -6576,6 +6725,10 @@ def variable_sites(argv=None):
 
 
 # Tree-based functions
+def independent_contrasts(argv=None):
+    Phykit.independent_contrasts(sys.argv[1:])
+
+
 def ancestral_state_reconstruction(argv=None):
     Phykit.ancestral_state_reconstruction(sys.argv[1:])
 
@@ -6656,6 +6809,10 @@ def phylogenetic_dimreduce(argv=None):
     Phykit.phylogenetic_ordination(sys.argv[1:])
 
 
+def phylo_heatmap(argv=None):
+    Phykit.phylo_heatmap(sys.argv[1:])
+
+
 def phylomorphospace(argv=None):
     Phykit.phylomorphospace(sys.argv[1:])
 

{phykit-2.1.44 → phykit-2.1.46}/phykit/service_factories.py

@@ -83,10 +83,12 @@ RelativeRateTest = _LazyServiceFactory("phykit.services.tree.relative_rate_test"
 ThresholdModel = _LazyServiceFactory("phykit.services.tree.threshold_model", "ThresholdModel")
 PolytomyTest = _LazyServiceFactory("phykit.services.tree.polytomy_test", "PolytomyTest")
 PrintTree = _LazyServiceFactory("phykit.services.tree.print_tree", "PrintTree")
+PhyloHeatmap = _LazyServiceFactory("phykit.services.tree.phylo_heatmap", "PhyloHeatmap")
 PruneTree = _LazyServiceFactory("phykit.services.tree.prune_tree", "PruneTree")
 QuartetPie = _LazyServiceFactory("phykit.services.tree.quartet_pie", "QuartetPie")
 RenameTreeTips = _LazyServiceFactory("phykit.services.tree.rename_tree_tips", "RenameTreeTips")
 FitDiscrete = _LazyServiceFactory("phykit.services.tree.fit_discrete", "FitDiscrete")
+IndependentContrasts = _LazyServiceFactory("phykit.services.tree.independent_contrasts", "IndependentContrasts")
 KuhnerFelsensteinDistance = _LazyServiceFactory("phykit.services.tree.kf_distance", "KuhnerFelsensteinDistance")
 RobinsonFouldsDistance = _LazyServiceFactory("phykit.services.tree.rf_distance", "RobinsonFouldsDistance")
 RootTree = _LazyServiceFactory("phykit.services.tree.root_tree", "RootTree")

{phykit-2.1.44 → phykit-2.1.46}/phykit/services/tree/__init__.py

@@ -27,9 +27,11 @@ _EXPORTS = {
     "RelativeRateTest": "relative_rate_test",
     "PolytomyTest": "polytomy_test",
     "PrintTree": "print_tree",
+    "PhyloHeatmap": "phylo_heatmap",
     "PruneTree": "prune_tree",
     "QuartetPie": "quartet_pie",
     "RenameTreeTips": "rename_tree_tips",
+    "IndependentContrasts": "independent_contrasts",
     "KuhnerFelsensteinDistance": "kf_distance",
     "RobinsonFouldsDistance": "rf_distance",
     "RootTree": "root_tree",

phykit-2.1.46/phykit/services/tree/independent_contrasts.py

@@ -0,0 +1,210 @@
+"""
+Phylogenetically independent contrasts (PIC).
+
+Computes Felsenstein's (1985) phylogenetically independent contrasts
+for a continuous trait on a phylogeny. Each internal node yields one
+contrast (standardized difference), producing n-1 contrasts for n tips.
+
+Cross-validated against R's ape::pic().
+"""
+import copy
+import sys
+from typing import Dict, List, Tuple
+
+import numpy as np
+
+from .base import Tree
+from ...helpers.json_output import print_json
+from ...errors import PhykitUserError
+
+
+class IndependentContrasts(Tree):
+    def __init__(self, args) -> None:
+        parsed = self.process_args(args)
+        super().__init__(tree_file_path=parsed["tree_file_path"])
+        self.trait_data_path = parsed["trait_data_path"]
+        self.json_output = parsed["json_output"]
+
+    def run(self) -> None:
+        tree = self.read_tree_file()
+        tree = copy.deepcopy(tree)
+        self._validate_tree(tree)
+
+        tree_tips = [t.name for t in tree.get_terminals()]
+        tip_traits = self._parse_trait_data(self.trait_data_path, tree_tips)
+
+        # Prune tree to shared taxa
+        shared = set(tip_traits.keys())
+        tips_to_prune = [t for t in tree_tips if t not in shared]
+        if tips_to_prune:
+            tree = self.prune_tree_using_taxa_list(tree, tips_to_prune)
+
+        # Resolve multifurcations (PIC requires fully dichotomous tree)
+        self._resolve_polytomies(tree)
+
+        contrasts, node_labels = self._compute_pic(tree, tip_traits)
+
+        if self.json_output:
+            self._print_json(contrasts, node_labels, tip_traits)
+        else:
+            self._print_text(contrasts, node_labels)
+
+    def process_args(self, args) -> Dict:
+        return dict(
+            tree_file_path=args.tree,
+            trait_data_path=args.trait_data,
+            json_output=getattr(args, "json", False),
+        )
+
+    def _validate_tree(self, tree) -> None:
+        tips = list(tree.get_terminals())
+        if len(tips) < 3:
+            raise PhykitUserError(
+                ["Tree must have at least 3 tips."], code=2
+            )
+        for clade in tree.find_clades():
+            if clade.branch_length is None and clade != tree.root:
+                clade.branch_length = 1e-8
+
+    def _parse_trait_data(
+        self, path: str, tree_tips: List[str]
+    ) -> Dict[str, float]:
+        """Parse two-column trait file (taxon<tab>value)."""
+        try:
+            with open(path) as f:
+                lines = f.readlines()
+        except FileNotFoundError:
+            raise PhykitUserError(
+                [f"{path} not found. Check filename and path."], code=2
+            )
+
+        traits = {}
+        for line in lines:
+            stripped = line.strip()
+            if not stripped or stripped.startswith("#"):
+                continue
+            parts = stripped.split("\t")
+            if len(parts) != 2:
+                continue
+            try:
+                traits[parts[0]] = float(parts[1])
+            except ValueError:
+                continue
+
+        shared = set(tree_tips) & set(traits.keys())
+        if len(shared) < 3:
+            raise PhykitUserError(
+                [
+                    f"Only {len(shared)} shared taxa between tree and trait file.",
+                    "At least 3 shared taxa are required.",
+                ],
+                code=2,
+            )
+
+        return {t: traits[t] for t in shared}
+
+    def _resolve_polytomies(self, tree) -> None:
+        """Resolve multifurcations by adding zero-length branches."""
+        for clade in tree.find_clades(order="postorder"):
+            while len(clade.clades) > 2:
+                # Take the last two children and merge them
+                from Bio.Phylo import Newick
+                child1 = clade.clades.pop()
+                child2 = clade.clades.pop()
+                new_internal = Newick.Clade(branch_length=0.0)
+                new_internal.clades = [child1, child2]
+                clade.clades.append(new_internal)
+
+    def _compute_pic(
+        self, tree, tip_traits: Dict[str, float]
+    ) -> Tuple[List[float], List[List[str]]]:
+        """Compute phylogenetically independent contrasts.
+
+        Felsenstein (1985) algorithm:
+        - Postorder traversal through tree
+        - At each internal node with children L, R:
+          contrast = (x_L - x_R) / sqrt(v_L + v_R)
+          x_node = (x_L/v_L + x_R/v_R) / (1/v_L + 1/v_R)
+          v_node += v_L * v_R / (v_L + v_R)
+
+        Returns (contrasts, node_tip_labels) where node_tip_labels[i]
+        is the list of tip names descending from the node that produced
+        contrast[i].
+        """
+        # Store trait values and effective branch lengths per node
+        node_val = {}
+        node_bl = {}  # effective branch length (adjusted during traversal)
+
+        # Initialize tips
+        for tip in tree.get_terminals():
+            if tip.name in tip_traits:
+                node_val[id(tip)] = tip_traits[tip.name]
+                node_bl[id(tip)] = tip.branch_length if tip.branch_length else 1e-8
+
+        contrasts = []
+        node_labels = []
+
+        for clade in tree.find_clades(order="postorder"):
+            if clade.is_terminal():
+                continue
+            if len(clade.clades) != 2:
+                continue
+
+            left, right = clade.clades
+            lid, rid = id(left), id(right)
+
+            if lid not in node_val or rid not in node_val:
+                continue
+
+            x_l = node_val[lid]
+            x_r = node_val[rid]
+            v_l = node_bl[lid]
+            v_r = node_bl[rid]
+
+            # Standardized contrast
+            contrast = (x_l - x_r) / np.sqrt(v_l + v_r)
+            contrasts.append(float(contrast))
+
+            # Tip labels for this node
+            tips_here = sorted(t.name for t in clade.get_terminals())
+            node_labels.append(tips_here)
+
+            # Weighted average trait value for this node
+            node_val[id(clade)] = (x_l / v_l + x_r / v_r) / (1.0 / v_l + 1.0 / v_r)
+
+            # Adjusted branch length
+            parent_bl = clade.branch_length if clade.branch_length else 0.0
+            node_bl[id(clade)] = parent_bl + (v_l * v_r) / (v_l + v_r)
+
+        return contrasts, node_labels
+
+    def _print_text(self, contrasts, node_labels):
+        print(f"Number of contrasts: {len(contrasts)}")
+        print()
+        print(f"{'Node':<6}{'Contrast':>12}  Tips")
+        print("-" * 60)
+        for i, (c, tips) in enumerate(zip(contrasts, node_labels), 1):
+            tips_str = ", ".join(tips[:3])
+            if len(tips) > 3:
+                tips_str += f", ... ({len(tips)} total)"
+            print(f"{i:<6}{c:>12.6f}  {tips_str}")
+        print()
+        print(f"Mean absolute contrast: {np.mean(np.abs(contrasts)):.6f}")
+        print(f"Variance of contrasts:  {np.var(contrasts, ddof=1):.6f}")
+
+    def _print_json(self, contrasts, node_labels, tip_traits):
+        nodes = []
+        for i, (c, tips) in enumerate(zip(contrasts, node_labels)):
+            nodes.append({
+                "node": i + 1,
+                "contrast": round(c, 6),
+                "tips": tips,
+            })
+        payload = {
+            "n_taxa": len(tip_traits),
+            "n_contrasts": len(contrasts),
+            "contrasts": nodes,
+            "mean_absolute_contrast": round(float(np.mean(np.abs(contrasts))), 6),
+            "variance_of_contrasts": round(float(np.var(contrasts, ddof=1)), 6),
+        }
+        print_json(payload)