foldreport 0.1.0__py3-none-any.whl

foldreport/__init__.py

@@ -0,0 +1,16 @@
+"""FoldReport — unify structure-prediction outputs into a single HTML report."""
+
+from foldreport.models import (
+    Chain,
+    Prediction,
+    PredictionMetrics,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Chain",
+    "Prediction",
+    "PredictionMetrics",
+    "__version__",
+]

foldreport/cli.py

@@ -0,0 +1,78 @@
+"""Command-line interface: ``foldreport <folder> [...] -o report.html``.
+
+Point it at one or more folders of predictions. Each folder's format is autodetected;
+all predictions are pooled, ranked by confidence, and written to a single HTML file.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+from foldreport import __version__
+from foldreport.metrics import ranked_dataframe
+from foldreport.parsers import detect_parser, parse_folder
+from foldreport.report import build_report
+
+
+@click.command(context_settings={"help_option_names": ["-h", "--help"]})
+@click.argument(
+    "folders",
+    nargs=-1,
+    required=True,
+    type=click.Path(exists=True, file_okay=False, dir_okay=True, path_type=Path),
+)
+@click.option(
+    "-o",
+    "--output",
+    type=click.Path(dir_okay=False, path_type=Path),
+    default=Path("foldreport.html"),
+    show_default=True,
+    help="Path of the self-contained HTML report to write.",
+)
+@click.option(
+    "-t",
+    "--title",
+    default="FoldReport",
+    show_default=True,
+    help="Title shown at the top of the report.",
+)
+@click.option(
+    "--csv",
+    type=click.Path(dir_okay=False, path_type=Path),
+    default=None,
+    help="Also write the ranked metrics table to this CSV path.",
+)
+@click.version_option(__version__, "-V", "--version", prog_name="foldreport")
+def main(folders: tuple[Path, ...], output: Path, title: str, csv: Path | None) -> None:
+    """Build a single HTML report from prediction FOLDERS.
+
+    Supported tools (autodetected): ColabFold, AlphaFold 3 Server, Boltz, OpenFold3,
+    and AlphaFold DB downloads.
+    """
+    predictions = []
+    for folder in folders:
+        parser = detect_parser(folder)
+        if parser is None:
+            click.echo(f"  ! Skipping {folder}: no supported format detected.", err=True)
+            continue
+        found = parse_folder(folder)
+        click.echo(f"  + {folder}: {len(found)} prediction(s) via '{parser.name}'.")
+        predictions.extend(found)
+
+    if not predictions:
+        click.echo("No predictions found in the given folder(s).", err=True)
+        sys.exit(1)
+
+    if csv is not None:
+        ranked_dataframe(predictions).to_csv(csv, index=False)
+        click.echo(f"  > Metrics table: {csv}")
+
+    out_path = build_report(predictions, output, title=title)
+    click.echo(f"  > Report ({len(predictions)} predictions): {out_path}")
+
+
+if __name__ == "__main__":
+    main()

foldreport/figures.py

@@ -0,0 +1,125 @@
+"""Publication-quality static figures: PAE and per-residue pLDDT.
+
+Figures are rendered with a non-interactive matplotlib backend and returned as base64
+PNG data URIs so the report can embed them with zero external files. Predictions that
+lack a given metric simply produce no figure (the caller renders "N/A").
+"""
+
+from __future__ import annotations
+
+import base64
+import io
+
+import matplotlib
+
+matplotlib.use("Agg")  # Headless: never requires a display server.
+
+import matplotlib.pyplot as plt
+import numpy as np
+from matplotlib.figure import Figure
+
+from foldreport.models import Prediction
+
+# pLDDT confidence bands used by the AlphaFold family (0-100 scale).
+_PLDDT_BANDS = [
+    (90, 100, "#0053D6", "Very high (90-100)"),
+    (70, 90, "#65CBF3", "Confident (70-90)"),
+    (50, 70, "#FFDB13", "Low (50-70)"),
+    (0, 50, "#FF7D45", "Very low (0-50)"),
+]
+
+
+def _fig_to_data_uri(fig: Figure, dpi: int = 150) -> str:
+    buf = io.BytesIO()
+    fig.savefig(buf, format="png", dpi=dpi, bbox_inches="tight")
+    plt.close(fig)
+    encoded = base64.b64encode(buf.getvalue()).decode("ascii")
+    return f"data:image/png;base64,{encoded}"
+
+
+def plddt_figure(pred: Prediction) -> str | None:
+    """Per-residue pLDDT line plot with confidence bands. Returns a PNG data URI."""
+    if not pred.plddt:
+        return None
+    plddt = np.asarray(pred.plddt, dtype=float)
+    x = np.arange(1, len(plddt) + 1)
+
+    fig, ax = plt.subplots(figsize=(7, 2.6))
+    for low, high, color, _label in _PLDDT_BANDS:
+        ax.axhspan(low, high, color=color, alpha=0.12, linewidth=0)
+    ax.plot(x, plddt, color="#1a1a1a", linewidth=1.2)
+
+    _draw_chain_boundaries(ax, pred)
+
+    ax.set_xlim(1, len(plddt))
+    ax.set_ylim(0, 100)
+    ax.set_xlabel("Residue")
+    ax.set_ylabel("pLDDT")
+    ax.set_title("Per-residue pLDDT")
+    ax.grid(True, axis="y", alpha=0.2)
+    return _fig_to_data_uri(fig)
+
+
+def pae_figure(pred: Prediction) -> str | None:
+    """PAE heatmap (Predicted Aligned Error). Returns a PNG data URI or None."""
+    if pred.pae is None:
+        return None
+    pae = np.asarray(pred.pae, dtype=float)
+    if pae.ndim != 2:
+        return None
+
+    fig, ax = plt.subplots(figsize=(4.2, 3.6))
+    im = ax.imshow(pae, cmap="Greens_r", vmin=0, vmax=max(float(pae.max()), 1.0), origin="upper")
+    ax.set_xlabel("Scored residue")
+    ax.set_ylabel("Aligned residue")
+    ax.set_title("Predicted Aligned Error")
+    cbar = fig.colorbar(im, ax=ax, fraction=0.046, pad=0.04)
+    cbar.set_label("Expected position error (Å)")
+
+    _draw_pae_chain_lines(ax, pred)
+    return _fig_to_data_uri(fig)
+
+
+def _chain_offsets(pred: Prediction) -> list[int]:
+    """Cumulative residue offsets at chain boundaries (excluding the final end)."""
+    offsets: list[int] = []
+    cumulative = 0
+    for chain in pred.chains[:-1]:
+        cumulative += chain.n_residues
+        offsets.append(cumulative)
+    return offsets
+
+
+def _draw_chain_boundaries(ax, pred: Prediction) -> None:
+    for boundary in _chain_offsets(pred):
+        ax.axvline(boundary + 0.5, color="#888888", linestyle="--", linewidth=0.8)
+
+
+def _draw_pae_chain_lines(ax, pred: Prediction) -> None:
+    for boundary in _chain_offsets(pred):
+        ax.axhline(boundary - 0.5, color="#444444", linewidth=0.6)
+        ax.axvline(boundary - 0.5, color="#444444", linewidth=0.6)
+
+
+def pae_data_for_js(pred: Prediction) -> dict | None:
+    """Return PAE matrix data for the interactive JS heatmap, or None."""
+    if pred.pae is None:
+        return None
+    pae = np.asarray(pred.pae, dtype=float)
+    if pae.ndim != 2:
+        return None
+    return {
+        "matrix": np.round(pae, 2).tolist(),
+        "size": int(pae.shape[0]),
+        "max_val": round(float(pae.max()), 2),
+        "chain_boundaries": _chain_offsets(pred),
+    }
+
+
+def make_figures(pred: Prediction) -> dict[str, str | None]:
+    """Return both figures for a prediction as a dict of data URIs (or None)."""
+    return {
+        "plddt": plddt_figure(pred),
+        "pae": pae_figure(pred),
+        "pae_interactive": pae_data_for_js(pred),
+    }

foldreport/metrics.py

@@ -0,0 +1,89 @@
+"""Normalize a list of predictions into a sortable/filterable metrics table.
+
+The table has exactly one row per prediction. Missing metrics stay as ``None`` (which
+pandas renders as ``NaN``); nothing here invents values. The default ranking key is a
+confidence score that gracefully falls back when a tool omits a metric.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import pandas as pd
+
+from foldreport.models import Prediction
+
+# Columns in display order. Keep human-readable; the report renders these as headers.
+COLUMNS = [
+    "name",
+    "source_tool",
+    "rank",
+    "mean_plddt",
+    "ptm",
+    "iptm",
+    "mpdockq",
+    "ranking_score",
+    "n_chains",
+    "n_residues",
+]
+
+
+def metrics_dataframe(predictions: Sequence[Prediction]) -> pd.DataFrame:
+    """Build a one-row-per-prediction DataFrame of normalized metrics."""
+    rows = []
+    for pred in predictions:
+        m = pred.metrics
+        rows.append(
+            {
+                "name": pred.name,
+                "source_tool": pred.source_tool,
+                "rank": pred.rank,
+                "mean_plddt": m.mean_plddt,
+                "ptm": m.ptm,
+                "iptm": m.iptm,
+                "mpdockq": m.mpdockq,
+                "ranking_score": m.ranking_score,
+                "n_chains": m.n_chains,
+                "n_residues": m.n_residues,
+            }
+        )
+    df = pd.DataFrame(rows, columns=COLUMNS)
+    return df
+
+
+def confidence_score(pred: Prediction) -> float:
+    """A single comparable confidence value used to rank predictions.
+
+    Preference order, using whatever the tool provided:
+        1. ipTM (complexes) blended with pTM: 0.8*ipTM + 0.2*pTM
+        2. pTM alone
+        3. mean pLDDT scaled to 0-1
+        4. the tool's own ranking_score
+        5. 0.0 as a last resort (keeps it sortable, sorts last)
+    """
+    m = pred.metrics
+    if m.iptm is not None and m.ptm is not None:
+        return 0.8 * m.iptm + 0.2 * m.ptm
+    if m.iptm is not None:
+        return m.iptm
+    if m.ptm is not None:
+        return m.ptm
+    if m.mean_plddt is not None:
+        return m.mean_plddt / 100.0
+    if m.ranking_score is not None:
+        return m.ranking_score
+    return 0.0
+
+
+def rank_predictions(predictions: Sequence[Prediction]) -> list[Prediction]:
+    """Return predictions sorted by descending confidence (best first)."""
+    return sorted(predictions, key=confidence_score, reverse=True)
+
+
+def ranked_dataframe(predictions: Sequence[Prediction]) -> pd.DataFrame:
+    """Metrics table sorted best-first, with a 1-based ``overall_rank`` column."""
+    ordered = rank_predictions(predictions)
+    df = metrics_dataframe(ordered)
+    df.insert(0, "overall_rank", range(1, len(df) + 1))
+    df["confidence"] = [round(confidence_score(p), 4) for p in ordered]
+    return df

