phykit 2.1.82__tar.gz → 2.1.84__tar.gz

{phykit-2.1.82 → phykit-2.1.84}/PKG-INFO

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

{phykit-2.1.82 → phykit-2.1.84}/phykit/cli_registry.py

@@ -55,6 +55,9 @@ ALIAS_TO_HANDLER: Dict[str, str] = {
     "sum_of_pairs_score": "sum_of_pairs_score",
     "sops": "sum_of_pairs_score",
     "sop": "sum_of_pairs_score",
+    "phylo_path": "phylo_path",
+    "ppath": "phylo_path",
+    "phylopath": "phylo_path",
     "phylo_anova": "phylo_anova",
     "panova": "phylo_anova",
     "phylo_manova": "phylo_anova",
@@ -214,6 +217,9 @@ ALIAS_TO_HANDLER: Dict[str, str] = {
     "tree_landscape": "tree_space",
     "tgroups": "taxon_groups",
     "shared_taxa": "taxon_groups",
+    "occupancy_filter": "occupancy_filter",
+    "occ_filter": "occupancy_filter",
+    "filter_occupancy": "occupancy_filter",
     # Helper aliases
     "create_concat": "create_concatenation_matrix",
     "cc": "create_concatenation_matrix",

phykit-2.1.84/phykit/helpers/pgls_utils.py

@@ -0,0 +1,181 @@
+"""
+Shared PGLS (Phylogenetic Generalized Least Squares) utilities.
+
+Provides reusable functions for:
+- Pagel's lambda estimation via ML
+- Concentrated PGLS log-likelihood
+- GLS model fitting
+- Lambda upper bound computation
+
+Used by phylogenetic_regression, phylo_path, phylogenetic_signal,
+phylogenetic_ordination, fit_continuous, and other comparative methods.
+"""
+from typing import Tuple
+
+import numpy as np
+from scipy.optimize import minimize_scalar
+
+from ..errors import PhykitUserError
+
+
+def max_lambda(tree) -> float:
+    """Compute the upper bound for Pagel's lambda.
+
+    For ultrametric trees, returns max_tip_height / max_parent_height.
+    For non-ultrametric trees, returns 1.0.
+    """
+    tips = tree.get_terminals()
+    root = tree.root
+    tip_heights = [tree.distance(root, tip) for tip in tips]
+    max_tip_height = max(tip_heights)
+    min_tip_height = min(tip_heights)
+
+    is_ultrametric = (max_tip_height - min_tip_height) / max_tip_height < 1e-6
+
+    if not is_ultrametric:
+        return 1.0
+
+    max_parent_height = 0.0
+    for clade in tree.find_clades(order="level"):
+        if clade == root:
+            continue
+        node_height = tree.distance(root, clade)
+        parent_height = node_height - (clade.branch_length or 0.0)
+        if parent_height > max_parent_height:
+            max_parent_height = parent_height
+
+    if max_parent_height == 0.0:
+        return 1.0
+
+    return max_tip_height / max_parent_height
+
+
+def pgls_log_likelihood(
+    y: np.ndarray, X: np.ndarray, C: np.ndarray
+) -> float:
+    """Concentrated log-likelihood with beta and sigma^2 profiled out.
+
+    Parameters
+    ----------
+    y : response vector (n,)
+    X : design matrix (n, p)
+    C : phylogenetic VCV matrix (n, n), possibly lambda-transformed
+    """
+    n = len(y)
+    try:
+        C_inv = np.linalg.inv(C)
+        XtCiX = X.T @ C_inv @ X
+        XtCiX_inv = np.linalg.inv(XtCiX)
+    except np.linalg.LinAlgError:
+        return -1e20
+
+    beta_hat = XtCiX_inv @ X.T @ C_inv @ y
+    e = y - X @ beta_hat
+    sigma2_ml = float(e @ C_inv @ e) / n
+
+    sign, logdet_C = np.linalg.slogdet(C)
+    if sign <= 0 or sigma2_ml <= 0:
+        return -1e20
+
+    ll = -0.5 * (
+        n * np.log(2 * np.pi) + n * np.log(sigma2_ml) + logdet_C + n
+    )
+    return float(ll)
+
+
+def estimate_lambda(
+    y: np.ndarray,
+    X: np.ndarray,
+    vcv: np.ndarray,
+    max_lam: float = 1.0,
+) -> Tuple[float, float]:
+    """Optimize Pagel's lambda via ML using multi-interval bounded search.
+
+    Parameters
+    ----------
+    y : response vector (n,)
+    X : design matrix (n, p)
+    vcv : phylogenetic VCV matrix (n, n)
+    max_lam : upper bound for lambda (default 1.0)
+
+    Returns
+    -------
+    (lambda_hat, log_likelihood_at_lambda)
+    """
+    diag_vals = np.diag(vcv).copy()
+    niter = 10
+
+    def neg_ll(lam):
+        C_lam = vcv * lam
+        np.fill_diagonal(C_lam, diag_vals)
+        try:
+            ll = pgls_log_likelihood(y, X, C_lam)
+            return -ll
+        except (np.linalg.LinAlgError, FloatingPointError, ValueError):
+            return 1e10
+
+    bounds_lo = np.linspace(0, max_lam - max_lam / niter, niter)
+    bounds_hi = np.linspace(max_lam / niter, max_lam, niter)
+
+    best_ll = -np.inf
+    lambda_hat = 0.0
+    for lo, hi in zip(bounds_lo, bounds_hi):
+        res = minimize_scalar(neg_ll, bounds=(lo, hi), method="bounded")
+        ll_val = -res.fun
+        if ll_val > best_ll:
+            best_ll = ll_val
+            lambda_hat = res.x
+
+    # Compute log-likelihood at fitted lambda
+    C_fitted = vcv * lambda_hat
+    np.fill_diagonal(C_fitted, diag_vals)
+    ll_fitted = pgls_log_likelihood(y, X, C_fitted)
+
+    return float(lambda_hat), float(ll_fitted)
+
+
+def fit_gls(
+    y: np.ndarray, X: np.ndarray, C_inv: np.ndarray
+) -> Tuple[np.ndarray, np.ndarray, float, np.ndarray]:
+    """GLS estimation: beta_hat = (X' C_inv X)^{-1} X' C_inv y.
+
+    Parameters
+    ----------
+    y : response vector (n,)
+    X : design matrix (n, p)
+    C_inv : inverse of phylogenetic VCV matrix (n, n)
+
+    Returns
+    -------
+    (beta_hat, residuals, sigma2_reml, var_beta)
+    """
+    n, k_plus_1 = X.shape
+    XtCiX = X.T @ C_inv @ X
+    try:
+        XtCiX_inv = np.linalg.inv(XtCiX)
+    except np.linalg.LinAlgError:
+        raise PhykitUserError(
+            [
+                "Singular design matrix: cannot estimate coefficients.",
+                "Check that predictors are not collinear.",
+            ],
+            code=2,
+        )
+
+    beta_hat = XtCiX_inv @ X.T @ C_inv @ y
+    residuals = y - X @ beta_hat
+
+    df_resid = n - k_plus_1
+    sigma2 = float(residuals @ C_inv @ residuals) / max(df_resid, 1)
+
+    var_beta = sigma2 * XtCiX_inv
+
+    return beta_hat, residuals, sigma2, var_beta
+
+
+def apply_lambda(vcv: np.ndarray, lambda_val: float) -> np.ndarray:
+    """Apply Pagel's lambda to a VCV matrix (scale off-diagonals, keep diagonal)."""
+    diag_vals = np.diag(vcv).copy()
+    vcv_lam = vcv * lambda_val
+    np.fill_diagonal(vcv_lam, diag_vals)
+    return vcv_lam

{phykit-2.1.82 → phykit-2.1.84}/phykit/helpers/plot_config.py

@@ -248,3 +248,119 @@ def compute_node_x_cladogram(tree, parent_map):
         else:
             node_x[cid] = float(node_depth.get(cid, 0)) * step_size
     return node_x
+
+
+# ---- Shared rectangular tree plotting utilities ----
+
+
+def build_parent_map(tree):
+    """Build a dict mapping child node id -> parent node."""
+    parent_map = {}
+    for clade in tree.find_clades(order="preorder"):
+        for child in clade.clades:
+            parent_map[id(child)] = clade
+    return parent_map
+
+
+def compute_node_positions(tree, parent_map, cladogram=False):
+    """Compute (node_x, node_y) for a rectangular tree layout.
+
+    Parameters
+    ----------
+    tree : Bio.Phylo tree
+    parent_map : dict from build_parent_map()
+    cladogram : if True, use equal-depth x-positions (tips aligned)
+
+    Returns
+    -------
+    (node_x, node_y) : dicts mapping node id -> coordinate
+    """
+    import numpy as np
+
+    tips = list(tree.get_terminals())
+    root = tree.root
+
+    node_y = {}
+    for i, tip in enumerate(tips):
+        node_y[id(tip)] = i
+
+    if cladogram:
+        node_x = compute_node_x_cladogram(tree, parent_map)
+    else:
+        node_x = {}
+        for clade in tree.find_clades(order="preorder"):
+            if clade == root:
+                node_x[id(clade)] = 0.0
+            elif id(clade) in parent_map:
+                parent = parent_map[id(clade)]
+                t = clade.branch_length if clade.branch_length else 0.0
+                node_x[id(clade)] = node_x.get(id(parent), 0.0) + t
+
+    for clade in tree.find_clades(order="postorder"):
+        if not clade.is_terminal() and id(clade) not in node_y:
+            child_ys = [
+                node_y[id(c)] for c in clade.clades if id(c) in node_y
+            ]
+            if child_ys:
+                node_y[id(clade)] = float(np.mean(child_ys))
+            else:
+                node_y[id(clade)] = 0.0
+
+    return node_x, node_y
+
+
+def draw_tree_branches(
+    ax, tree, node_x, node_y, parent_map,
+    color="black", lw=1.5, vertical_color="black", vertical_lw=0.8,
+):
+    """Draw rectangular tree branches (horizontal + vertical connectors).
+
+    Override color per branch by passing a callable for `color`:
+        color=lambda clade: "red" if ... else "black"
+    """
+    root = tree.root
+    for clade in tree.find_clades(order="preorder"):
+        if clade == root:
+            continue
+        if id(clade) not in parent_map:
+            continue
+        parent = parent_map[id(clade)]
+        if id(parent) not in node_x or id(clade) not in node_x:
+            continue
+
+        x0 = node_x[id(parent)]
+        x1 = node_x[id(clade)]
+        y0 = node_y.get(id(parent), 0)
+        y1 = node_y.get(id(clade), 0)
+
+        branch_color = color(clade) if callable(color) else color
+        ax.plot([x0, x1], [y1, y1], color=branch_color, lw=lw)
+        ax.plot([x0, x0], [y0, y1], color=vertical_color, lw=vertical_lw)
+
+
+def draw_tip_labels(
+    ax, tree, node_x, node_y, fontsize=9, offset_fraction=0.03,
+):
+    """Draw taxon name labels at tree tips."""
+    tips = list(tree.get_terminals())
+    max_x = max(node_x.values()) if node_x else 1.0
+    offset = max_x * offset_fraction
+
+    if fontsize <= 0:
+        return
+
+    for tip in tips:
+        ax.text(
+            node_x[id(tip)] + offset, node_y[id(tip)],
+            tip.name, va="center", fontsize=fontsize,
+        )
+
+
+def cleanup_tree_axes(ax, show_xlabel=True):
+    """Standard axis cleanup for rectangular tree plots."""
+    ax.set_yticks([])
+    ax.spines["top"].set_visible(False)
+    ax.spines["right"].set_visible(False)
+    ax.spines["left"].set_visible(False)
+    if show_xlabel:
+        ax.set_xlabel("Branch length")

phykit-2.1.84/phykit/helpers/trait_parsing.py

@@ -0,0 +1,133 @@
+"""
+Shared trait file parsing utilities.
+
+Provides a single implementation for parsing tab-delimited multi-trait
+files with a header row, used across phylogenetic regression, signal,
+ordination, path analysis, ANOVA, and other comparative methods.
+"""
+import sys
+from typing import Dict, List, Tuple
+
+from ..errors import PhykitUserError
+
+
+def parse_multi_trait_file(
+    path: str,
+    tree_tips: List[str],
+    min_shared: int = 3,
+    min_columns: int = 2,
+) -> Tuple[List[str], Dict[str, List[float]]]:
+    """Parse a tab-delimited multi-trait file with a header row.
+
+    Format:
+        taxon<tab>trait1<tab>trait2<tab>...
+        species_A<tab>1.2<tab>3.4<tab>...
+
+    Parameters
+    ----------
+    path : path to TSV file
+    tree_tips : list of tip names from the tree
+    min_shared : minimum shared taxa between tree and file (default 3)
+    min_columns : minimum columns in header (default 2: taxon + 1 trait)
+
+    Returns
+    -------
+    (trait_names, traits_dict) where traits_dict maps taxon -> [float values]
+    """
+    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,
+        )
+
+    # Filter out comments and blank lines
+    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,
+        )
+
+    # First data line is the header
+    header_parts = data_lines[0].split("\t")
+    n_cols = len(header_parts)
+    if n_cols < min_columns:
+        raise PhykitUserError(
+            [
+                f"Header must have at least {min_columns} columns "
+                f"(taxon + at least {min_columns - 1} trait(s)).",
+            ],
+            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>"
+                    f"{'<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) < min_shared:
+        raise PhykitUserError(
+            [
+                f"Only {len(shared)} shared taxa between tree and trait file.",
+                f"At least {min_shared} shared taxa are required.",
+            ],
+            code=2,
+        )
+
+    filtered = {taxon: traits[taxon] for taxon in shared}
+    return trait_names, filtered

{phykit-2.1.82 → phykit-2.1.84}/phykit/phykit.py

@@ -175,6 +175,8 @@ class Phykit:
                       in an alignment
                 taxon_groups (alias: tgroups; shared_taxa)
                     - group tree or FASTA files by their taxon set
+                occupancy_filter (alias: occ_filter; filter_occupancy)
+                    - filter alignments/trees by cross-file taxon occupancy
 
                 Tree-based commands
                 ===================
@@ -250,6 +252,8 @@ class Phykit:
                     - fit phylogenetic GLM for binary (logistic) or count (Poisson) data
                 phylo_anova (alias: panova; phylo_manova; pmanova)
                     - phylogenetic ANOVA / MANOVA using RRPP (Adams & Collyer 2018)
+                phylo_path (alias: ppath; phylopath)
+                    - phylogenetic path analysis (von Hardenberg & Gonzalez-Voyer 2013)
                 phylo_logistic (alias: phylo_logreg; plogreg)
                     - fit phylogenetic logistic regression (Ives & Garland 2010)
                 stochastic_character_map (alias: simmap; scm)
@@ -2089,6 +2093,65 @@ class Phykit:
         _add_json_argument(parser)
         _run_service(parser, argv, PhyloAnova)
 
+    @staticmethod
+    def phylo_path(argv):
+        parser = _new_parser(
+            description=textwrap.dedent(
+                f"""\
+                {help_header}
+
+                Phylogenetic path analysis (von Hardenberg & Gonzalez-Voyer
+                2013). Compare competing causal DAGs using d-separation
+                tests via PGLS with Pagel's lambda, rank models by CICc,
+                and estimate model-averaged path coefficients.
+
+                Aliases:
+                  phylo_path, ppath, phylopath
+                Command line interfaces:
+                  pk_phylo_path, pk_ppath, pk_phylopath
+
+                Usage:
+                phykit phylo_path -t <tree> --traits <traits_file>
+                  --models <models_file> [--best-only]
+                  [--plot-output <file>] [--csv <file>] [--json]
+
+                Options
+                =====================================================
+                -t/--tree                   species tree (required)
+
+                --traits                    TSV file with taxon and
+                                            continuous trait columns
+                                            (required)
+
+                --models                    model definition file
+                                            with candidate DAGs
+                                            (required). Format:
+                                            name: A->B, B->C, ...
+
+                --best-only                 report only best model
+                                            coefficients (default:
+                                            model averaging)
+
+                --plot-output               output DAG plot file
+
+                --csv                       output CSV with model
+                                            comparison and path
+                                            coefficients
+
+                --json                      output results as JSON
+                """
+            ),
+        )
+        parser.add_argument("-t", "--tree", type=str, required=True, help=SUPPRESS, metavar="")
+        parser.add_argument("--traits", type=str, required=True, help=SUPPRESS, metavar="")
+        parser.add_argument("--models", type=str, required=True, help=SUPPRESS, metavar="")
+        parser.add_argument("--best-only", action="store_true", help=SUPPRESS)
+        parser.add_argument("--plot-output", type=str, default=None, help=SUPPRESS, metavar="")
+        parser.add_argument("--csv", type=str, default=None, help=SUPPRESS, metavar="")
+        add_plot_arguments(parser)
+        _add_json_argument(parser)
+        _run_service(parser, argv, PhyloPath)
+
     @staticmethod
     def alignment_subsample(argv):
         parser = _new_parser(
@@ -8545,6 +8608,69 @@ class Phykit:
         _add_json_argument(parser)
         _run_service(parser, argv, TaxonGroups)
 
+    @staticmethod
+    def occupancy_filter(argv):
+        parser = _new_parser(
+            description=textwrap.dedent(
+                f"""\
+                {help_header}
+
+                Filter alignments and/or trees by cross-file taxon
+                occupancy. Counts how many files each taxon appears in
+                and retains only taxa meeting a minimum threshold.
+                Outputs filtered copies of each input file.
+
+                For FASTA files, removes sequences of filtered taxa.
+                For tree files, prunes tips of filtered taxa.
+
+                Aliases:
+                  occupancy_filter, occ_filter, filter_occupancy
+                Command line interfaces:
+                  pk_occupancy_filter, pk_occ_filter, pk_filter_occupancy
+
+                Usage:
+                phykit occupancy_filter -l <file_list>
+                  [-f/--format fasta|trees] [-t/--threshold <int>]
+                  [-o/--output-dir <dir>] [--suffix <str>] [--json]
+
+                Options
+                =====================================================
+                -l/--list                   file listing paths to
+                                            alignment or tree files,
+                                            one per line (required)
+
+                -f/--format                 input file format: fasta
+                                            or trees (default: fasta)
+
+                -t/--threshold              minimum occupancy to retain
+                                            a taxon. Values between 0
+                                            and 1 are treated as a
+                                            fraction (e.g., 0.5 = 50%
+                                            of files). Values >= 1 are
+                                            treated as an absolute
+                                            count. (default: 0.5)
+
+                -o/--output-dir             directory for filtered
+                                            output files (default:
+                                            same directory as input)
+
+                --suffix                    suffix added to output
+                                            filenames before the
+                                            extension (default:
+                                            ".filtered")
+
+                --json                      output results as JSON
+                """
+            ),
+        )
+        parser.add_argument("-l", "--list", type=str, required=True, help=SUPPRESS, metavar="")
+        parser.add_argument("-f", "--format", type=str, default="fasta", choices=["fasta", "trees"], help=SUPPRESS, metavar="")
+        parser.add_argument("-t", "--threshold", type=float, default=0.5, help=SUPPRESS, metavar="")
+        parser.add_argument("-o", "--output-dir", type=str, default=None, help=SUPPRESS, metavar="")
+        parser.add_argument("--suffix", type=str, default=".filtered", help=SUPPRESS, metavar="")
+        _add_json_argument(parser)
+        _run_service(parser, argv, OccupancyFilter)
+
     ### Helper commands
     @staticmethod
     def create_concatenation_matrix(argv):
@@ -8847,6 +8973,10 @@ def phylo_anova(argv=None):
     Phykit.phylo_anova(sys.argv[1:])
 
 
+def phylo_path(argv=None):
+    Phykit.phylo_path(sys.argv[1:])
+
+
 def dfoil(argv=None):
     Phykit.dfoil(sys.argv[1:])
 
@@ -9160,3 +9290,7 @@ def trait_rate_map(argv=None):
 
 def taxon_groups(argv=None):
     Phykit.taxon_groups(sys.argv[1:])
+
+
+def occupancy_filter(argv=None):
+    Phykit.occupancy_filter(sys.argv[1:])

{phykit-2.1.82 → phykit-2.1.84}/phykit/service_factories.py

@@ -45,7 +45,9 @@ RelativeCompositionVariabilityTaxon = _LazyServiceFactory("phykit.services.align
 RenameFastaEntries = _LazyServiceFactory("phykit.services.alignment.rename_fasta_entries", "RenameFastaEntries")
 SumOfPairsScore = _LazyServiceFactory("phykit.services.alignment.sum_of_pairs_score", "SumOfPairsScore")
 PhyloAnova = _LazyServiceFactory("phykit.services.tree.phylo_anova", "PhyloAnova")
+PhyloPath = _LazyServiceFactory("phykit.services.tree.phylo_path", "PhyloPath")
 PhyloGwas = _LazyServiceFactory("phykit.services.alignment.phylo_gwas", "PhyloGwas")
+OccupancyFilter = _LazyServiceFactory("phykit.services.alignment.occupancy_filter", "OccupancyFilter")
 TaxonGroups = _LazyServiceFactory("phykit.services.alignment.taxon_groups", "TaxonGroups")
 VariableSites = _LazyServiceFactory("phykit.services.alignment.variable_sites", "VariableSites")