phykit 2.1.90__tar.gz → 2.1.93__tar.gz

{phykit-2.1.90 → phykit-2.1.93}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.1
 Name: phykit
-Version: 2.1.90
+Version: 2.1.93
 Home-page: https://github.com/jlsteenwyk/phykit
 Author: Jacob L. Steenwyk
 Author-email: jlsteenwyk@gmail.com
@@ -15,22 +15,6 @@ Classifier: Topic :: Scientific/Engineering
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE.md
-Requires-Dist: biopython>=1.82
-Requires-Dist: matplotlib>=3.7.0
-Requires-Dist: numpy>=1.24.0
-Requires-Dist: scipy>=1.11.3
-Requires-Dist: scikit-learn>=1.4.2
-Requires-Dist: umap-learn>=0.5.0
-Requires-Dist: tqdm>=4.65.0
-Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
-Dynamic: license-file
-Dynamic: requires-dist
-Dynamic: requires-python
 
 <p align="center">
   <a href="https://github.com/jlsteenwyk/phykit">

{phykit-2.1.90 → phykit-2.1.93}/phykit/cli_registry.py

@@ -83,6 +83,10 @@ ALIAS_TO_HANDLER: Dict[str, str] = {
     "ctree": "consensus_tree",
     "degree_of_violation_of_a_molecular_clock": "dvmc",
     "evo_rate": "evolutionary_rate",
+    "faiths_pd": "faiths_pd",
+    "faith_pd": "faiths_pd",
+    "fpd": "faiths_pd",
+    "phylo_diversity": "faiths_pd",
     "clan_check": "hidden_paralogy_check",
     "ibs": "internal_branch_stats",
     "il": "internode_labeler",

{phykit-2.1.90 → phykit-2.1.93}/phykit/phykit.py

@@ -230,6 +230,9 @@ class Phykit:
                     - determines if a set of tip names are monophyletic
                 nearest_neighbor_interchange (alias: nni)
                     - make nearest neighbor interchange moves on a tree
+                faiths_pd (alias: faith_pd; fpd; phylo_diversity)
+                    - calculate Faith's phylogenetic diversity for a
+                      community of tips
                 patristic_distances (alias: pd)
                     - calculate all pairwise distances between tips in a tree
                 phylogenetic_signal (alias: phylo_signal; ps)
@@ -3739,10 +3742,19 @@ class Phykit:
                 f"""\
                 {help_header}
 
-                Generate all nearest neighbor interchange moves for a binary
-                rooted tree.
+                Generate nearest neighbor interchange (NNI) moves for a
+                binary rooted tree.
 
-                The output file will also include the original phylogeny.
+                By default, all NNI rearrangements are emitted. Pass
+                --branch (a comma-separated pair of taxa) or --branches
+                (a file with one pair per line) to restrict output to the
+                two NNI rearrangements around a specific internal branch.
+                The branch is identified as the edge leading to the MRCA
+                of the supplied taxa. Useful for branch-by-branch
+                likelihood comparison in IQ-TREE / RAxML.
+
+                The output file includes the input phylogeny at the top
+                unless --no-input-tree is supplied.
 
                 Aliases:
                   nearest_neighbor_interchange, nni
@@ -3750,22 +3762,49 @@ class Phykit:
                   pk_nearest_neighbor_interchange, pk_nni
 
                 Usage:
-                phykit nearest_neighbor_interchange <tree> [-o/--output <output_file>] [--json]
+                phykit nearest_neighbor_interchange <tree>
+                  [-o/--output <output_file>] [--branch A,B]
+                  [--branches <file>] [--no-input-tree] [--json]
 
                 Options
                 =====================================================
-                <tree>                      first argument after 
+                <tree>                      first argument after
                                             function name should be
                                             a tree file
 
                 -o/--output                 name of output file that will
                                             contain all trees with the
                                             nearest neighbor interchange
-                                            moves. 
-                                            Default output will have 
+                                            moves.
+                                            Default output will have
                                             the same name as the input
-                                            file but with the suffix 
-                                            ".NNIs"
+                                            file but with the suffix
+                                            ".nnis"
+
+                --branch                    optional argument. Two taxa
+                                            separated by a comma
+                                            (e.g., --branch A,B) whose
+                                            MRCA defines the internal
+                                            branch to rearrange. Emits
+                                            the two alternative NNI
+                                            topologies for that branch.
+
+                --branches                  optional argument. Path to a
+                                            file with one taxon pair per
+                                            line (comma- or tab-
+                                            separated). Lines may
+                                            optionally start with a
+                                            label followed by the two
+                                            taxa, in which case the
+                                            label is echoed in the
+                                            --json report. Lines that
+                                            are blank or start with #
+                                            are ignored. Each pair
+                                            yields two NNI trees.
+
+                --no-input-tree             optional argument. Omit the
+                                            input phylogeny from the
+                                            top of the output file.
 
                 --json                      optional argument to output
                                             results as JSON
@@ -3774,9 +3813,78 @@ class Phykit:
         )
         parser.add_argument("tree", type=str, help=SUPPRESS)
         parser.add_argument("-o", "--output", type=str, required=False, help=SUPPRESS)
+        parser.add_argument("--branch", type=str, default=None, help=SUPPRESS)
+        parser.add_argument("--branches", type=str, default=None, help=SUPPRESS)
+        parser.add_argument(
+            "--no-input-tree",
+            action="store_true",
+            default=False,
+            help=SUPPRESS,
+        )
         _add_json_argument(parser)
         _run_service(parser, argv, NearestNeighborInterchange)
 
+    @staticmethod
+    def faiths_pd(argv):
+        parser = _new_parser(
+            description=textwrap.dedent(
+                f"""\
+                {help_header}
+
+                Calculate Faith's phylogenetic diversity (PD) for a
+                community of tips on a phylogeny.
+
+                Faith's PD is the sum of branch lengths in the minimum
+                subtree that connects a set of taxa. By default, the
+                path from the community's most recent common ancestor
+                up to the tree root is included, matching Faith (1992)
+                and picante::pd(..., include.root = TRUE). Use
+                --exclude-root to sum only the branches of the induced
+                subtree rooted at the MRCA, matching
+                picante::pd(..., include.root = FALSE).
+
+                Aliases:
+                  faiths_pd, faith_pd, fpd, phylo_diversity
+                Command line interfaces:
+                  pk_faiths_pd, pk_faith_pd, pk_fpd, pk_phylo_diversity
+
+                Usage:
+                phykit faiths_pd <tree> -t/--taxa <taxa_file>
+                  [--exclude-root] [--json]
+
+                Options
+                =====================================================
+                <tree>                      first argument after
+                                            function name should be
+                                            a tree file
+
+                -t/--taxa                   file with one tip label per
+                                            line defining the community
+
+                --exclude-root              sum only branches of the
+                                            induced subtree rooted at
+                                            the community MRCA; by
+                                            default the path up to the
+                                            tree root is included
+
+                --json                      optional argument to output
+                                            results as JSON
+                """
+            ),
+        )
+        parser.add_argument("tree", type=str, help=SUPPRESS)
+        parser.add_argument(
+            "-t", "--taxa", type=str, required=True, help=SUPPRESS, metavar=""
+        )
+        parser.add_argument(
+            "--exclude-root",
+            dest="exclude_root",
+            action="store_true",
+            help=SUPPRESS,
+        )
+        _add_json_argument(parser)
+        _run_service(parser, argv, FaithsPD)
+
     @staticmethod
     def patristic_distances(argv):
         parser = _new_parser(
@@ -6887,29 +6995,38 @@ class Phykit:
 
                 Usage:
                 phykit prune_tree <tree> <list_of_taxa> [-o/--output <output_file>
-                -k/--keep] [--json]
+                -k/--keep] [--ignore-branch-labels] [--json]
 
                 Options
                 =====================================================
-                <tree>                      first argument after 
+                <tree>                      first argument after
                                             function name should be
                                             a tree file
 
                 <list_of_taxa>              single column file with the
                                             names of the tips to remove
-                                            from the phylogeny 
+                                            from the phylogeny
 
                 -o/--output                 name of output file for the
-                                            pruned phylogeny. 
-                                            Default output will have 
+                                            pruned phylogeny.
+                                            Default output will have
                                             the same name as the input
-                                            file but with the suffix 
+                                            file but with the suffix
                                             ".pruned"
 
                 -k/--keep                   optional argument. If used
                                             instead of pruning taxa in
                                             <list_of_taxa>, keep them
 
+                --ignore-branch-labels      optional argument. Strip
+                                            HyPhy/aBSREL-style {{...}}
+                                            branch labels (e.g.,
+                                            "Hydlep{{FG}}") from tip
+                                            names when matching
+                                            against <list_of_taxa>.
+                                            The labels are preserved
+                                            in the output tree.
+
                 --json                      optional argument to output
                                             results as JSON
                 """
@@ -6921,6 +7038,12 @@ class Phykit:
         parser.add_argument(
             "-k", "--keep", type=str2bool, nargs="?", default=False, help=SUPPRESS
         )
+        parser.add_argument(
+            "--ignore-branch-labels",
+            action="store_true",
+            default=False,
+            help=SUPPRESS,
+        )
         _add_json_argument(parser)
         _run_service(parser, argv, PruneTree)
 
@@ -9270,6 +9393,10 @@ def nearest_neighbor_interchange(argv=None):
     Phykit.nearest_neighbor_interchange(sys.argv[1:])
 
 
+def faiths_pd(argv=None):
+    Phykit.faiths_pd(sys.argv[1:])
+
+
 def patristic_distances(argv=None):
     Phykit.patristic_distances(sys.argv[1:])
 

{phykit-2.1.90 → phykit-2.1.93}/phykit/service_factories.py

@@ -66,6 +66,7 @@ NeighborNet = _LazyServiceFactory("phykit.services.tree.neighbor_net", "Neighbor
 ConsensusTree = _LazyServiceFactory("phykit.services.tree.consensus_tree", "ConsensusTree")
 DVMC = _LazyServiceFactory("phykit.services.tree.dvmc", "DVMC")
 EvolutionaryRate = _LazyServiceFactory("phykit.services.tree.evolutionary_rate", "EvolutionaryRate")
+FaithsPD = _LazyServiceFactory("phykit.services.tree.faiths_pd", "FaithsPD")
 HiddenParalogyCheck = _LazyServiceFactory("phykit.services.tree.hidden_paralogy_check", "HiddenParalogyCheck")
 InternalBranchStats = _LazyServiceFactory("phykit.services.tree.internal_branch_stats", "InternalBranchStats")
 InternodeLabeler = _LazyServiceFactory("phykit.services.tree.internode_labeler", "InternodeLabeler")

{phykit-2.1.90 → phykit-2.1.93}/phykit/services/tree/__init__.py

@@ -15,6 +15,7 @@ _EXPORTS = {
     "DiscordanceAsymmetry": "discordance_asymmetry",
     "EvolutionaryRate": "evolutionary_rate",
     "EvoTempoMap": "evo_tempo_map",
+    "FaithsPD": "faiths_pd",
     "FitDiscrete": "fit_discrete",
     "HiddenParalogyCheck": "hidden_paralogy_check",
     "Hybridization": "hybridization",

phykit-2.1.93/phykit/services/tree/faiths_pd.py

@@ -0,0 +1,148 @@
+"""
+Faith's phylogenetic diversity (PD).
+
+Given a tree and a community (list of tip labels), sum the branch
+lengths of the minimum subtree connecting the community. When
+``include_root`` is True (default), the sum includes the path from
+the community's MRCA up to the tree root, matching Faith (1992) and
+``picante::pd(..., include.root = TRUE)``.
+"""
+from typing import Dict, List, Tuple
+
+from .base import Tree
+from ...errors import PhykitUserError
+from ...helpers.files import read_single_column_file_to_list
+from ...helpers.json_output import print_json
+
+
+class FaithsPD(Tree):
+    def __init__(self, args) -> None:
+        parsed = self.process_args(args)
+        super().__init__(tree_file_path=parsed["tree_file_path"])
+        self.taxa_file = parsed["taxa_file"]
+        self.include_root = parsed["include_root"]
+        self.json_output = parsed["json_output"]
+
+    def process_args(self, args) -> Dict:
+        return dict(
+            tree_file_path=args.tree,
+            taxa_file=args.taxa,
+            include_root=not getattr(args, "exclude_root", False),
+            json_output=getattr(args, "json", False),
+        )
+
+    def run(self) -> None:
+        tree = self.read_tree_file()
+        taxa = self._load_taxa(self.taxa_file)
+        pd_value, n_tips = self.calculate_faiths_pd(
+            tree, taxa, include_root=self.include_root
+        )
+        pd_rounded = round(pd_value, 4)
+
+        if self.json_output:
+            print_json(
+                dict(
+                    faiths_pd=pd_rounded,
+                    n_taxa=n_tips,
+                    include_root=self.include_root,
+                )
+            )
+            return
+        print(pd_rounded)
+
+    @staticmethod
+    def _load_taxa(taxa_file: str) -> List[str]:
+        raw = read_single_column_file_to_list(taxa_file)
+        seen = set()
+        taxa: List[str] = []
+        for name in raw:
+            if not name or name in seen:
+                continue
+            seen.add(name)
+            taxa.append(name)
+        if not taxa:
+            raise PhykitUserError(
+                [f"No taxa found in {taxa_file}."], code=2,
+            )
+        return taxa
+
+    def calculate_faiths_pd(
+        self, tree, taxa: List[str], include_root: bool = True,
+    ) -> Tuple[float, int]:
+        """Compute Faith's PD for ``taxa`` on ``tree``.
+
+        Returns (pd, n_taxa). n_taxa is the deduplicated community size.
+        """
+        self.validate_tree(tree, min_tips=2, require_branch_lengths=True,
+                           context="Faith's PD")
+
+        seen: set = set()
+        deduped: List[str] = []
+        for name in taxa:
+            if name and name not in seen:
+                seen.add(name)
+                deduped.append(name)
+        taxa = deduped
+        if not taxa:
+            raise PhykitUserError(
+                ["Community must contain at least one taxon."], code=2,
+            )
+
+        tip_map = {t.name: t for t in tree.get_terminals()}
+        missing = [name for name in taxa if name not in tip_map]
+        if missing:
+            sample = ", ".join(sorted(missing)[:5])
+            suffix = f" ... ({len(missing)} total)" if len(missing) > 5 else ""
+            raise PhykitUserError(
+                [
+                    "Taxa not found in tree:",
+                    sample + suffix,
+                ],
+                code=2,
+            )
+
+        community_tips = [tip_map[name] for name in taxa]
+
+        if len(community_tips) == 1:
+            # Single-tip community: PD with include_root=True is the path
+            # length from the root to that tip; with include_root=False it
+            # is 0 (no induced subtree). picante returns NA for the latter;
+            # we return 0 for programmatic convenience.
+            if not include_root:
+                return 0.0, 1
+            path = tree.get_path(community_tips[0])
+            return (
+                sum((c.branch_length or 0.0) for c in path),
+                1,
+            )
+
+        if include_root:
+            start_clade = tree.root
+        else:
+            mrca = tree.common_ancestor(community_tips)
+            # If the MRCA is the root, include.root=False is equivalent
+            # to include.root=True because there is no branch leading to
+            # the MRCA to subtract (matches picante).
+            start_clade = mrca
+
+        total = 0.0
+        seen_ids = set()
+        for tip in community_tips:
+            # Skip clades at or above start_clade. For include_root=True,
+            # start_clade is the root, which is never in get_path.
+            path = tree.get_path(tip)
+            if start_clade is not tree.root:
+                try:
+                    idx = path.index(start_clade)
+                    path = path[idx + 1:]
+                except ValueError:
+                    # start_clade (MRCA) not on path - defensive; shouldn't happen
+                    pass
+            for clade in path:
+                cid = id(clade)
+                if cid in seen_ids:
+                    continue
+                seen_ids.add(cid)
+                total += clade.branch_length or 0.0
+
+        return total, len(community_tips)