foldmetrics 0.1.0__tar.gz

foldmetrics-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.10", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Install
+        run: |
+          uv venv --python ${{ matrix.python }}
+          uv pip install -e ".[dev]"
+      - name: Test
+        run: .venv/bin/pytest
+      - name: Lint
+        run: .venv/bin/ruff check src tests examples

foldmetrics-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,36 @@
+name: Publish to PyPI
+
+# Triggered by pushing a version tag, e.g.: git push origin v0.1.0
+# Requires a PyPI "trusted publisher" configured for this repository
+# (project: foldmetrics, workflow: publish.yml, environment: pypi).
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Build sdist and wheel
+        run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/foldmetrics
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

foldmetrics-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Editors / OS
+.DS_Store
+.idea/
+.vscode/
+
+# Local working notes (not part of the published project)
+CLAUDE.md
+.claude/
+
+# Local outputs
+foldmetrics_plots/
+*.tsv
+!tests/**/*.tsv

foldmetrics-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jiajun Li
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

foldmetrics-0.1.0/PKG-INFO

@@ -0,0 +1,241 @@
+Metadata-Version: 2.5
+Name: foldmetrics
+Version: 0.1.0
+Summary: Unified confidence metrics (pTM, ipTM, pLDDT, ipLDDT, PAE, ipSAE, pDockQ, pDockQ2, LIS) for AlphaFold2/3, ColabFold, Boltz, Chai-1 and Protenix predictions
+Project-URL: Homepage, https://github.com/ChiaChunL/foldmetrics
+Project-URL: Repository, https://github.com/ChiaChunL/foldmetrics
+Project-URL: Issues, https://github.com/ChiaChunL/foldmetrics/issues
+Author-email: Jiajun Li <ChiaChun.Le@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: alphafold,bioinformatics,boltz,chai-1,ipsae,iptm,pae,pdockq,plddt,protein-complex,protenix,structure-prediction
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Requires-Dist: gemmi>=0.6.4
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: numpy>=1.23
+Requires-Dist: pandas>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# foldmetrics
+
+Unified confidence metrics for structure-prediction models.
+
+`foldmetrics` ingests the raw output folders of the mainstream structure
+predictors — **AlphaFold2 / AlphaFold-Multimer, ColabFold, AlphaFold3, Boltz,
+Chai-1, Protenix** — and computes a consistent set of quality metrics for
+monomers and complexes (protein, nucleic acid and small-molecule ligands),
+for a single model or whole batches:
+
+| Metric | What it tells you | Source |
+|---|---|---|
+| `ptm`, `iptm` | global / interface predicted TM-score | read from tool output |
+| `ranking_score` | tool-native model ranking (AF3 `ranking_score`, Boltz `confidence_score`, Chai `aggregate_score`, AF2 `ranking_confidence`) | read from tool output |
+| `plddt_mean` | mean per-token pLDDT | computed |
+| `iplddt` | mean pLDDT over interface residues (contact atoms within 8 Å across chains) | computed |
+| `pae_mean`, `ipae_mean` | mean PAE (all off-diagonal / inter-chain blocks) | computed |
+| `ipsae` | interface score from PAE with per-residue d0 (Dunbrack 2025) | computed |
+| `pdockq` | interface score from contacts + pLDDT (Bryant 2022) | computed |
+| `pdockq2` | interface score from contacts + pLDDT + PAE (Zhu 2023) | computed |
+| `lis` | Local Interaction Score from PAE (Kim 2024) | computed |
+
+Computed metrics were validated against the `ipsae.py` reference
+implementation (Dunbrack Lab), including its exact `d0` conventions.
+
+## Install
+
+```bash
+pip install foldmetrics
+```
+
+(conda-forge packaging is planned; until then use pip inside a conda env.)
+
+Development install:
+
+```bash
+git clone https://github.com/ChiaChunL/foldmetrics.git && cd foldmetrics
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+CLI (`foldmetrics`, short alias `fmx`):
+
+```bash
+# score every prediction found under a directory (any mix of tools)
+foldmetrics score path/to/predictions/ -o metrics.tsv
+
+# per chain-pair breakdown + summary figures (pLDDT track, PAE heatmap, metrics)
+fmx score preds/ -o metrics.tsv --interfaces interfaces.tsv --plot plots/
+
+# a single model: point at any of its files
+fmx score run1/fold_job_full_data_0.json
+
+# one metric only (every metric name is also a subcommand)
+fmx ipsae preds/ --interfaces ipsae_per_pair.tsv
+fmx score preds/ --metrics ipsae,pdockq2,lis
+
+# what would be scored?
+fmx detect preds/
+
+# figures only
+fmx plot preds/ -o plots/
+```
+
+Python:
+
+```python
+import foldmetrics as fm
+
+df = fm.evaluate("path/to/predictions/")          # one row per model
+dfi = fm.evaluate_interfaces("path/to/predictions/")  # one row per chain pair
+
+# lower-level access
+preds = fm.load_predictions("path/to/predictions/")
+summary, interfaces = fm.compute_all(preds[0])
+```
+
+More recipes (including runnable demo data that needs no prediction tool) live
+in [examples/](examples/).
+
+## Visualization
+
+`--plot DIR` (on `score` and every metric subcommand) or the `plot`
+subcommand renders publication-oriented figures, adapting automatically to
+the shape of the batch:
+
+| Input shape | Figures written into DIR |
+|---|---|
+| every model | `<model>.png` — pLDDT-colored structure + pLDDT track + PAE heatmap + metrics panel |
+| more than one model | plus `batch_overview.png` — ranked confidence dot plot + mean pLDDT bars |
+| more than one target and/or tool | plus `comparison.png` — one panel per metric, grouped by target, one color per tool |
+
+The structure panel uses **headless PyMOL** when available (auto-detected
+from `FOLDMETRICS_PYMOL`, PATH, or common conda locations; ~2–3 s per
+model) and falls back to a fast matplotlib backbone trace otherwise —
+select explicitly with `--renderer pymol|trace`. The `plot` subcommand also
+takes `--format png|pdf|svg` and `--dpi` (default 300).
+
+Single model (AlphaFold3, SARS-CoV-2 Mpro + nirmatrelvir):
+
+![per-model summary](https://raw.githubusercontent.com/ChiaChunL/foldmetrics/main/docs/assets/demo_summary.png)
+
+Targets × methods comparison (real batch: 10 complexes × 4 tools):
+
+![per-target comparison](https://raw.githubusercontent.com/ChiaChunL/foldmetrics/main/docs/assets/demo_comparison.png)
+
+Batch overview (one target, AlphaFold2 + AlphaFold3 models):
+
+![batch overview](https://raw.githubusercontent.com/ChiaChunL/foldmetrics/main/docs/assets/demo_batch.png)
+
+## Supported tools and files
+
+| Tool | Detected files | pTM/ipTM | pLDDT | PAE |
+|---|---|---|---|---|
+| ColabFold | `*_scores_rank_*.json` + `*_(un)relaxed_rank_*.pdb` | yes | yes | yes |
+| AlphaFold2 (pickle layout) | `result_model_*.pkl` + `unrelaxed_*.pdb` / `ranked_*.pdb` | yes | yes | yes |
+| AlphaFold2 (JSON layout) | `iptm_ptm.json` + `confidence_*.json` / `pae_*.json` + `unrelaxed_*.cif/.pdb` | yes | yes | yes |
+| AlphaFold3 (server/local) | `*model*.cif` + `*summary_confidences*.json` + `*confidences*/full_data*.json` | yes | yes | yes |
+| Boltz-1/2 | `confidence_*_model_*.json` + `*_model_*.cif` + `pae_*.npz` / `plddt_*.npz` | yes | yes | yes |
+| Chai-1 | `scores.model_idx_*.npz` + `pred.model_idx_*.cif` | yes | yes | if exported |
+| Protenix | `*summary_confidence*.json` + matching `.cif` (+ `*full_data*.json` with `token_pair_pae`) | yes | yes | yes |
+| HelixFold3 | planned | — | — | — |
+
+## Validation
+
+- Numerical parity with the `ipsae.py` reference implementation (Dunbrack
+  Lab) verified digit-for-digit on real AlphaFold3 server output: ipSAE
+  (both directions and d0chn variant), pDockQ, pDockQ2 and LIS all match to
+  6 decimal places at the default cutoffs (10/10).
+- Batch-tested on 720 real predictions across AlphaFold2-Multimer,
+  AlphaFold3 (server + local), Boltz-2 and Protenix — including
+  protein–small-molecule complexes, homodimers, monomers and negative
+  controls — with zero parse errors; known binders score ipSAE 0.9+, decoy
+  pairs < 0.1, monomers report NA.
+- ColabFold and Chai-1 parsers are currently validated on synthetic
+  fixtures only; real-output samples welcome.
+
+Native per-tool extras (e.g. Boltz `complex_iplddt`/`ligand_iptm`, AF3
+`chain_pair_pae_min`, Chai clash flags) are preserved on
+`Prediction.extras` and chain-pair ipTM is surfaced as `iptm_native` in the
+interface table.
+
+## What each metric needs
+
+The structure file is always required (it defines chains and tokens); the
+table shows which additional inputs each metric consumes. When an input is
+missing the metric is `NA` and a note lands in the `warnings` column —
+nothing crashes.
+
+| Metric (= subcommand) | pLDDT | Coordinates | PAE | Source |
+|---|---|---|---|---|
+| `ptm`, `iptm`, `ranking` | – | – | – | read from the tool's confidence file |
+| `plddt` (mean pLDDT, ipLDDT) | yes | ipLDDT only | – | B-factors, or the tool's pLDDT file |
+| `pae` (mean PAE, inter-chain PAE) | – | – | yes | tool's PAE matrix |
+| `pdockq` | yes | yes | – | contacts at 8 Å between CB/C3' atoms |
+| `pdockq2` | yes | yes | yes | |
+| `ipsae`, `lis` | – | – | yes | chain mapping from the structure |
+
+## Outputs and paths
+
+- Summary table → stdout; `-o FILE` writes it. The extension picks the
+  format: `.tsv` (default), `.csv`, `.json`; missing values are `NA`.
+- `--interfaces FILE` → the per chain-pair table (same formats).
+- `--plot DIR` → figures as described under Visualization; model names are
+  sanitized (`[^\w.-]` → `_`) for use as filenames.
+- `plot -o DIR` defaults to `./foldmetrics_plots/`.
+- Exit codes: `0` success, `1` nothing recognized/found, `2` bad arguments.
+
+## Conventions worth knowing
+
+- **Tokens.** Standard residues are one token; ligands and modified residues
+  are one token per heavy atom (AF3-style), so token-level PAE matrices line
+  up across tools. pLDDT is stored on the 0–100 scale everywhere (Boltz 0–1
+  values are rescaled).
+- **Complex-level interface metrics are the best interface.** For >2 chains,
+  `ipsae`/`pdockq`/`pdockq2`/`lis` in the summary table are the maximum over
+  chain pairs; use `--interfaces` for the full breakdown.
+- **Ligand interfaces.** `pdockq`/`pdockq2`/`iplddt` are defined for
+  polymer–polymer interfaces only. For chain pairs involving a ligand chain,
+  `ipsae`/`lis` are computed over ligand atom tokens (experimental) and marked
+  `ipsae_mode = "tokens"` in the interface table.
+- **Missing data degrades gracefully.** No PAE → PAE-based metrics are NaN
+  and a note lands in the `warnings` column; nothing crashes.
+- **Directionality.** PAE is asymmetric, so `pdockq2`/`ipsae`/`lis` have two
+  directional values; the interface table reports both (`*_ab`, `*_ba`) plus
+  the aggregate used everywhere else (max for ipSAE/pDockQ2, mean for LIS,
+  matching the reference implementations).
+
+## References
+
+- Bryant P, Pozzati G, Elofsson A. *Improved prediction of protein-protein
+  interactions using AlphaFold2.* Nat Commun 13, 1265 (2022). — pDockQ
+- Zhu W, Shenoy A, Kundrotas P, Elofsson A. *Evaluation of AlphaFold-Multimer
+  prediction on multi-chain protein complexes.* Bioinformatics 39, btad424
+  (2023). — pDockQ2
+- Dunbrack RL. *ipSAE: scoring pairwise interactions in AlphaFold models.*
+  bioRxiv 10.1101/2025.02.10.637595 (2025). — ipSAE
+- Kim AR et al. *Enhanced protein-protein interaction discovery via
+  AlphaFold-Multimer.* bioRxiv 10.1101/2024.02.19.580970 (2024). — LIS
+
+## Roadmap
+
+- HelixFold3 parser (sample outputs welcome — please open an issue)
+- Real-output samples for ColabFold and Chai-1
+- Per-interface PAE/ipSAE figures; interactive HTML report
+- conda-forge feedstock; CI (lint + tests) on GitHub Actions
+
+## License
+
+MIT

foldmetrics-0.1.0/README.md

@@ -0,0 +1,211 @@
+# foldmetrics
+
+Unified confidence metrics for structure-prediction models.
+
+`foldmetrics` ingests the raw output folders of the mainstream structure
+predictors — **AlphaFold2 / AlphaFold-Multimer, ColabFold, AlphaFold3, Boltz,
+Chai-1, Protenix** — and computes a consistent set of quality metrics for
+monomers and complexes (protein, nucleic acid and small-molecule ligands),
+for a single model or whole batches:
+
+| Metric | What it tells you | Source |
+|---|---|---|
+| `ptm`, `iptm` | global / interface predicted TM-score | read from tool output |
+| `ranking_score` | tool-native model ranking (AF3 `ranking_score`, Boltz `confidence_score`, Chai `aggregate_score`, AF2 `ranking_confidence`) | read from tool output |
+| `plddt_mean` | mean per-token pLDDT | computed |
+| `iplddt` | mean pLDDT over interface residues (contact atoms within 8 Å across chains) | computed |
+| `pae_mean`, `ipae_mean` | mean PAE (all off-diagonal / inter-chain blocks) | computed |
+| `ipsae` | interface score from PAE with per-residue d0 (Dunbrack 2025) | computed |
+| `pdockq` | interface score from contacts + pLDDT (Bryant 2022) | computed |
+| `pdockq2` | interface score from contacts + pLDDT + PAE (Zhu 2023) | computed |
+| `lis` | Local Interaction Score from PAE (Kim 2024) | computed |
+
+Computed metrics were validated against the `ipsae.py` reference
+implementation (Dunbrack Lab), including its exact `d0` conventions.
+
+## Install
+
+```bash
+pip install foldmetrics
+```
+
+(conda-forge packaging is planned; until then use pip inside a conda env.)
+
+Development install:
+
+```bash
+git clone https://github.com/ChiaChunL/foldmetrics.git && cd foldmetrics
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+CLI (`foldmetrics`, short alias `fmx`):
+
+```bash
+# score every prediction found under a directory (any mix of tools)
+foldmetrics score path/to/predictions/ -o metrics.tsv
+
+# per chain-pair breakdown + summary figures (pLDDT track, PAE heatmap, metrics)
+fmx score preds/ -o metrics.tsv --interfaces interfaces.tsv --plot plots/
+
+# a single model: point at any of its files
+fmx score run1/fold_job_full_data_0.json
+
+# one metric only (every metric name is also a subcommand)
+fmx ipsae preds/ --interfaces ipsae_per_pair.tsv
+fmx score preds/ --metrics ipsae,pdockq2,lis
+
+# what would be scored?
+fmx detect preds/
+
+# figures only
+fmx plot preds/ -o plots/
+```
+
+Python:
+
+```python
+import foldmetrics as fm
+
+df = fm.evaluate("path/to/predictions/")          # one row per model
+dfi = fm.evaluate_interfaces("path/to/predictions/")  # one row per chain pair
+
+# lower-level access
+preds = fm.load_predictions("path/to/predictions/")
+summary, interfaces = fm.compute_all(preds[0])
+```
+
+More recipes (including runnable demo data that needs no prediction tool) live
+in [examples/](examples/).
+
+## Visualization
+
+`--plot DIR` (on `score` and every metric subcommand) or the `plot`
+subcommand renders publication-oriented figures, adapting automatically to
+the shape of the batch:
+
+| Input shape | Figures written into DIR |
+|---|---|
+| every model | `<model>.png` — pLDDT-colored structure + pLDDT track + PAE heatmap + metrics panel |
+| more than one model | plus `batch_overview.png` — ranked confidence dot plot + mean pLDDT bars |
+| more than one target and/or tool | plus `comparison.png` — one panel per metric, grouped by target, one color per tool |
+
+The structure panel uses **headless PyMOL** when available (auto-detected
+from `FOLDMETRICS_PYMOL`, PATH, or common conda locations; ~2–3 s per
+model) and falls back to a fast matplotlib backbone trace otherwise —
+select explicitly with `--renderer pymol|trace`. The `plot` subcommand also
+takes `--format png|pdf|svg` and `--dpi` (default 300).
+
+Single model (AlphaFold3, SARS-CoV-2 Mpro + nirmatrelvir):
+
+![per-model summary](https://raw.githubusercontent.com/ChiaChunL/foldmetrics/main/docs/assets/demo_summary.png)
+
+Targets × methods comparison (real batch: 10 complexes × 4 tools):
+
+![per-target comparison](https://raw.githubusercontent.com/ChiaChunL/foldmetrics/main/docs/assets/demo_comparison.png)
+
+Batch overview (one target, AlphaFold2 + AlphaFold3 models):
+
+![batch overview](https://raw.githubusercontent.com/ChiaChunL/foldmetrics/main/docs/assets/demo_batch.png)
+
+## Supported tools and files
+
+| Tool | Detected files | pTM/ipTM | pLDDT | PAE |
+|---|---|---|---|---|
+| ColabFold | `*_scores_rank_*.json` + `*_(un)relaxed_rank_*.pdb` | yes | yes | yes |
+| AlphaFold2 (pickle layout) | `result_model_*.pkl` + `unrelaxed_*.pdb` / `ranked_*.pdb` | yes | yes | yes |
+| AlphaFold2 (JSON layout) | `iptm_ptm.json` + `confidence_*.json` / `pae_*.json` + `unrelaxed_*.cif/.pdb` | yes | yes | yes |
+| AlphaFold3 (server/local) | `*model*.cif` + `*summary_confidences*.json` + `*confidences*/full_data*.json` | yes | yes | yes |
+| Boltz-1/2 | `confidence_*_model_*.json` + `*_model_*.cif` + `pae_*.npz` / `plddt_*.npz` | yes | yes | yes |
+| Chai-1 | `scores.model_idx_*.npz` + `pred.model_idx_*.cif` | yes | yes | if exported |
+| Protenix | `*summary_confidence*.json` + matching `.cif` (+ `*full_data*.json` with `token_pair_pae`) | yes | yes | yes |
+| HelixFold3 | planned | — | — | — |
+
+## Validation
+
+- Numerical parity with the `ipsae.py` reference implementation (Dunbrack
+  Lab) verified digit-for-digit on real AlphaFold3 server output: ipSAE
+  (both directions and d0chn variant), pDockQ, pDockQ2 and LIS all match to
+  6 decimal places at the default cutoffs (10/10).
+- Batch-tested on 720 real predictions across AlphaFold2-Multimer,
+  AlphaFold3 (server + local), Boltz-2 and Protenix — including
+  protein–small-molecule complexes, homodimers, monomers and negative
+  controls — with zero parse errors; known binders score ipSAE 0.9+, decoy
+  pairs < 0.1, monomers report NA.
+- ColabFold and Chai-1 parsers are currently validated on synthetic
+  fixtures only; real-output samples welcome.
+
+Native per-tool extras (e.g. Boltz `complex_iplddt`/`ligand_iptm`, AF3
+`chain_pair_pae_min`, Chai clash flags) are preserved on
+`Prediction.extras` and chain-pair ipTM is surfaced as `iptm_native` in the
+interface table.
+
+## What each metric needs
+
+The structure file is always required (it defines chains and tokens); the
+table shows which additional inputs each metric consumes. When an input is
+missing the metric is `NA` and a note lands in the `warnings` column —
+nothing crashes.
+
+| Metric (= subcommand) | pLDDT | Coordinates | PAE | Source |
+|---|---|---|---|---|
+| `ptm`, `iptm`, `ranking` | – | – | – | read from the tool's confidence file |
+| `plddt` (mean pLDDT, ipLDDT) | yes | ipLDDT only | – | B-factors, or the tool's pLDDT file |
+| `pae` (mean PAE, inter-chain PAE) | – | – | yes | tool's PAE matrix |
+| `pdockq` | yes | yes | – | contacts at 8 Å between CB/C3' atoms |
+| `pdockq2` | yes | yes | yes | |
+| `ipsae`, `lis` | – | – | yes | chain mapping from the structure |
+
+## Outputs and paths
+
+- Summary table → stdout; `-o FILE` writes it. The extension picks the
+  format: `.tsv` (default), `.csv`, `.json`; missing values are `NA`.
+- `--interfaces FILE` → the per chain-pair table (same formats).
+- `--plot DIR` → figures as described under Visualization; model names are
+  sanitized (`[^\w.-]` → `_`) for use as filenames.
+- `plot -o DIR` defaults to `./foldmetrics_plots/`.
+- Exit codes: `0` success, `1` nothing recognized/found, `2` bad arguments.
+
+## Conventions worth knowing
+
+- **Tokens.** Standard residues are one token; ligands and modified residues
+  are one token per heavy atom (AF3-style), so token-level PAE matrices line
+  up across tools. pLDDT is stored on the 0–100 scale everywhere (Boltz 0–1
+  values are rescaled).
+- **Complex-level interface metrics are the best interface.** For >2 chains,
+  `ipsae`/`pdockq`/`pdockq2`/`lis` in the summary table are the maximum over
+  chain pairs; use `--interfaces` for the full breakdown.
+- **Ligand interfaces.** `pdockq`/`pdockq2`/`iplddt` are defined for
+  polymer–polymer interfaces only. For chain pairs involving a ligand chain,
+  `ipsae`/`lis` are computed over ligand atom tokens (experimental) and marked
+  `ipsae_mode = "tokens"` in the interface table.
+- **Missing data degrades gracefully.** No PAE → PAE-based metrics are NaN
+  and a note lands in the `warnings` column; nothing crashes.
+- **Directionality.** PAE is asymmetric, so `pdockq2`/`ipsae`/`lis` have two
+  directional values; the interface table reports both (`*_ab`, `*_ba`) plus
+  the aggregate used everywhere else (max for ipSAE/pDockQ2, mean for LIS,
+  matching the reference implementations).
+
+## References
+
+- Bryant P, Pozzati G, Elofsson A. *Improved prediction of protein-protein
+  interactions using AlphaFold2.* Nat Commun 13, 1265 (2022). — pDockQ
+- Zhu W, Shenoy A, Kundrotas P, Elofsson A. *Evaluation of AlphaFold-Multimer
+  prediction on multi-chain protein complexes.* Bioinformatics 39, btad424
+  (2023). — pDockQ2
+- Dunbrack RL. *ipSAE: scoring pairwise interactions in AlphaFold models.*
+  bioRxiv 10.1101/2025.02.10.637595 (2025). — ipSAE
+- Kim AR et al. *Enhanced protein-protein interaction discovery via
+  AlphaFold-Multimer.* bioRxiv 10.1101/2024.02.19.580970 (2024). — LIS
+
+## Roadmap
+
+- HelixFold3 parser (sample outputs welcome — please open an issue)
+- Real-output samples for ColabFold and Chai-1
+- Per-interface PAE/ipSAE figures; interactive HTML report
+- conda-forge feedstock; CI (lint + tests) on GitHub Actions
+
+## License
+
+MIT

foldmetrics-0.1.0/examples/README.md

@@ -0,0 +1,92 @@
+# Examples
+
+Everything here runs without any prediction tool installed: `make_demo_data.py`
+generates realistic synthetic AlphaFold3-style outputs to play with. Substitute
+your real prediction folders anywhere a `demo_predictions` path appears.
+
+```bash
+python examples/make_demo_data.py demo_predictions
+```
+
+## CLI recipes
+
+`fmx` is a short alias for `foldmetrics`; they are identical.
+
+### Score a batch (any mix of supported tools, scanned recursively)
+
+```bash
+fmx score demo_predictions -o metrics.tsv --interfaces interfaces.tsv --plot plots
+```
+
+stdout (also written to `metrics.tsv`; missing values are written as `NA`):
+
+```
+                   model       tool chains  n_chains  n_tokens  n_res   ptm  iptm  ranking_score  plddt_mean  iplddt  pae_mean  ipae_mean  ipsae  pdockq  pdockq2   lis  n_interfaces  has_pae
+complex_with_ligand_poor alphafold3  A,B,C         3       180    170 0.680 0.380          0.450      69.624  68.924    12.315     19.943  0.266   0.467    0.011 0.473             1     True
+              dimer_good alphafold3    A,B         2       195    195 0.870 0.820          0.840      88.462  88.645     3.824      4.310  0.488   0.712    0.436 0.641             1     True
+ receptor_peptide_medium alphafold3    A,B         2       170    170 0.720 0.550          0.580      81.796  72.580     6.130     11.326  0.052   0.278    0.029 0.142             1     True
+```
+
+Reading `complex_with_ligand_poor` is instructive: `pdockq` is deceptively
+decent (0.47 — it only sees contacts and pLDDT) while `pdockq2` (0.011) and the
+per-pair ipSAE expose the bad protein–protein interface; the summary `ipsae`
+(0.266) comes from the *best* interface, which is the protein–ligand pair.
+The `--interfaces` table shows exactly this breakdown per chain pair, including
+the two directional values (`*_ab`, `*_ba`) and the tool's own chain-pair ipTM
+(`iptm_native`).
+
+`--plot plots/` writes one summary figure per model (pLDDT-colored structure
++ pLDDT track + PAE heatmap + metrics panel), plus `batch_overview.png` when
+there are several models, plus `comparison.png` (targets x methods, one panel
+per metric) when the batch spans several targets or tools. The structure
+panel uses headless PyMOL when installed (auto-detected; ~2-3 s per model) and
+a fast matplotlib backbone trace otherwise:
+
+```bash
+fmx plot demo_predictions -o plots --renderer trace   # fast, no PyMOL
+fmx plot demo_predictions -o plots --format pdf       # vector output
+```
+
+### Single metrics
+
+Every metric name is also a subcommand, so computing just one metric over a
+batch is:
+
+```bash
+fmx ipsae demo_predictions                      # only ipSAE columns
+fmx pdockq2 demo_predictions -o pdockq2.tsv     # same options as 'score'
+fmx score demo_predictions --metrics ipsae,lis  # any subset
+```
+
+Available names: `ptm`, `iptm`, `ranking`, `plddt`, `pae`, `ipsae`,
+`pdockq`, `pdockq2`, `lis`.
+
+### Other commands
+
+```bash
+fmx detect demo_predictions            # list what would be scored, per tool
+fmx plot demo_predictions -o plots     # figures only
+fmx score run1/fold_x_full_data_0.json # a single model, via any of its files
+fmx score preds/ --tool boltz          # restrict auto-detection to one tool
+fmx score preds/ --pae-cutoff 15       # loosen the ipSAE PAE cutoff
+fmx score run1/ run2/ model_dir/       # any number of paths
+```
+
+Output formats follow the file extension: `.tsv` (default), `.csv`, `.json`.
+
+## Python API
+
+See [python_api.py](python_api.py) for a complete walkthrough:
+
+```bash
+python examples/python_api.py demo_predictions
+```
+
+It covers:
+
+1. `fm.evaluate(path)` — summary DataFrame (one row per model)
+2. `fm.evaluate_interfaces(path)` — per chain-pair DataFrame
+3. `fm.load_predictions` + `fm.compute_all` — full access to one model,
+   including per-residue ipSAE profiles via `foldmetrics.metrics.ipsae_asym`
+4. Figures: `save_summary_plot`, `save_batch_plot`, and composing your own
+   figure from `plot_plddt` / `plot_pae`