pkasso 0.5.0__tar.gz

pkasso-0.5.0/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-Present Bind Research
+
+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.

pkasso-0.5.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: pkasso
+Version: 0.5.0
+Summary: Prediction of protonation states for small molecules
+Author: Bind Research
+Maintainer-email: Soeren von Buelow <soeren.buelow@bindresearch.org>, Thomas Loehr <thomas@bindresearch.org>
+License: MIT
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Requires-Python: <3.14,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: rdkit>=2026.03.02
+Requires-Dist: numpy<3,>=1.26
+Requires-Dist: scipy<2,>=1.11
+Requires-Dist: pyyaml<7,>=6
+Requires-Dist: svgutils<1,>=0.3
+Requires-Dist: matplotlib<4,>=3.8
+Requires-Dist: torch<3,>=2.2
+Requires-Dist: torch-geometric<3,>=2.5
+Requires-Dist: pandas<3,>=2.1
+Requires-Dist: tqdm<5,>=4.66
+Requires-Dist: click<9,>=8.1
+Requires-Dist: networkx<4,>=3.1
+Requires-Dist: ipython<9,>=8.39
+Provides-Extra: webserver
+Requires-Dist: fastapi<1,>=0.115; extra == "webserver"
+Requires-Dist: uvicorn[standard]; extra == "webserver"
+Requires-Dist: jinja2; extra == "webserver"
+Requires-Dist: python-multipart; extra == "webserver"
+Requires-Dist: itsdangerous; extra == "webserver"
+Provides-Extra: dev
+Requires-Dist: pytest<9,>=7; extra == "dev"
+Requires-Dist: pytest-cov<8,>=4; extra == "dev"
+Requires-Dist: mypy<2,>=1.10; extra == "dev"
+Requires-Dist: ruff<1,>=0.4; extra == "dev"
+Dynamic: license-file
+
+# pKasso
+
+pKasso determines protonation states for small molecules based on the pKa predictor MolGpKa (https://github.com/Xundrug/MolGpKa).
+
+One protonation microstate describes a unique charge pattern on the protonable sites of molecules. pKasso enumerates protonation microstates, screens pKa values between connected microstates, and predicts pH-dependent microstate frequencies based on the graph of free energy differences between microstates.
+
+The easiest way to run pKasso is via the **webserver**: [ADD LINK TO WEBSERVER]
+
+# Installation
+
+```
+# Create conda environment
+conda create -n pkasso python=3.12
+conda activate pkasso
+
+# Install pkasso from PyPI
+pip install pkasso
+```
+
+# Command line interface
+
+The command line interface is called via `pkasso`. 
+
+1) `pkasso single`: Calculate single pH-dependent microstate probabilities given a SMILES string
+2) `pkasso batch`: Batch process a .smi file to calculate pH-dependent microstates
+3) `pkasso scan`: Scan a pH range and plot the microstate distributions for all pH values (for a single molecule); calculate macro-pKa values.
+
+```
+pkasso --smiles 'OC(=O)C(c1ccc(O)cc1)CNCCN'
+# equivalent to
+# pkasso single --smiles 'OC(=O)C(c1ccc(O)cc1)CNCCN'
+```
+
+Get help for different pKasso options (single prediction, batch prediction, pH scan) with
+```
+pkasso --help
+pkasso single --help
+pkasso batch --help
+pkasso scan --help
+```
+
+# Python interface (e.g. in a notebook)
+
+```
+from pkasso import protonate
+
+name = 'mymolecule'
+smiles = r'OC(=O)C(c1ccc(O)cc1)CNCCN'
+pH = 7.0
+
+# Include microstates with probability of 20% compared to most probable microstate
+# Select cutoff_export = 1. to only output the most likely microstate
+cutoff_export = 0.2
+
+# protonate accepts a smiles string or an rdkit Mol as input
+smiles_out, mols_out = protonate(smiles, name=name, pH=pH, cutoff_export=cutoff_export)
+print(smiles_out)
+```
+
+For more examples, see the jupyter notebook in `example/example.ipynb`.
+
+# Local webserver
+
+A local webserver can be hosted via `pip install pkasso[webserver]` followed by calling `pkasso-web` or by downloading and running the docker image [ADD LINK].

