phykit 2.1.69__tar.gz → 2.1.70__tar.gz

{phykit-2.1.69 → phykit-2.1.70}/PKG-INFO

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

{phykit-2.1.69 → phykit-2.1.70}/phykit/phykit.py

@@ -3442,6 +3442,10 @@ class Phykit:
                                             gene trees for discordance-aware
                                             VCV computation
 
+                --multivariate              compute K_mult (Adams 2014)
+                                            for multivariate traits using
+                                            a multi-column TSV file
+
                 --json                      optional argument to output
                                             results as JSON
                 """
@@ -3476,6 +3480,10 @@ class Phykit:
             "-g", "--gene-trees", type=str, required=False, default=None,
             help=SUPPRESS, metavar=""
         )
+        parser.add_argument(
+            "--multivariate", action="store_true", default=False,
+            help=SUPPRESS,
+        )
         _add_json_argument(parser)
         _run_service(parser, argv, PhylogeneticSignal)
 

{phykit-2.1.69 → phykit-2.1.70}/phykit/services/tree/phylogenetic_signal.py

@@ -19,6 +19,7 @@ class PhylogeneticSignal(Tree):
         self.permutations = parsed["permutations"]
         self.json_output = parsed["json_output"]
         self.gene_trees_path = parsed["gene_trees_path"]
+        self.multivariate = parsed["multivariate"]
 
     def run(self) -> None:
         from .vcv_utils import build_vcv_matrix, build_discordance_vcv, parse_gene_trees
@@ -27,6 +28,53 @@ class PhylogeneticSignal(Tree):
         self._validate_tree(tree)
 
         tree_tips = self.get_tip_names_from_tree(tree)
+
+        if self.multivariate:
+            if self.method == "lambda":
+                raise PhykitUserError(
+                    [
+                        "K_mult (--multivariate) only works with Blomberg's K framework.",
+                        "Pagel's lambda is not supported for multivariate data.",
+                        "Use --method blombergs_k (the default) instead.",
+                    ],
+                    code=2,
+                )
+
+            trait_names, traits_multi = self._parse_multi_trait_file(
+                self.trait_data_path, tree_tips
+            )
+            ordered_names = sorted(traits_multi.keys())
+
+            if self.gene_trees_path:
+                gene_trees = parse_gene_trees(self.gene_trees_path)
+                vcv, vcv_meta = build_discordance_vcv(tree, gene_trees, ordered_names)
+                shared = vcv_meta["shared_taxa"]
+                if set(shared) != set(ordered_names):
+                    traits_multi = {k: traits_multi[k] for k in shared}
+                    ordered_names = shared
+            else:
+                vcv = build_vcv_matrix(tree, ordered_names)
+                vcv_meta = None
+
+            p = len(trait_names)
+            Y = np.array(
+                [[traits_multi[name][j] for j in range(p)] for name in ordered_names]
+            )
+
+            result = self._kmult(Y, vcv, self.permutations)
+            if vcv_meta is not None:
+                result["vcv_metadata"] = vcv_meta
+            if self.json_output:
+                print_json(result)
+                return
+            print(
+                f"{round(result['K_mult'], 4)}\t"
+                f"{round(result['p_value'], 4)}\t"
+                f"{result['n_traits']}\t"
+                f"{result['permutations']}"
+            )
+            return
+
         traits = self._parse_trait_file(self.trait_data_path, tree_tips)
 
         ordered_names = sorted(traits.keys())
@@ -84,6 +132,7 @@ class PhylogeneticSignal(Tree):
             permutations=getattr(args, "permutations", 1000),
             json_output=getattr(args, "json", False),
             gene_trees_path=getattr(args, "gene_trees", None),
+            multivariate=getattr(args, "multivariate", False),
         )
 
     def _validate_tree(self, tree) -> None:
@@ -171,6 +220,200 @@ class PhylogeneticSignal(Tree):
 
         return {taxon: traits[taxon] for taxon in shared}
 
+    def _parse_multi_trait_file(
+        self, path: str, tree_tips: List[str]
+    ) -> Tuple[List[str], Dict[str, List[float]]]:
+        """Parse a multi-column TSV trait file with header row.
+
+        Format:
+            taxon	trait1	trait2	trait3
+            A	1.0	2.0	3.0
+            B	0.5	1.5	2.5
+
+        Returns (trait_names, {taxon: [val1, val2, ...]}).
+        """
+        try:
+            with open(path) as f:
+                lines = f.readlines()
+        except FileNotFoundError:
+            raise PhykitUserError(
+                [
+                    f"{path} corresponds to no such file or directory.",
+                    "Please check filename and pathing",
+                ],
+                code=2,
+            )
+
+        data_lines = []
+        for line in lines:
+            stripped = line.strip()
+            if not stripped or stripped.startswith("#"):
+                continue
+            data_lines.append(stripped)
+
+        if len(data_lines) < 2:
+            raise PhykitUserError(
+                [
+                    "Multi-trait file must have a header row and at least one data row.",
+                ],
+                code=2,
+            )
+
+        header_parts = data_lines[0].split("\t")
+        n_cols = len(header_parts)
+        if n_cols < 2:
+            raise PhykitUserError(
+                [
+                    "Header must have at least 2 columns (taxon + at least 1 trait).",
+                ],
+                code=2,
+            )
+        trait_names = header_parts[1:]
+
+        traits = {}
+        for line_idx, line in enumerate(data_lines[1:], 2):
+            parts = line.split("\t")
+            if len(parts) != n_cols:
+                raise PhykitUserError(
+                    [
+                        f"Line {line_idx} has {len(parts)} columns; expected {n_cols}.",
+                        f"Each line should have: taxon_name<tab>{'<tab>'.join(['trait'] * len(trait_names))}",
+                    ],
+                    code=2,
+                )
+            taxon = parts[0]
+            values = []
+            for i, val_str in enumerate(parts[1:]):
+                try:
+                    values.append(float(val_str))
+                except ValueError:
+                    raise PhykitUserError(
+                        [
+                            f"Non-numeric trait value '{val_str}' for taxon '{taxon}' "
+                            f"(trait '{trait_names[i]}') on line {line_idx}.",
+                        ],
+                        code=2,
+                    )
+            traits[taxon] = values
+
+        tree_tip_set = set(tree_tips)
+        trait_taxa_set = set(traits.keys())
+        shared = tree_tip_set & trait_taxa_set
+
+        tree_only = tree_tip_set - trait_taxa_set
+        trait_only = trait_taxa_set - tree_tip_set
+
+        if tree_only:
+            print(
+                f"Warning: {len(tree_only)} taxa in tree but not in trait file: "
+                f"{', '.join(sorted(tree_only))}",
+                file=sys.stderr,
+            )
+        if trait_only:
+            print(
+                f"Warning: {len(trait_only)} taxa in trait file but not in tree: "
+                f"{', '.join(sorted(trait_only))}",
+                file=sys.stderr,
+            )
+
+        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,
+            )
+
+        filtered = {taxon: traits[taxon] for taxon in shared}
+        return trait_names, filtered
+
+    def _kmult(
+        self, Y: np.ndarray, vcv: np.ndarray, n_perm: int
+    ) -> Dict:
+        """Multivariate K (Adams 2014).
+
+        Y: n x p matrix of trait values (n taxa, p traits)
+        vcv: n x n phylogenetic VCV matrix
+
+        K_mult = observed_ratio / expected_ratio
+
+        Where:
+        - observed_ratio = MSE_obs / MSE_phylo
+        - MSE_obs = sum of squared distances from each species to the
+                    phylogenetic mean (using Euclidean distance in trait space)
+        - MSE_phylo = sum of squared phylogenetically weighted distances
+                      (using C_inv weighting)
+        - expected_ratio = same formula as univariate K but uses trace
+                          operations on the multivariate analogue
+        """
+        n, p = Y.shape
+        ones = np.ones(n)
+
+        C = vcv.copy()
+        C_inv = np.linalg.inv(C)
+        sum_C_inv = float(ones @ C_inv @ ones)
+
+        # GLS estimate of phylogenetic mean (p-dimensional vector)
+        # a_hat = (1^T C^{-1} 1)^{-1} * (1^T C^{-1} Y)
+        a_hat = (ones @ C_inv @ Y) / sum_C_inv  # shape: (p,)
+
+        # Residual matrix: each row is (Y_i - a_hat)
+        E = Y - a_hat  # n x p
+
+        # MSE_obs: sum of squared Euclidean distances from each species to phylo mean
+        # = trace(E^T @ E)
+        MSE_obs = np.trace(E.T @ E)
+
+        # MSE_phylo: phylogenetically-weighted version
+        # = trace(E^T @ C_inv @ E)
+        MSE_phylo = np.trace(E.T @ C_inv @ E)
+
+        # Observed ratio
+        if MSE_phylo == 0:
+            observed_ratio = 0.0
+        else:
+            observed_ratio = MSE_obs / MSE_phylo
+
+        # Expected ratio under BM (same as univariate, from Blomberg et al. 2003)
+        expected_ratio = (np.trace(C) - n / sum_C_inv) / (n - 1)
+
+        # K_mult
+        if expected_ratio == 0:
+            K_mult = 0.0
+        else:
+            K_mult = observed_ratio / expected_ratio
+
+        # Permutation test: shuffle rows of Y, recompute K_mult
+        rng = np.random.default_rng(seed=42)
+        k_perm = np.empty(n_perm)
+        for perm_i in range(n_perm):
+            # Permute rows (species) of Y -- keeps trait correlations intact
+            perm_idx = rng.permutation(n)
+            Y_perm = Y[perm_idx]
+
+            a_p = (ones @ C_inv @ Y_perm) / sum_C_inv
+            E_p = Y_perm - a_p
+
+            MSE_obs_p = np.trace(E_p.T @ E_p)
+            MSE_phylo_p = np.trace(E_p.T @ C_inv @ E_p)
+
+            if MSE_phylo_p == 0:
+                obs_ratio_p = 0.0
+            else:
+                obs_ratio_p = MSE_obs_p / MSE_phylo_p
+
+            k_perm[perm_i] = obs_ratio_p / expected_ratio if expected_ratio != 0 else 0.0
+
+        p_value = float(np.mean(k_perm >= K_mult))
+
+        return dict(
+            K_mult=float(K_mult),
+            p_value=p_value,
+            permutations=n_perm,
+            n_traits=p,
+        )
+
     def _build_vcv_matrix(
         self, tree, ordered_names: List[str]
     ) -> np.ndarray:

phykit-2.1.70/phykit/version.py

@@ -0,0 +1 @@
+__version__ = "2.1.70"

{phykit-2.1.69 → phykit-2.1.70}/phykit.egg-info/PKG-INFO

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

phykit-2.1.69/phykit/version.py

@@ -1 +0,0 @@
-__version__ = "2.1.69"