descriptron-core 2.1.2__tar.gz → 2.2.0__tar.gz

{descriptron_core-2.1.2 → descriptron_core-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: descriptron-core
-Version: 2.1.2
+Version: 2.2.0
 Summary: Evidence-tiered species descriptions, keys and audits from phenomic matrices
 Project-URL: Homepage, https://github.com/alexrvandam/Descriptron
 Project-URL: Repository, https://github.com/alexrvandam/Descriptron
@@ -9,7 +9,6 @@ Author: Alex R. Van Dam
 License: Apache-2.0
 License-File: LICENSE
 License-File: NOTICE
-License-File: NOTICE.bak_pre_212_20260929_1100
 Keywords: COCO,morphometrics,phenomics,species description,taxonomy
 Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: Apache Software License

{descriptron_core-2.1.2 → descriptron_core-2.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "descriptron-core"
-version = "2.1.2"
+version = "2.2.0"
 description = "Evidence-tiered species descriptions, keys and audits from phenomic matrices"
 readme = "README.md"
 requires-python = ">=3.9"

{descriptron_core-2.1.2 → descriptron_core-2.2.0}/src/descriptron_core/tools/biorag_llm_backend.py

@@ -82,6 +82,11 @@ class LLMResponse:
 def _log_call(log_path: Optional[str], record: Dict):
     if not log_path:
         return
+    try:                                   # when the call was made, for matching a call to a result
+        from datetime import datetime, timezone
+        record = {"time_utc": datetime.now(timezone.utc).isoformat(timespec="seconds"), **record}
+    except Exception:
+        pass
     with _LOG_LOCK:
         Path(log_path).parent.mkdir(parents=True, exist_ok=True)
         with open(log_path, "a") as f:

descriptron_core-2.2.0/src/descriptron_core/tools/biorag_provenance_v1.py

@@ -0,0 +1,230 @@
+#!/usr/bin/env python3
+"""
+biorag_provenance_v1.py — stamp every output with what produced it
+==================================================================
+
+A number in a manuscript is only checkable if a reader can get from it back to
+the code and the inputs that made it. `manuscript_numbers_v18.tsv` already maps
+each number to the report file that supplied it; this closes the remaining link,
+from the report back to the script, the commit and the exact inputs.
+
+Three lines in a script:
+
+    from biorag_provenance_v1 import stamp, write_json
+    ...
+    write_json(out_dir / "report.json", payload)        # adds "_provenance"
+
+or, for anything that is not JSON (a CSV, a figure, a directory of tables):
+
+    stamp(out_dir, inputs=[args.matrix, args.coco])     # writes provenance.json
+
+What is recorded: the script and its SHA-256, the git commit and whether the tree
+was dirty, the full command line, the interpreter and platform, the run time in
+UTC, and a SHA-256 for every named input file. Hashing the inputs is what makes
+the record worth anything — "produced by version X from these exact files" is a
+claim a sceptic can test, "produced by version X" is not.
+
+Deliberately: no network, no imports beyond the standard library, and every
+failure is swallowed. A provenance stamp must never be the reason an analysis
+dies.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import platform
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+__all__ = ["provenance", "stamp", "write_json", "sha256"]
+
+_MAX_HASH_BYTES = 2_000_000_000     # 2 GB: beyond this, record the size only
+
+
+def sha256(path) -> str | None:
+    """SHA-256 of a file, or None if it cannot be read. Never raises."""
+    try:
+        p = Path(path)
+        if not p.is_file():
+            return None
+        if p.stat().st_size > _MAX_HASH_BYTES:
+            return f"(not hashed: {p.stat().st_size} bytes)"
+        h = hashlib.sha256()
+        with open(p, "rb") as fh:
+            for chunk in iter(lambda: fh.read(1 << 20), b""):
+                h.update(chunk)
+        return h.hexdigest()
+    except Exception:
+        return None
+
+
+def _git(*args, cwd=None):
+    try:
+        out = subprocess.run(["git", *args], cwd=cwd, capture_output=True,
+                             text=True, timeout=10)
+        return out.stdout.strip() if out.returncode == 0 else None
+    except Exception:
+        return None
+
+
+def provenance(inputs=None, script=None, extra=None) -> dict:
+    """The record itself. Safe to call from anywhere; never raises."""
+    try:
+        script_path = Path(script or sys.argv[0]).resolve()
+    except Exception:
+        script_path = Path(sys.argv[0] if sys.argv else "unknown")
+    repo = script_path.parent if script_path.exists() else None
+
+    # Only report a commit if THIS FILE is tracked by that repository. The
+    # Descriptron scripts currently sit untracked inside a clone of
+    # facebookresearch/segment-anything-2, so a naive `git rev-parse HEAD` returns
+    # SAM2's commit — a hash that says nothing about the code that produced the
+    # output, and is worse than no hash because it looks authoritative.
+    commit = dirty = tracked = None
+    if repo is not None:
+        tracked = bool(_git("ls-files", "--error-unmatch", str(script_path), cwd=repo))
+        if tracked:
+            commit = _git("rev-parse", "HEAD", cwd=repo)
+            dirty = bool(_git("status", "--porcelain", "--", str(script_path), cwd=repo))
+
+    rec = {
+        "script": script_path.name,
+        "script_path": str(script_path),
+        "script_sha256": sha256(script_path),
+        "git_commit": commit,
+        "git_dirty": dirty,
+        # a run from an untracked tree cannot be pinned to a version; say so in
+        # the record rather than leaving a reader to infer it
+        "git_tracked": tracked,
+        "git_note": (None if commit else
+                     "this script is NOT tracked by any git repository, so the output "
+                     "cannot be tied to a version of the code"),
+        "command": " ".join(sys.argv),
+        "argv": list(sys.argv),
+        "cwd": os.getcwd(),
+        "python": sys.version.split()[0],
+        "platform": platform.platform(),
+        "hostname": platform.node(),
+        "run_utc": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+        "inputs": {},
+    }
+    for item in (inputs or []):
+        if item is None:
+            continue
+        try:
+            rec["inputs"][str(item)] = sha256(item)
+        except Exception:
+            rec["inputs"][str(item)] = None
+    if extra:
+        rec["extra"] = extra
+    return rec
+
+
+def stamp(out_dir, inputs=None, script=None, extra=None, name="provenance.json"):
+    """Write a provenance record beside an output that is not itself JSON."""
+    try:
+        d = Path(out_dir)
+        d.mkdir(parents=True, exist_ok=True)
+        rec = provenance(inputs=inputs, script=script, extra=extra)
+        (d / name).write_text(json.dumps(rec, indent=2))
+        return d / name
+    except Exception:
+        return None
+
+
+def write_json(path, payload, inputs=None, script=None, extra=None, indent=2):
+    """json.dump with a `_provenance` key added. Drop-in for an existing dump."""
+    try:
+        rec = provenance(inputs=inputs, script=script, extra=extra)
+        if isinstance(payload, dict):
+            payload = {**payload, "_provenance": rec}
+        else:
+            payload = {"data": payload, "_provenance": rec}
+    except Exception:
+        pass
+    p = Path(path)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(json.dumps(payload, indent=indent, default=str))
+    return p
+
+
+def verify(record_path) -> dict:
+    """
+    Re-check a stamped record: does the script still hash the same, do the inputs
+    still hash the same? This is what a sceptical reader runs.
+    """
+    rec = json.loads(Path(record_path).read_text())
+    rec = rec.get("_provenance", rec)
+    out = {"script": None, "inputs": {}, "ok": True}
+    now = sha256(rec.get("script_path"))
+    out["script"] = ("unchanged" if now and now == rec.get("script_sha256")
+                     else "CHANGED or missing")
+    if out["script"] != "unchanged":
+        out["ok"] = False
+    for path, want in (rec.get("inputs") or {}).items():
+        got = sha256(path)
+        same = (got is not None and got == want)
+        out["inputs"][path] = "unchanged" if same else "CHANGED or missing"
+        if not same:
+            out["ok"] = False
+    # records written by run_full_pipeline_v2 also list what the step wrote
+    if isinstance(rec.get("outputs"), dict):
+        out["outputs"] = {}
+        for path, want in rec["outputs"].items():
+            if path.startswith("("):
+                continue
+            got = sha256(path)
+            same = (got is not None and got == want)
+            out["outputs"][path] = "unchanged" if same else "CHANGED or missing"
+            if not same:
+                out["ok"] = False
+    return out
+
+
+def which(result_file, search_dir) -> list:
+    """Which pipeline step wrote this file? Hash it and look for the hash among the outputs of
+    every provenance record under search_dir. A match means this exact content was written by
+    that step; no match means the file was changed afterwards or made outside the pipeline."""
+    want = sha256(result_file)
+    hits = []
+    if want is None:
+        return hits
+    for rp in sorted(Path(search_dir).rglob("*provenance*.json")):
+        try:
+            rec = json.loads(rp.read_text())
+        except Exception:
+            continue
+        rec = rec.get("_provenance", rec)
+        outs = rec.get("outputs") or {}
+        if isinstance(outs, dict) and want in outs.values():
+            hits.append({"record": str(rp),
+                         "step": (rec.get("extra") or {}).get("pipeline_step"),
+                         "script": rec.get("script"), "script_sha256": rec.get("script_sha256"),
+                         "git_commit": rec.get("git_commit"), "run_utc": rec.get("run_utc"),
+                         "command": rec.get("command")})
+    return hits
+
+
+if __name__ == "__main__":
+    import argparse
+    ap = argparse.ArgumentParser(description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--verify", help="a provenance.json (or a report with _provenance) to re-check")
+    ap.add_argument("--show", action="store_true", help="print a record for this invocation")
+    ap.add_argument("--which", help="a result file: find the provenance record of the step that wrote it")
+    ap.add_argument("--search", default=".", help="folder to search for provenance records (with --which)")
+    a = ap.parse_args()
+    if a.verify:
+        result = verify(a.verify)
+        print(json.dumps(result, indent=2))
+        sys.exit(0 if result["ok"] else 1)
+    if a.which:
+        hits = which(a.which, a.search)
+        print(json.dumps(hits, indent=2) if hits else
+              "no provenance record lists this exact file content (changed since, or not made by the pipeline)")
+        sys.exit(0 if hits else 1)
+    if a.show:
+        print(json.dumps(provenance(), indent=2))

descriptron_core-2.2.0/src/descriptron_core/tools/descriptron_phylo.py

@@ -0,0 +1,377 @@
+#!/usr/bin/env python3
+"""
+descriptron_phylo.py - phylogenetic comparative analyses of any continuous Descriptron traits
+=============================================================================================
+
+Given a Newick tree and one or more trait tables (landmark shape, linear measurements, colour pattern, texture, or
+any other continuous features), computes on species means:
+
+  signal     multivariate phylogenetic signal Kmult (Adams 2014), permutation P and effect size Z,
+             as geomorph::physignal
+  pgls       phylogenetic regression of a trait set on a predictor (for example log centroid size: phylogenetic
+             allometry) by generalised least squares under Brownian motion, SS / R2 / F with residual
+             randomisation, as geomorph::procD.pgls
+  morphospace principal components of the species means with ancestral states estimated under Brownian motion
+             (generalised least squares) projected into the same space and the tree drawn through them, as
+             geomorph::gm.prcomp(phy = )
+
+Trait tables: CSV with one row per specimen (or per species) and numeric columns. The species of each row comes
+from a column (--species_col) or from a regular expression applied to an id column (--species_regex). Rows of the
+same species are averaged. Species absent from the tree, or tree tips without data, are dropped (the tree is pruned).
+
+  python descriptron_phylo.py --tree tree.nwk --out_dir phylo/ \
+      --traits shape=landmark_gpa/forewing/forewing_procrustes_coords.csv \
+      --traits colour=color_homology/whole_wing/color_homology_features_whole_wing.csv \
+      --species_regex "morph_([A-Za-z]+\\d*?)_?\\d+_" --scale colour=standardize \
+      --pgls shape~logCS --analyses signal pgls morphospace
+
+Scaling (--scale NAME=none|standardize|log): Kmult and the PGLS statistics weight every column by its variance, so a
+set that mixes units (millimetres with ratios, colour channels with entropies) should be standardised; Procrustes
+shape coordinates are analysed as they are (the default for a set whose columns look like x/y coordinates).
+
+Validated against geomorph 4.1.1 and ape on geomorph's plethspecies data (validation/validate_phylo_real_tree.py).
+"""
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+import numpy as np
+
+# ============================================================================ tree
+class Node:
+    __slots__ = ("name", "length", "kids", "parent", "depth", "idx")
+
+    def __init__(self, name="", length=0.0):
+        self.name, self.length, self.kids, self.parent, self.depth, self.idx = name, length, [], None, 0.0, -1
+
+
+def parse_newick(s: str) -> Node:
+    s = s.strip().rstrip(";")
+    pos = 0
+
+    def node() -> Node:
+        nonlocal pos
+        n = Node()
+        if s[pos] == "(":
+            pos += 1
+            n.kids.append(node())
+            while s[pos] == ",":
+                pos += 1
+                n.kids.append(node())
+            pos += 1                                                  # ')'
+        m = re.match(r"([^:,();\[]*)(?:\[[^\]]*\])?(?::([0-9.eE+\-]+))?", s[pos:])
+        pos += m.end()
+        n.name = m.group(1).strip().strip("'\"")
+        n.length = float(m.group(2) or 0.0)
+        for k in n.kids:
+            k.parent = n
+        return n
+
+    root = node()
+    root.length = 0.0                                                 # the root's own branch does not count
+    _set_depths(root)
+    return root
+
+
+def _set_depths(n: Node, d: float = 0.0):
+    n.depth = d
+    for k in n.kids:
+        _set_depths(k, d + k.length)
+
+
+def tips_of(n: Node) -> List[Node]:
+    return [n] if not n.kids else [t for k in n.kids for t in tips_of(k)]
+
+
+def internal_nodes(n: Node) -> List[Node]:
+    return ([n] if n.kids else []) + [x for k in n.kids for x in internal_nodes(k)]
+
+
+def prune(root: Node, keep: set) -> Node:
+    """Drop tips not in `keep`; collapse nodes left with one child (their branch lengths add up)."""
+    def rec(n: Node) -> Optional[Node]:
+        if not n.kids:
+            return n if n.name in keep else None
+        kids = [c for c in (rec(k) for k in n.kids) if c is not None]
+        if not kids:
+            return None
+        if len(kids) == 1:
+            kids[0].length += n.length
+            return kids[0]
+        n.kids = kids
+        for k in kids:
+            k.parent = n
+        return n
+
+    r = rec(root)
+    r.length, r.parent = 0.0, None
+    _set_depths(r)
+    return r
+
+
+def mrca_depth(a: Node, b: Node) -> float:
+    anc = set()
+    x = a
+    while x is not None:
+        anc.add(id(x)); x = x.parent
+    y = b
+    while id(y) not in anc:
+        y = y.parent
+    return y.depth
+
+
+def vcv(nodes_a: List[Node], nodes_b: List[Node]) -> np.ndarray:
+    """Brownian-motion covariance: shared path length from the root (tips and internal nodes alike)."""
+    return np.array([[mrca_depth(a, b) for b in nodes_b] for a in nodes_a])
+
+
+# ============================================================================ statistics
+def _whiten(C: np.ndarray) -> np.ndarray:
+    """P with P'P = C^-1 (any such P gives the same GLS sums of squares)."""
+    return np.linalg.inv(np.linalg.cholesky(C))
+
+
+def kmult(Y: np.ndarray, C: np.ndarray) -> float:
+    """Adams (2014) multivariate K, as geomorph::physignal."""
+    n = len(Y)
+    Ci = np.linalg.inv(C)
+    one = np.ones((n, 1))
+    a = np.linalg.solve(one.T @ Ci @ one, one.T @ Ci @ Y)
+    R = Y - one @ a
+    obs = np.trace(R.T @ R) / np.trace(R.T @ Ci @ R)
+    expct = (np.trace(C) - n / Ci.sum()) / (n - 1)
+    return float(obs / expct)
+
+
+def effect_size(obs: float, rand: np.ndarray) -> float:
+    r = np.r_[obs, rand]
+    sd = r.std(ddof=1)
+    return float((obs - r.mean()) / sd) if sd > 0 else float("nan")
+
+
+def phylo_signal(Y, C, iters, rng) -> Dict:
+    K = kmult(Y, C)
+    rand = np.array([kmult(Y[rng.permutation(len(Y))], C) for _ in range(iters)])
+    return {"Kmult": K, "P": float((1 + (rand >= K - 1e-12).sum()) / (iters + 1)), "Z": effect_size(K, rand)}
+
+
+def pgls(Y: np.ndarray, x: np.ndarray, C: np.ndarray, iters: int, rng) -> Dict:
+    """Y ~ x under Brownian motion by GLS; SS from the whitened data, residual randomisation of the null model
+    (intercept only), as RRPP / geomorph::procD.pgls with a single predictor."""
+    n = len(Y)
+    P = _whiten(C)
+    Yt = P @ Y
+    X0 = P @ np.ones((n, 1))
+    X1 = P @ np.column_stack([np.ones(n), x])
+
+    def rss(X, Yy):
+        B, *_ = np.linalg.lstsq(X, Yy, rcond=None)
+        R = Yy - X @ B
+        return float((R ** 2).sum())
+
+    B0, *_ = np.linalg.lstsq(X0, Yt, rcond=None)
+    fit0, res0 = X0 @ B0, Yt - X0 @ B0
+    ss_tot, ss_res = rss(X0, Yt), rss(X1, Yt)
+    ss = ss_tot - ss_res
+    df, dfr = 1, n - 2
+    F = (ss / df) / (ss_res / dfr)
+    rand = []
+    for _ in range(iters):
+        Yp = fit0 + res0[rng.permutation(n)]
+        s_t, s_r = rss(X0, Yp), rss(X1, Yp)
+        rand.append(((s_t - s_r) / df) / (s_r / dfr))
+    rand = np.array(rand)
+    return {"Df": df, "SS": ss, "MS": ss / df, "Rsq": ss / ss_tot, "F": F, "Z": effect_size(F, rand),
+            "P": float((1 + (rand >= F - 1e-12).sum()) / (iters + 1)), "SS_residual": ss_res, "SS_total": ss_tot}
+
+
+def ancestral_states(Y: np.ndarray, tips: List[Node], nodes: List[Node]) -> np.ndarray:
+    """Ancestral states under Brownian motion by GLS: a = mu + C_nt C_tt^-1 (Y - 1 mu), with mu the GLS root state."""
+    Ctt = vcv(tips, tips)
+    Cnt = vcv(nodes, tips)
+    Ci = np.linalg.inv(Ctt)
+    one = np.ones((len(tips), 1))
+    mu = np.linalg.solve(one.T @ Ci @ one, one.T @ Ci @ Y)
+    return mu + Cnt @ Ci @ (Y - one @ mu)
+
+
+# ============================================================================ data
+def _is_number(v: str) -> bool:
+    try:
+        float(v); return True
+    except ValueError:
+        return False
+
+
+def load_traits(path: str, species_col: Optional[str], species_regex: Optional[str], id_col: Optional[str]):
+    rows = list(csv.DictReader(open(path, newline="")))
+    if not rows:
+        sys.exit(f"{path}: no rows")
+    cols = list(rows[0])
+    if species_col and species_col in cols:
+        sp = [r[species_col] for r in rows]
+    else:
+        idc = id_col or next((c for c in ("filename", "specimen_id", "specimen", "image", "id", "file") if c in cols), cols[0])
+        if not species_regex:
+            sys.exit(f"{path}: give --species_col or --species_regex (no species column found)")
+        rx = re.compile(species_regex)
+        sp = []
+        for r in rows:
+            m = rx.search(r[idc])
+            sp.append(m.group(1) if m else None)
+    num = [c for c in cols if c != species_col and all(_is_number(r[c]) or r[c] == "" for r in rows)
+           and any(r[c] != "" for r in rows)]
+    M = np.array([[float(r[c]) if r[c] != "" else np.nan for c in num] for r in rows])
+    by: Dict[str, List[int]] = {}
+    for i, s in enumerate(sp):
+        if s:
+            by.setdefault(s, []).append(i)
+    species = sorted(by)
+    means = np.array([np.nanmean(M[by[s]], axis=0) for s in species])
+    keep = ~np.isnan(means).any(axis=0)                  # drop columns missing for any species
+    return species, [c for c, k in zip(num, keep) if k], means[:, keep], {s: len(v) for s, v in by.items()}
+
+
+def scale(M: np.ndarray, how: str) -> np.ndarray:
+    if how == "standardize":
+        sd = M.std(axis=0, ddof=1)
+        ok = sd > 0
+        return (M[:, ok] - M[:, ok].mean(0)) / sd[ok]
+    if how == "log":
+        if (M <= 0).any():
+            sys.exit("--scale log needs positive values")
+        return np.log(M)
+    return M
+
+
+# ============================================================================ plot
+def plot_morphospace(pc_tips, pc_nodes, tips, nodes, ev, path, title):
+    import matplotlib
+    matplotlib.use("Agg")
+    import matplotlib.pyplot as plt
+    pos = {id(t): pc_tips[i] for i, t in enumerate(tips)}
+    pos.update({id(n): pc_nodes[i] for i, n in enumerate(nodes)})
+    fig, ax = plt.subplots(figsize=(6.5, 5.5))
+    for n in nodes:
+        for k in n.kids:
+            a, b = pos[id(n)], pos[id(k)]
+            ax.plot([a[0], b[0]], [a[1], b[1]], color="#6b7780", lw=0.9, zorder=1)
+    ax.scatter(pc_nodes[:, 0], pc_nodes[:, 1], s=14, color="white", edgecolor="#6b7780", zorder=2, label="ancestral states")
+    ax.scatter(pc_tips[:, 0], pc_tips[:, 1], s=30, color="#0072B2", zorder=3, label="species means")
+    for i, t in enumerate(tips):
+        ax.annotate(t.name, pc_tips[i, :2], xytext=(3, 3), textcoords="offset points", fontsize=7)
+    ax.set_xlabel(f"PC1 ({100 * ev[0]:.1f}%)"); ax.set_ylabel(f"PC2 ({100 * ev[1]:.1f}%)")
+    ax.set_title(title, fontsize=10); ax.legend(fontsize=7, frameon=False)
+    fig.tight_layout(); fig.savefig(path, dpi=200); plt.close(fig)
+
+
+# ============================================================================ main
+def main(argv=None):
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--tree", required=True, help="Newick tree whose tips are species names")
+    ap.add_argument("--traits", action="append", required=True, metavar="NAME=CSV",
+                    help="a trait table; repeat for several sets (shape, measurements, colour, texture, ...)")
+    ap.add_argument("--species_col", default=None, help="column holding the species (default: use --species_regex)")
+    ap.add_argument("--species_regex", default=None, help="regex with one group extracting the species from the id column")
+    ap.add_argument("--id_col", default=None, help="id column for --species_regex (default: filename/specimen_id/...)")
+    ap.add_argument("--columns", action="append", default=[], metavar="NAME=REGEX",
+                    help="keep only the columns of trait set NAME that match REGEX")
+    ap.add_argument("--scale", action="append", default=[], metavar="NAME=none|standardize|log")
+    ap.add_argument("--size_col", default=r"centroid|csize",
+                    help="regex for a size column kept out of the trait set and used as the logCS predictor")
+    ap.add_argument("--pgls", action="append", default=[], metavar="SET~PREDICTOR",
+                    help="PREDICTOR is logCS (from a set's centroid-size column) or SET2:COLUMN")
+    ap.add_argument("--analyses", nargs="+", default=["signal", "morphospace"], choices=["signal", "pgls", "morphospace"])
+    ap.add_argument("--iterations", type=int, default=999); ap.add_argument("--seed", type=int, default=1)
+    ap.add_argument("--out_dir", required=True)
+    a = ap.parse_args(argv)
+    out = Path(a.out_dir); out.mkdir(parents=True, exist_ok=True)
+    rng = np.random.default_rng(a.seed)
+    root = parse_newick(Path(a.tree).read_text())
+    colsel = dict(x.split("=", 1) for x in a.columns)
+    scales = dict(x.split("=", 1) for x in a.scale)
+
+    sets = {}
+    for spec in a.traits:
+        name, path = spec.split("=", 1)
+        sp, cols, M, counts = load_traits(path, a.species_col, a.species_regex, a.id_col)
+        if name in colsel:
+            rx = re.compile(colsel[name]); k = [i for i, c in enumerate(cols) if rx.search(c)]
+            cols, M = [cols[i] for i in k], M[:, k]
+        # a size column (centroid size) is kept aside: it is a predictor (logCS), not part of the trait set
+        szi = [i for i, c in enumerate(cols) if re.search(a.size_col, c, re.I)]
+        size = M[:, szi[0]] if szi else None
+        keep = [i for i in range(len(cols)) if i not in szi]
+        sets[name] = {"species": sp, "cols": [cols[i] for i in keep], "raw": M[:, keep], "size": size,
+                      "counts": counts}
+
+    report = ["# Phylogenetic comparative analyses", "", f"Tree: {a.tree}", ""]
+    signal_rows, pgls_rows = [], []
+    for name, S in sets.items():
+        tipnames = {t.name for t in tips_of(root)}
+        common = [s for s in S["species"] if s in tipnames]
+        if len(common) < 4:
+            report.append(f"{name}: only {len(common)} species match the tree - skipped"); continue
+        tree = prune(parse_newick(Path(a.tree).read_text()), set(common))
+        tips = tips_of(tree)
+        idx = [S["species"].index(t.name) for t in tips]
+        how = scales.get(name, "none")
+        Y = scale(S["raw"][idx], how)
+        C = vcv(tips, tips)
+        S.update(tree=tree, tips=tips, Y=Y, C=C, idx=idx)
+        dropped = sorted(set(S["species"]) - set(common))
+        report += [f"## {name}", f"{len(tips)} species, {Y.shape[1]} variables (scale: {how})"
+                   + (f"; not in the tree: {', '.join(dropped)}" if dropped else ""), ""]
+        if "signal" in a.analyses:
+            r = phylo_signal(Y, C, a.iterations, rng)
+            signal_rows.append({"trait_set": name, "n_species": len(tips), "n_variables": Y.shape[1], "scale": how, **r})
+            report.append(f"Phylogenetic signal: Kmult = {r['Kmult']:.4f}, P = {r['P']:.4f}, Z = {r['Z']:.2f}")
+        if "morphospace" in a.analyses:
+            nodes = internal_nodes(tree)
+            anc = ancestral_states(Y, tips, nodes)
+            mu = Y.mean(0)
+            U, sv, Vt = np.linalg.svd(Y - mu, full_matrices=False)
+            ev = sv ** 2 / (sv ** 2).sum()
+            pc_t, pc_n = (Y - mu) @ Vt.T, (anc - mu) @ Vt.T
+            np.savetxt(out / f"{name}_morphospace_tips.csv", pc_t[:, :min(5, pc_t.shape[1])], delimiter=",",
+                       header=",".join(f"PC{i + 1}" for i in range(min(5, pc_t.shape[1]))), comments="")
+            plot_morphospace(pc_t, pc_n, tips, nodes, ev, out / f"{name}_phylomorphospace.png",
+                             f"{name}: phylomorphospace ({len(tips)} species)")
+            report.append(f"Phylomorphospace: {name}_phylomorphospace.png (PC1 {100 * ev[0]:.1f}%, PC2 {100 * ev[1]:.1f}%)")
+        report.append("")
+
+    if "pgls" in a.analyses:
+        for f in a.pgls:
+            ys, pred = [x.strip() for x in f.split("~")]
+            S = sets.get(ys)
+            if S is None or "Y" not in S:
+                report.append(f"PGLS {f}: trait set {ys} not analysed - skipped"); continue
+            if pred == "logCS":
+                if S["size"] is None:
+                    report.append(f"PGLS {f}: no size column in {ys} (--size_col) - skipped"); continue
+                xv = np.log(np.array([S["size"][S["species"].index(t.name)] for t in S["tips"]]))
+            else:
+                s2, cc = pred.split(":", 1); src = sets.get(s2)
+                if src is None or cc not in src["cols"]:
+                    report.append(f"PGLS {f}: predictor column not found - skipped"); continue
+                xv = np.array([src["raw"][src["species"].index(t.name), src["cols"].index(cc)] for t in S["tips"]])
+            r = pgls(S["Y"], xv, S["C"], a.iterations, rng)
+            pgls_rows.append({"model": f, **r})
+            report.append(f"PGLS {f}: R2 = {r['Rsq']:.4f}, F = {r['F']:.3f}, P = {r['P']:.4f}")
+
+    for fn, rows in (("phylogenetic_signal.csv", signal_rows), ("pgls.csv", pgls_rows)):
+        if rows:
+            with open(out / fn, "w", newline="") as fh:
+                w = csv.DictWriter(fh, fieldnames=list(rows[0])); w.writeheader(); w.writerows(rows)
+    (out / "phylo_report.md").write_text("\n".join(report) + "\n")
+    print("\n".join(report))
+
+
+if __name__ == "__main__":
+    main()