pkasso-0.5.0/README.md

@@ -0,0 +1,64 @@
+# pKasso
+
+pKasso determines protonation states for small molecules based on the pKa predictor MolGpKa (https://github.com/Xundrug/MolGpKa).
+
+One protonation microstate describes a unique charge pattern on the protonable sites of molecules. pKasso enumerates protonation microstates, screens pKa values between connected microstates, and predicts pH-dependent microstate frequencies based on the graph of free energy differences between microstates.
+
+The easiest way to run pKasso is via the **webserver**: [ADD LINK TO WEBSERVER]
+
+# Installation
+
+```
+# Create conda environment
+conda create -n pkasso python=3.12
+conda activate pkasso
+
+# Install pkasso from PyPI
+pip install pkasso
+```
+
+# Command line interface
+
+The command line interface is called via `pkasso`. 
+
+1) `pkasso single`: Calculate single pH-dependent microstate probabilities given a SMILES string
+2) `pkasso batch`: Batch process a .smi file to calculate pH-dependent microstates
+3) `pkasso scan`: Scan a pH range and plot the microstate distributions for all pH values (for a single molecule); calculate macro-pKa values.
+
+```
+pkasso --smiles 'OC(=O)C(c1ccc(O)cc1)CNCCN'
+# equivalent to
+# pkasso single --smiles 'OC(=O)C(c1ccc(O)cc1)CNCCN'
+```
+
+Get help for different pKasso options (single prediction, batch prediction, pH scan) with
+```
+pkasso --help
+pkasso single --help
+pkasso batch --help
+pkasso scan --help
+```
+
+# Python interface (e.g. in a notebook)
+
+```
+from pkasso import protonate
+
+name = 'mymolecule'
+smiles = r'OC(=O)C(c1ccc(O)cc1)CNCCN'
+pH = 7.0
+
+# Include microstates with probability of 20% compared to most probable microstate
+# Select cutoff_export = 1. to only output the most likely microstate
+cutoff_export = 0.2
+
+# protonate accepts a smiles string or an rdkit Mol as input
+smiles_out, mols_out = protonate(smiles, name=name, pH=pH, cutoff_export=cutoff_export)
+print(smiles_out)
+```
+
+For more examples, see the jupyter notebook in `example/example.ipynb`.
+
+# Local webserver
+
+A local webserver can be hosted via `pip install pkasso[webserver]` followed by calling `pkasso-web` or by downloading and running the docker image [ADD LINK].

pkasso-0.5.0/pkasso/__init__.py