foldreport/models.py

@@ -0,0 +1,75 @@
+"""Internal representation shared by every parser.
+
+This is the core abstraction of FoldReport: each parser converts the on-disk output
+of a prediction tool into ``list[Prediction]`` objects. Nothing downstream (metrics,
+figures, report) knows the original format. Adding a new tool means writing a parser
+that produces these dataclasses, not touching the rest of the codebase.
+
+Missing values are always ``None`` — never invented. The report renders them as "N/A".
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import numpy as np
+
+
+@dataclass
+class Chain:
+    """A single polymer chain within a predicted structure."""
+
+    chain_id: str
+    n_residues: int
+    sequence: str | None = None  # one-letter sequence, if known
+
+
+@dataclass
+class PredictionMetrics:
+    """Normalized confidence metrics for one prediction.
+
+    Any metric a tool does not provide stays ``None``; downstream code must tolerate
+    holes and never fabricate a value.
+    """
+
+    mean_plddt: float | None = None
+    ptm: float | None = None
+    iptm: float | None = None
+    mpdockq: float | None = None
+    n_chains: int = 0
+    n_residues: int = 0
+    # Optional ranking score reported by some tools (e.g. AF3 Server "ranking_score").
+    ranking_score: float | None = None
+
+
+@dataclass
+class Prediction:
+    """A single predicted model, normalized across tools.
+
+    Attributes:
+        name: Human-readable identifier (usually derived from the file name).
+        source_tool: One of "colabfold", "af3_server", "boltz", ...
+        structure_path: Path to the ``.cif``/``.pdb`` holding coordinates.
+        chains: Per-chain metadata in canonical order.
+        plddt: Per-residue pLDDT in canonical residue order (0-100). Empty if unknown.
+        pae: Predicted Aligned Error matrix (N_tokens x N_tokens) or ``None``.
+        metrics: Normalized scalar metrics.
+        rank: Tool-reported rank (1 = best) when available, else ``None``.
+        raw_files: Provenance — maps a logical role to the file it came from.
+    """
+
+    name: str
+    source_tool: str
+    structure_path: Path
+    chains: list[Chain] = field(default_factory=list)
+    plddt: list[float] = field(default_factory=list)
+    pae: np.ndarray | None = None
+    metrics: PredictionMetrics = field(default_factory=PredictionMetrics)
+    rank: int | None = None
+    raw_files: dict[str, Path] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        # Keep the PAE as a float ndarray for consistent downstream handling.
+        if self.pae is not None and not isinstance(self.pae, np.ndarray):
+            self.pae = np.asarray(self.pae, dtype=float)

foldreport/parsers/__init__.py

@@ -0,0 +1,65 @@
+"""Parser registry and format autodetection.
+
+Each tool-specific parser registers here. ``detect_parser`` asks every parser whether
+it recognizes a folder, so the user never has to declare the format.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from foldreport.models import Prediction
+from foldreport.parsers.af3_server import Af3ServerParser
+from foldreport.parsers.alphafold_db import AlphaFoldDBParser
+from foldreport.parsers.base import Parser
+from foldreport.parsers.boltz import BoltzParser
+from foldreport.parsers.colabfold import ColabFoldParser
+from foldreport.parsers.openfold3 import OpenFold3Parser
+
+# Order matters only as a tie-breaker; can_handle checks should be mutually exclusive
+# in practice. More specific layouts come first.
+ALL_PARSERS: list[Parser] = [
+    ColabFoldParser(),
+    Af3ServerParser(),
+    OpenFold3Parser(),
+    AlphaFoldDBParser(),
+    BoltzParser(),
+]
+
+
+def detect_parser(path: Path) -> Parser | None:
+    """Return the first parser that recognizes ``path``, or None."""
+    path = Path(path)
+    for parser in ALL_PARSERS:
+        if parser.can_handle(path):
+            return parser
+    return None
+
+
+def parse_folder(path: Path) -> list[Prediction]:
+    """Autodetect the tool for ``path`` and parse all predictions.
+
+    Raises:
+        ValueError: if no registered parser recognizes the folder.
+    """
+    path = Path(path)
+    parser = detect_parser(path)
+    if parser is None:
+        raise ValueError(
+            f"No registered parser recognizes the folder: {path}. "
+            f"Supported tools: {', '.join(p.name for p in ALL_PARSERS)}."
+        )
+    return parser.parse(path)
+
+
+__all__ = [
+    "ALL_PARSERS",
+    "Parser",
+    "ColabFoldParser",
+    "Af3ServerParser",
+    "BoltzParser",
+    "OpenFold3Parser",
+    "AlphaFoldDBParser",
+    "detect_parser",
+    "parse_folder",
+]

