about summary refs log tree commit diff
path: root/scripts
diff options
context:
space:
mode:
authorPjotr Prins <pjotr.public01@thebird.nl>2026-11-16 15:56:57 +0000
committerPjotr Prins <pjotr.public01@thebird.nl>2026-11-16 15:56:57 +0000
commit0e94a6a728e08feb69f183667f62dfabf86768d8 (patch)
tree4c20028b1bf44392686f0a4e67f00e5b6846b296 /scripts
parent6f48a70b389f712bd5a53bbd7495cb40954a7eaa (diff)
downloadgenenetwork4-0e94a6a728e08feb69f183667f62dfabf86768d8.tar.gz
correlation matrix: PCA, behind its parity test
`"pca": true` on the matrix request now folds the correlation matrix into
principal components: eigenvalues descending, explained variance ratios,
loadings per kept trait, and the eigenvalues' sum reported so a caller can
check the decomposition is sane instead of trusting it.

The eigendecomposition is cyclic Jacobi -- symmetric matrices, no LAPACK, no
new dependency -- capped at 300 traits because Jacobi is O(n^3) per sweep and
this is for a collection, not a dataset.

Two decisions from ai-memory #103, both visible in the reply:

* **Traits with any null cell are dropped and named**, with the reason. A
  component from a matrix with holes is not defined; GN2 silently mutates its
  shared-sample list instead, and nobody can reproduce that component.
* **The sign is fixed**: within a component the largest absolute loading is
  positive. Eigenvectors are defined up to sign, so without a rule two correct
  implementations disagree and no parity test could be exact.

Verified against numpy.linalg.eigh on the same r the reply carries
(scripts/pca-parity.py, BXDPublish 10001/10002/10003/10005/10007):

  eigenvalues: worst relative difference 3.2e-14
  loadings:    worst absolute difference 9.99e-16
  trace:       5.000000000000 for 5 traits