@@ -0,0 +1,15 @@
+"""Public package exports for pKasso."""
+
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = ["batch_protonate", "protonate", "scan_pH"]
+
+
+def __getattr__(name: str) -> Any:
+    if name in __all__:
+        from pkasso import py_interface
+
+        return getattr(py_interface, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

pkasso-0.5.0/pkasso/api/__init__.py

@@ -0,0 +1 @@
+"""pKasso web application."""

pkasso-0.5.0/pkasso/api/app.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import textwrap
+
+WEB_DEPENDENCIES = {
+    "fastapi": "fastapi",
+    "jinja2": "jinja2",
+    "multipart": "python-multipart",
+    "itsdangerous": "itsdangerous",
+    "uvicorn": "uvicorn",
+}
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Run the pKasso daisyUI/HTMX GUI.")
+    parser.add_argument("--host", default="0.0.0.0")
+    parser.add_argument("--port", default=8001, type=int)
+    parser.add_argument("--reload", action="store_true", help="Reload when local code changes.")
+    args = parser.parse_args()
+
+    missing = [
+        package_name for module_name, package_name in WEB_DEPENDENCIES.items() if importlib.util.find_spec(module_name) is None
+    ]
+    if missing:
+        parser.exit(
+            1,
+            "The pKasso web server dependencies are not installed.\n"
+            f"Missing: {', '.join(sorted(set(missing)))}.\n"
+            "Install them with: pip install 'pkasso[webserver]'\n",
+        )
+
+    import uvicorn
+
+    url = f"http://{args.host}:{args.port}"
+    print(
+        textwrap.dedent(f"""
+    pKasso GUI is running at {url}
+    Press Ctrl+C to stop.
+    """).strip()
+    )
+    uvicorn.run("pkasso.api.web:app", host=args.host, port=args.port, reload=args.reload)
+
+
+if __name__ == "__main__":
+    main()

pkasso-0.5.0/pkasso/api/chemistry.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+import copy
+import io
+import numpy as np
+import os
+from typing import Any
+from rdkit.Chem import AllChem
+from rdkit import Chem
+
+from .config import CUTOFF_STATES
+from .state import AppState
+
+from ..py_interface import scan_pH, protonate
+from ..postprocess import draw_mols
+
+os.environ.setdefault("MPLCONFIGDIR", "/tmp/matplotlib-pkasso")
+
+
+def _pyplot() -> Any:
+    import matplotlib
+
+    matplotlib.use("Agg")
+    import matplotlib.pyplot as plt
+
+    return plt
+
+
+def render_svg_image(svg: str | bytes) -> str:
+    if isinstance(svg, bytes):
+        return svg.decode("utf-8")
+    return svg
+
+
+def figure_to_svg(fig: Any) -> str:
+    plt = _pyplot()
+    if fig is None:
+        fig = plt.gcf()
+    elif hasattr(fig, "figure") and not hasattr(fig, "savefig"):
+        fig = fig.figure
+
+    buffer = io.StringIO()
+    fig.savefig(buffer, format="svg", bbox_inches="tight")
+    plt.close(fig)
+    return buffer.getvalue()
+
+
+def compute_prediction(state: AppState) -> None:
+
+    state.error = None
+    smiles_out, mols_out = protonate(
+        state.smiles,
+        name=state.ligand,
+        pH=state.ph,
+        cutoff_export=0.0,
+        cutoff_states=CUTOFF_STATES,
+        tautomer_search=state.tautomer_search,
+    )
+    state.smiles_out = list(smiles_out[: state.nmols_export])
+    state.mols_out = list(mols_out[: state.nmols_export])
+    state.scan = None
+    state.scan_figures.clear()
+
+
+def compute_scan(state: AppState) -> None:
+
+    state.error = None
+    state.scan = scan_pH(
+        state.smiles,
+        name=state.ligand,
+        cutoff_states=CUTOFF_STATES,
+        tautomer_search=state.tautomer_search,
+        pHs=np.arange(0, 14.1, 0.25, dtype=np.float64),
+    )
+    state.scan_figures.clear()
+
+
+def draw_molecule_grid(mols: list[Any], show_probability: bool = True) -> str:
+
+    if not mols:
+        return ""
+
+    svg = draw_mols(
+        mols,
+        subImgSize=(400, 350),
+        max_cols=3,
+        show_probability=show_probability,
+    )
+    return render_svg_image(svg)
+
+
+def draw_single_molecule(mol: Any) -> str:
+
+    svg = draw_mols([mol], subImgSize=(520, 430), max_cols=1, show_probability=False)
+    return render_svg_image(svg)
+
+
+def scan_figure_svg(state: AppState, highlight_idx: int) -> str | None:
+
+    if state.scan is None:
+        return None
+
+    max_idx = len(getattr(state.scan, "mols_relevant", []))
+    highlight_idx = max(0, min(max_idx, highlight_idx))
+    if highlight_idx not in state.scan_figures:
+        fig = state.scan.plot_scan(highlight_idx=highlight_idx)
+        state.scan_figures[highlight_idx] = figure_to_svg(fig)
+    return state.scan_figures[highlight_idx]
+
+
+def sdf_for_state(state: AppState) -> bytes:
+
+    sdf = ""
+    for mol in state.mols_out:
+        mol2 = copy.deepcopy(mol)
+        mol2 = Chem.AddHs(mol2, addCoords=True)
+        AllChem.EmbedMolecule(mol2, randomSeed=1, useRandomCoords=True)
+        AllChem.UFFOptimizeMolecule(mol2)
+        sdf += Chem.MolToMolBlock(mol2) + "\n$$$$\n"
+    return sdf.encode("utf-8")

pkasso-0.5.0/pkasso/api/config.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+API_ROOT = Path(__file__).resolve().parent
+STATIC_DIR = API_ROOT / "static"
+TEMPLATE_DIR = API_ROOT / "templates"
+DATA_DIR = API_ROOT / "data"
+FEEDBACK_DB = DATA_DIR / "feedback.sqlite3"
+
+DEFAULT_LIGAND = "mymolecule"
+DEFAULT_SMILES = "OC(=O)C(c1ccc(O)cc1)CNCCN"
+CUTOFF_STATES = 200

pkasso-0.5.0/pkasso/api/feedback.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import sqlite3
+from datetime import datetime, timezone
+
+from .config import FEEDBACK_DB
+
+
+MAX_SMILES_LEN = 4000
+MAX_COMMENT_LEN = 8000
+
+
+def clean_feedback(smiles: str, comment: str) -> tuple[str, str]:
+    smiles = smiles.strip()
+    comment = comment.strip()
+    if not smiles:
+        raise ValueError("Please enter a SMILES code.")
+    if not comment:
+        raise ValueError("Please enter a comment.")
+    if len(smiles) > MAX_SMILES_LEN:
+        raise ValueError("SMILES code is too long.")
+    if len(comment) > MAX_COMMENT_LEN:
+        raise ValueError("Comment is too long.")
+    return smiles, comment
+
+
+def save_feedback(smiles: str, comment: str) -> None:
+    FEEDBACK_DB.parent.mkdir(parents=True, exist_ok=True)
+    created_at = datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+    with sqlite3.connect(FEEDBACK_DB) as db:
+        db.execute(
+            """
+            CREATE TABLE IF NOT EXISTS feedback (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                smiles TEXT NOT NULL,
+                comment TEXT NOT NULL,
+                created_at TEXT NOT NULL
+            )
+            """
+        )
+        db.execute(
+            "INSERT INTO feedback (smiles, comment, created_at) VALUES (?, ?, ?)",
+            (smiles, comment, created_at),
+        )

pkasso-0.5.0/pkasso/api/render.py

@@ -0,0 +1,211 @@
+from __future__ import annotations
+
+import html
+from typing import Any
+
+from .chemistry import draw_molecule_grid, draw_single_molecule, scan_figure_svg
+from .state import AppState
+
+
+def esc(value: Any) -> str:
+    return html.escape(str(value), quote=True)
+
+
+def render_empty(message: str) -> str:
+    return f"""
+    <div class="rounded-lg border border-dashed border-[color:var(--bind-border)] bg-white p-8 text-center text-sm text-[color:var(--bind-muted)]">
+      {esc(message)}
+    </div>
+    """
+
+
+def render_alert(message: str) -> str:
+    return f"""
+    <div role="alert" class="alert alert-error rounded-lg">
+      <span>{esc(message)}</span>
+    </div>
+    """
+
+
+def render_form(state: AppState) -> str:
+    tautomer_checked = "checked" if state.tautomer_search else ""
+    scan_checked = "checked" if state.scan_enabled else ""
+    return f"""
+    <form id="pkasso-form"
+          class="space-y-5"
+          hx-post="/predict"
+          hx-target="#results"
+          hx-swap="innerHTML"
+          hx-indicator="#predict-indicator">
+      <label class="form-control w-full">
+        <div class="label px-0"><span class="label-text text-xs font-semibold uppercase tracking-[0.14em] text-[color:var(--bind-muted)]">Small molecule name</span></div>
+        <input name="ligand" class="input input-bordered input-sm rounded-lg border-[color:var(--bind-border)] bg-white" value="{esc(state.ligand)}" />
+      </label>
+
+      <label class="form-control w-full">
+        <div class="label px-0"><span class="label-text text-xs font-semibold uppercase tracking-[0.14em] text-[color:var(--bind-muted)]">SMILES code</span></div>
+        <textarea name="smiles" class="textarea textarea-bordered min-h-28 rounded-lg border-[color:var(--bind-border)] bg-white font-mono text-sm">{esc(state.smiles)}</textarea>
+      </label>
+
+      <div class="grid grid-cols-1 gap-4 sm:grid-cols-[minmax(0,1fr)_minmax(0,7rem)]">
+        <div class="space-y-3">
+          <label class="flex min-w-0 cursor-pointer items-center gap-3 rounded-lg border border-[color:var(--bind-border)] bg-[color:var(--bind-soft)] px-3 py-2">
+            <input name="tautomer_search" type="checkbox" class="bind-toggle" {tautomer_checked} />
+            <span class="min-w-0 text-sm font-medium">Tautomer search</span>
+            <span class="bind-toggle-state ml-auto text-[11px] font-bold uppercase tracking-[0.12em] text-[color:var(--bind-muted)]"></span>
+          </label>
+
+          <label class="flex min-w-0 cursor-pointer items-center gap-3 rounded-lg border border-[color:var(--bind-border)] bg-[color:var(--bind-soft)] px-3 py-2">
+            <input name="scan_enabled" type="checkbox" class="bind-toggle" {scan_checked} />
+            <span class="min-w-0 text-sm font-medium">Full pH scan</span>
+            <span class="bind-toggle-state ml-auto text-[11px] font-bold uppercase tracking-[0.12em] text-[color:var(--bind-muted)]"></span>
+          </label>
+        </div>
+
+        <label class="form-control min-w-0">
+          <div class="label px-0 py-1"><span class="label-text text-xs font-semibold uppercase tracking-[0.14em] text-[color:var(--bind-muted)]">Max states</span></div>
+          <input name="nmols_export" type="number" min="1" max="20" value="{state.nmols_export}"
+                 class="input input-bordered input-sm min-w-0 rounded-lg border-[color:var(--bind-border)] bg-white" />
+        </label>
+      </div>
+
+      <div class="rounded-lg border border-[color:var(--bind-border)] bg-white p-4">
+        <div class="mb-3 flex items-center justify-between gap-3">
+          <span class="text-xs font-semibold uppercase tracking-[0.14em] text-[color:var(--bind-muted)]">pH</span>
+          <output id="phValue" for="phRange"
+                  class="min-w-14 rounded-lg bg-[color:var(--bind-soft)] px-2 py-1 text-center text-sm font-semibold text-[color:var(--bind-green)]">
+            {state.ph:.1f}
+          </output>
+        </div>
+        <input id="phRange" name="ph" type="range" min="0" max="14" step="0.1" value="{state.ph:.1f}"
+               class="bind-range w-full"
+               aria-describedby="phValue"
+               data-ph-range
+               style="--ph-position: {state.ph / 14 * 100:.3f}" />
+        <div class="mt-2 grid grid-cols-3 text-[11px] font-medium text-[color:var(--bind-muted)]">
+          <span>0</span><span class="text-center">7</span><span class="text-right">14</span>
+        </div>
+      </div>
+
+      <button type="submit" class="btn btn-primary btn-sm w-full rounded-lg">
+        <span style='color:white;'>Calculate states</span>
+        <span id="predict-indicator" class="loading loading-spinner loading-xs htmx-indicator"></span>
+      </button>
+    </form>
+    """
+
+
+def render_results(state: AppState) -> str:
+    if state.error:
+        return render_alert(state.error)
+
+    if not state.smiles_out:
+        return render_empty("Enter a SMILES string and calculate states to begin.")
+
+    smiles_lines = "\n".join(state.smiles_out)
+    try:
+        molecule_grid = draw_molecule_grid(state.mols_out, show_probability=True)
+    except Exception as exc:  # pragma: no cover - visual helper failure path
+        molecule_grid = render_alert(f"Could not render molecule images: {exc}")
+
+    scan_html = (
+        render_scan(state)
+        if state.scan is not None
+        else render_empty("Enable pH scan and calculate states to inspect microstate distributions.")
+    )
+    return f"""
+    <section class="space-y-4">
+      <div class="flex flex-wrap items-start justify-between gap-3 border-b border-[color:var(--bind-border)] pb-4">
+        <div>
+          <p class="section-kicker">Single pH prediction</p>
+          <h2 class="mt-1 text-2xl font-semibold tracking-tight">Predicted states at pH {state.ph:.1f}</h2>
+          <p class="mt-1 text-sm text-[color:var(--bind-muted)]">{len(state.mols_out)} exported microstate(s)</p>
+        </div>
+        <div class="flex flex-wrap gap-2">
+          <a class="btn btn-outline btn-sm rounded-lg" href="/download/sdf">Download SDF</a>
+          <button type="button" class="btn btn-secondary btn-sm rounded-lg" data-feedback-open>Feedback</button>
+        </div>
+      </div>
+
+      <pre class="overflow-x-auto rounded-lg border border-[color:var(--bind-border)] bg-[color:var(--bind-soft)] p-4 text-sm text-[#32716D]"><code>{esc(smiles_lines)}</code></pre>
+
+      <div class="overflow-x-auto rounded-lg border border-[color:var(--bind-border)] bg-white p-3 [&_svg]:max-w-full [&_svg]:h-auto">
+        {molecule_grid}
+      </div>
+
+      <div id="scan-panel">
+        {scan_html}
+      </div>
+    </section>
+    """
+
+
+def render_scan(state: AppState) -> str:
+    if state.scan is None:
+        return render_empty("Enable pH scan and calculate states to inspect microstate distributions.")
+
+    mols_relevant = list(getattr(state.scan, "mols_relevant", []))
+    plot = scan_plot_svg(state, 0)
+    microstates = []
+    for idx, mol in enumerate(mols_relevant):
+        try:
+            mol_svg = draw_single_molecule(mol)
+        except Exception as exc:  # pragma: no cover - visual helper failure path
+            mol_svg = render_alert(f"Could not render microstate {idx + 1}: {exc}")
+        microstates.append(
+            f"""
+            <button type="button"
+                    class="microstate rounded-lg border border-[color:var(--bind-border)] bg-white p-3 text-left transition hover:border-accent hover:bg-accent/5 focus:outline-none focus:ring-2 focus:ring-accent"
+                    data-microstate-enlarge
+                    data-microstate-title="Microstate {idx + 1}"
+                    hx-get="/scan/plot?highlight_idx={idx + 1}"
+                    hx-target="#scan-plot"
+                    hx-swap="innerHTML"
+                    hx-trigger="mouseenter, focus, click">
+              <span class="mb-2 block text-xs font-semibold uppercase tracking-[0.12em] text-[color:var(--bind-muted)]">Microstate {idx + 1}</span>
+              <span class="microstate-image block [&_svg]:h-auto [&_svg]:max-w-full">{mol_svg}</span>
+            </button>
+            """
+        )
+
+    if not microstates:
+        microstate_html = render_empty("No relevant microstates were returned for this scan.")
+    else:
+        grid_cols = "2xl:grid-cols-3" if len(microstates) > 4 else ""
+        microstate_html = f"""
+        <div class="grid grid-cols-1 gap-4 md:grid-cols-2 xl:grid-cols-2 {grid_cols}">
+          {"".join(microstates)}
+        </div>
+        """
+
+    return f"""
+    <section class="rounded-lg border border-[color:var(--bind-border)] bg-white p-4">
+      <div class="mb-3 flex flex-wrap items-center justify-between gap-3">
+        <div>
+          <p class="section-kicker">Full pH scan</p>
+          <h2 class="mt-1 text-2xl font-semibold tracking-tight">Microstate distributions</h2>
+          <p class="mt-1 text-sm text-[color:var(--bind-muted)]">Hover a microstate image to highlight it in the distribution plot; click to enlarge it.</p>
+        </div>
+        <button type="button"
+                class="btn btn-ghost btn-sm rounded-lg"
+                hx-get="/scan/plot?highlight_idx=0"
+                hx-target="#scan-plot"
+                hx-swap="innerHTML">
+          Clear highlight
+        </button>
+      </div>
+      <div class="grid grid-cols-1 gap-5 xl:grid-cols-[minmax(0,1.35fr)_minmax(28rem,0.95fr)]">
+        <div id="scan-plot" class="rounded-lg border border-[color:var(--bind-border)] bg-white p-4 [&_svg]:h-auto [&_svg]:w-full [&_svg]:max-w-full">
+          {plot}
+        </div>
+        {microstate_html}
+      </div>
+    </section>
+    """
+
+
+def scan_plot_svg(state: AppState, highlight_idx: int) -> str:
+    plot = scan_figure_svg(state, highlight_idx)
+    if plot is None:
+        return render_empty("Run a pH scan to show the distribution plot.")
+    return plot