foldreport/parsers/af3_server.py

@@ -0,0 +1,129 @@
+"""Parser for AlphaFold 3 Server output folders.
+
+The AF3 Server download contains, per job, five ranked models plus JSON sidecars::
+
+    fold_<job>_model_0.cif ... fold_<job>_model_4.cif
+    fold_<job>_full_data_0.json          -> atom_plddts, pae, token_chain_ids, ...
+    fold_<job>_summary_confidences_0.json -> ptm, iptm, ranking_score, ...
+    fold_<job>_job_request.json
+    terms_of_use.md
+
+pLDDT is stored both per-atom in ``full_data`` and in the mmCIF B-factor column; we
+read per-residue pLDDT from the B-factors for consistency with the other parsers.
+The PAE matrix (per token) comes from ``full_data``.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+import numpy as np
+
+from foldreport.models import Prediction, PredictionMetrics
+from foldreport.parsers import base
+
+_MODEL_RE = re.compile(r"^(?P<job>.+)_model_(?P<idx>\d+)\.(?:cif|pdb)$")
+_SUMMARY_RE = re.compile(r"^(?P<job>.+)_summary_confidences_(?P<idx>\d+)\.json$")
+_FULLDATA_RE = re.compile(r"^(?P<job>.+)_full_data_(?P<idx>\d+)\.json$")
+
+
+class Af3ServerParser:
+    """Parse a folder produced by the AlphaFold 3 Server."""
+
+    name = "af3_server"
+
+    def can_handle(self, path: Path) -> bool:
+        path = Path(path)
+        if not path.is_dir():
+            return False
+        has_summary = has_fulldata = False
+        for entry in path.iterdir():
+            if _SUMMARY_RE.match(entry.name):
+                has_summary = True
+            elif _FULLDATA_RE.match(entry.name):
+                has_fulldata = True
+            if has_summary and has_fulldata:
+                return True
+        return False
+
+    def parse(self, path: Path) -> list[Prediction]:
+        path = Path(path)
+        models = self._index(path, _MODEL_RE)
+        summaries = self._index(path, _SUMMARY_RE)
+        fulldata = self._index(path, _FULLDATA_RE)
+
+        predictions: list[Prediction] = []
+        for (job, idx), struct_path in sorted(models.items(), key=lambda kv: kv[0][1]):
+            summary = _load_json(summaries.get((job, idx)))
+            data = _load_json(fulldata.get((job, idx)))
+
+            plddt = base.plddt_from_bfactors(struct_path)
+            pae = _as_matrix(data.get("pae"))
+
+            structure = base.read_structure(struct_path)
+            chains = base.chains_from_structure(structure)
+            n_residues = sum(c.n_residues for c in chains)
+
+            metrics = PredictionMetrics(
+                mean_plddt=float(np.mean(plddt)) if plddt else None,
+                ptm=_as_opt_float(summary.get("ptm")),
+                iptm=_as_opt_float(summary.get("iptm")),
+                mpdockq=None,  # AF3 Server does not report mpDockQ.
+                n_chains=len(chains),
+                n_residues=n_residues,
+                ranking_score=_as_opt_float(summary.get("ranking_score")),
+            )
+
+            raw_files: dict[str, Path] = {"structure": struct_path}
+            if summaries.get((job, idx)):
+                raw_files["summary"] = summaries[(job, idx)]
+            if fulldata.get((job, idx)):
+                raw_files["full_data"] = fulldata[(job, idx)]
+
+            predictions.append(
+                Prediction(
+                    name=f"{_clean_job(job)}_model_{idx}",
+                    source_tool=self.name,
+                    structure_path=struct_path,
+                    chains=chains,
+                    plddt=plddt,
+                    pae=pae,
+                    metrics=metrics,
+                    rank=int(idx) + 1,  # model_0 is the top-ranked model
+                    raw_files=raw_files,
+                )
+            )
+        return predictions
+
+    @staticmethod
+    def _index(path: Path, pattern: re.Pattern) -> dict[tuple[str, str], Path]:
+        out: dict[tuple[str, str], Path] = {}
+        for entry in path.iterdir():
+            m = pattern.match(entry.name)
+            if m:
+                out[(m["job"], m["idx"])] = entry
+        return out
+
+
+def _clean_job(job: str) -> str:
+    return job[len("fold_"):] if job.startswith("fold_") else job
+
+
+def _load_json(path: Path | None) -> dict:
+    if path is None:
+        return {}
+    with open(path, "r", encoding="utf-8") as fh:
+        return json.load(fh)
+
+
+def _as_opt_float(value) -> float | None:
+    return None if value is None else float(value)
+
+
+def _as_matrix(value) -> np.ndarray | None:
+    if value is None:
+        return None
+    arr = np.asarray(value, dtype=float)
+    return arr if arr.ndim == 2 else None