Unit tests cover the identity (unit eigenvalues), the closed form for 2x2
(1 +/- rho), the trace, a non-symmetric matrix being refused, and the cap. The
monitor gained `compute-correlation-pca`, whose judge checks that the
eigenvalues sum to the trait count and the ratios to 1.
Diffstat (limited to 'scripts')
-rwxr-xr-xscripts/pca-parity.py132
1 files changed, 132 insertions, 0 deletions
diff --git a/scripts/pca-parity.py b/scripts/pca-parity.py
new file mode 100755
index 0000000..6bef16c
--- /dev/null
+++ b/scripts/pca-parity.py
@@ -0,0 +1,132 @@
+#!/usr/bin/env python3
+"""Check a matrix PCA against numpy.linalg.eigh, to machine precision.
+
+The correlation matrix is the input and the eigendecomposition is the only
+numerically delicate step in the whole correlation surface (ai-memory #106), so
+it gets its own harness: the server's own `pca` block is compared against what
+numpy computes from the *same* `r` matrix, which is an independent
+implementation of the same mathematics (LAPACK's dsyevd against our Jacobi).
+
+    scripts/pca-parity.py --traits BXDPublish:10001,BXDPublish:10002,... \\
+        [--base http://127.0.0.1:3000] [--token ...]
+
+What is compared, per component:
+  * eigenvalues, relatively (they are O(1) here);
+  * loadings, by absolute difference *after* aligning signs -- an eigenvector
+    is defined up to sign, so the server fixes a convention (largest absolute
+    loading positive) and this script flips numpy's to match before comparing.
+
+Exit status is 0 only if everything agrees, so it is usable as a gate.
+Needs numpy (`guix shell python python-numpy` or the scipy profile).
+"""
+
+import argparse
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+
+TOLERANCE = 1e-10
+
+
+def post(base: str, path: str, body: dict, token: str | None, timeout: float) -> dict:
+    headers = {"content-type": "application/json"}
+    if token:
+        headers["authorization"] = "Bearer " + token
+    request = urllib.request.Request(
+        base.rstrip("/") + path,
+        data=json.dumps(body).encode(),
+        headers=headers,
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            payload = json.loads(response.read().decode())
+    except urllib.error.HTTPError as error:
+        detail = error.read().decode(errors="replace")
+        raise SystemExit(f"{path}: HTTP {error.code}: {detail}") from error
+    return payload
+
+
+def traits_of(spec: str) -> list[dict]:
+    out = []
+    for item in spec.split(","):
+        dataset, _, trait = item.strip().partition(":")
+        if not dataset or not trait:
+            raise SystemExit(f"--traits wants dataset:trait, got {item!r}")
+        out.append({"dataset": dataset, "trait_name": trait})
+    return out
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__,
+                                     formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--base", default="http://127.0.0.1:3000")
+    parser.add_argument("--token", default=os.environ.get("GN4_TOKEN"))
+    parser.add_argument("--traits", required=True,
+                        help="dataset:trait[,dataset:trait...]")
+    parser.add_argument("--method", default="pearson")
+    parser.add_argument("--tolerance", type=float, default=TOLERANCE)
+    parser.add_argument("--timeout", type=float, default=600.0)
+    args = parser.parse_args()
+
+    try:
+        import numpy
+    except ImportError:
+        raise SystemExit("needs numpy: guix shell python python-numpy -- this script")
+
+    payload = post(args.base, "/compute/correlation/matrix",
+                   {"traits": traits_of(args.traits), "method": args.method, "pca": True},
+                   args.token, args.timeout)
+    data = payload.get("data") or {}
+    ours = data.get("pca") or {}
+    if not ours.get("components"):
+        raise SystemExit(f"no pca in the reply: {json.dumps(payload)[:300]}")
+
+    kept = [t for t in data.get("traits") or []
+            if not any(d["dataset"] == t["dataset"] and d["trait_name"] == t["trait_name"]
+                       for d in ours.get("dropped") or [])]
+    dropped = [f"{d['dataset']}:{d['trait_name']}" for d in ours.get("dropped") or []]
+    print(f"{len(kept)} trait(s) in the PCA"
+          + (f", {len(dropped)} dropped: {dropped}" if dropped else ""))
+
+    # Rebuild the kept submatrix from the reply's own r and decompose it.
+    order = [i for i, t in enumerate(data["traits"]) if t in kept]
+    matrix = numpy.array([[data["r"][i][j] for j in order] for i in order], dtype=float)
+    values, vectors = numpy.linalg.eigh(matrix)          # ascending
+    values = values[::-1]
+    vectors = vectors[:, ::-1]
+
+    worst_value, worst_loading = 0.0, 0.0
+    for index, component in enumerate(ours["components"]):
+        if index >= len(values):
+            break
+        expected = values[index]
+        got = component["eigenvalue"]
+        scale = max(abs(expected), abs(got), 1e-300)
+        worst_value = max(worst_value, abs(expected - got) / scale)
+
+        reference = vectors[:, index]
+        # Align signs on the largest absolute loading, the server's convention.
+        pivot = int(numpy.argmax(numpy.abs(reference)))
+        if (reference[pivot] < 0) != (component["loadings"][pivot] < 0):
+            reference = -reference
+        for a, b in zip(component["loadings"], reference):
+            worst_loading = max(worst_loading, abs(a - b))
+
+    trace = sum(c["eigenvalue"] for c in ours["components"])
+    print(f"eigenvalues: worst relative difference {worst_value:.3g}")
+    print(f"loadings:    worst absolute difference {worst_loading:.3g}")
+    print(f"trace:       {trace:.12f} (should equal {len(kept)})")
+    if abs(trace - len(kept)) > 1e-8 * max(1, len(kept)):
+        print("TRACE MISMATCH: the decomposition is not sane")
+        return 1
+    if worst_value > args.tolerance or worst_loading > args.tolerance:
+        print(f"DISAGREEMENT beyond {args.tolerance:g}")
+        return 1
+    print("agrees with numpy.linalg.eigh")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())