pocketscribe 0.1.0__py3-none-any.whl

pocketscribe/__init__.py

@@ -0,0 +1,23 @@
+"""Pocketscribe: confidence-aware binding-pocket triage for predicted protein structures.
+
+Takes a predicted structure from AlphaFold2, OpenFold, ColabFold, ESMFold or Boltz and
+produces one self-contained report covering structure QC, pocket detection,
+confidence-caveated druggability, optional cross-model consensus, and ready-to-run
+GROMACS input files.
+
+Pocketscribe is an integration contribution. It does not implement a new
+pocket-detection algorithm, druggability model or force field -- fpocket, GROMACS,
+CHARMM36m and the prediction models do that work, and each is cited in
+:mod:`pocketscribe.citations`. The one piece of original method here is the cross-model
+consensus module in :mod:`pocketscribe.consensus`.
+
+Research use only. See the disclaimer in every generated report.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+__author__ = "John Adeyemo Adedeji"
+__license__ = "MIT"
+
+__all__ = ["__version__", "__author__", "__license__"]

pocketscribe/citations.py

@@ -0,0 +1,251 @@
+"""Citations for every external tool and method Pocketscribe wraps.
+
+Pocketscribe invents no science. fpocket does the cavity geometry and druggability
+scoring, GROMACS and CHARMM36m do the simulation physics, and the structure-prediction
+models do the folding. A report that gets cited in someone's methods section must point
+at those primary sources, so they live here in one place, shared by the README, the
+rendered report and ``pocketscribe sources``.
+
+Keeping this list correct is a research-integrity obligation, not a formatting detail.
+If you add an adapter, add its citation here in the same commit.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Citation:
+    """One primary reference."""
+
+    key: str
+    name: str
+    reference: str
+    url: str = ""
+    role: str = ""
+
+
+CITATIONS: dict[str, Citation] = {
+    "fpocket": Citation(
+        key="fpocket",
+        name="fpocket",
+        reference=(
+            "Le Guilloux, V., Schmidtke, P. & Tuffery, P. Fpocket: an open source "
+            "platform for ligand pocket detection. BMC Bioinformatics 10, 168 (2009). "
+            "doi:10.1186/1471-2105-10-168"
+        ),
+        url="https://github.com/Discngine/fpocket",
+        role="Cavity detection and alpha-sphere descriptors.",
+    ),
+    "fpocket_druggability": Citation(
+        key="fpocket_druggability",
+        name="fpocket druggability score",
+        reference=(
+            "Schmidtke, P. & Barril, X. Understanding and predicting druggability. A "
+            "high-throughput method for detection of drug binding sites. Journal of "
+            "Medicinal Chemistry 53, 5858-5867 (2010). doi:10.1021/jm100574m"
+        ),
+        url="https://doi.org/10.1021/jm100574m",
+        role="The trained druggability model reported in the pocket table.",
+    ),
+    "gromacs": Citation(
+        key="gromacs",
+        name="GROMACS",
+        reference=(
+            "Abraham, M. J., Murtola, T., Schulz, R., Pall, S., Smith, J. C., Hess, B. "
+            "& Lindahl, E. GROMACS: High performance molecular simulations through "
+            "multi-level parallelism from laptops to supercomputers. SoftwareX 1-2, "
+            "19-25 (2015). doi:10.1016/j.softx.2015.06.001"
+        ),
+        url="https://www.gromacs.org/",
+        role="The MD engine the generated input files target.",
+    ),
+    "charmm36m": Citation(
+        key="charmm36m",
+        name="CHARMM36m force field",
+        reference=(
+            "Huang, J., Rauscher, S., Nawrocki, G., Ran, T., Feig, M., de Groot, B. L., "
+            "Grubmuller, H. & MacKerell, A. D. Jr. CHARMM36m: an improved force field "
+            "for folded and intrinsically disordered proteins. Nature Methods 14, "
+            "71-73 (2017). doi:10.1038/nmeth.4067"
+        ),
+        url="https://doi.org/10.1038/nmeth.4067",
+        role="Default force field in the generated MD setup.",
+    ),
+    "jumper2021": Citation(
+        key="jumper2021",
+        name="AlphaFold2",
+        reference=(
+            "Jumper, J., Evans, R., Pritzel, A. et al. Highly accurate protein structure "
+            "prediction with AlphaFold. Nature 596, 583-589 (2021). "
+            "doi:10.1038/s41586-021-03819-2"
+        ),
+        url="https://github.com/google-deepmind/alphafold",
+        role="Tier 1 structure source.",
+    ),
+    "varadi2024": Citation(
+        key="varadi2024",
+        name="AlphaFold Protein Structure Database",
+        reference=(
+            "Varadi, M., Bertoni, D., Magana, P. et al. AlphaFold Protein Structure "
+            "Database in 2024: providing structure coverage for over 214 million protein "
+            "sequences. Nucleic Acids Research 52, D368-D375 (2024). "
+            "doi:10.1093/nar/gkad1011"
+        ),
+        url="https://alphafold.ebi.ac.uk/",
+        role="Source of AlphaFold DB models, if that is where the input came from.",
+    ),
+    "ahdritz2024": Citation(
+        key="ahdritz2024",
+        name="OpenFold",
+        reference=(
+            "Ahdritz, G., Bouatta, N., Floristean, C. et al. OpenFold: retraining "
+            "AlphaFold2 yields new insights into its learning mechanisms and capacity "
+            "for generalization. Nature Methods 21, 1514-1524 (2024). "
+            "doi:10.1038/s41592-024-02272-z"
+        ),
+        url="https://github.com/aqlaboratory/openfold",
+        role="Tier 1 structure source.",
+    ),
+    "mirdita2022": Citation(
+        key="mirdita2022",
+        name="ColabFold",
+        reference=(
+            "Mirdita, M., Schutze, K., Moriwaki, Y., Heo, L., Ovchinnikov, S. & "
+            "Steinegger, M. ColabFold: making protein folding accessible to all. "
+            "Nature Methods 19, 679-682 (2022). doi:10.1038/s41592-022-01488-1"
+        ),
+        url="https://github.com/sokrypton/ColabFold",
+        role="Tier 1 structure source.",
+    ),
+    "lin2023": Citation(
+        key="lin2023",
+        name="ESMFold / ESM-2",
+        reference=(
+            "Lin, Z., Akin, H., Rao, R. et al. Evolutionary-scale prediction of "
+            "atomic-level protein structure with a language model. Science 379, "
+            "1123-1130 (2023). doi:10.1126/science.ade2574"
+        ),
+        url="https://github.com/facebookresearch/esm",
+        role="Tier 1 structure source; the single-sequence family in consensus.",
+    ),
+    "wohlwend2024": Citation(
+        key="wohlwend2024",
+        name="Boltz-1 / Boltz-2",
+        reference=(
+            "Wohlwend, J., Corso, G., Passaro, S. et al. Boltz-1: democratizing "
+            "biomolecular interaction modeling. bioRxiv (2024). "
+            "doi:10.1101/2024.11.19.624167"
+        ),
+        url="https://github.com/jwohlwend/boltz",
+        role="Tier 2 reference structure source.",
+    ),
+    "protenix2025": Citation(
+        key="protenix2025",
+        name="Protenix",
+        reference=(
+            "ByteDance AML AI4Science Team. Protenix: advancing structure prediction "
+            "through a comprehensive AlphaFold3 reproduction. bioRxiv (2025). "
+            "doi:10.1101/2025.01.08.631967"
+        ),
+        url="https://github.com/bytedance/Protenix",
+        role="Tier 2 stub; adapter not yet implemented.",
+    ),
+    "abramson2024": Citation(
+        key="abramson2024",
+        name="AlphaFold3",
+        reference=(
+            "Abramson, J., Adler, J., Dunger, J. et al. Accurate structure prediction of "
+            "biomolecular interactions with AlphaFold 3. Nature 630, 493-500 (2024). "
+            "doi:10.1038/s41586-024-07487-w"
+        ),
+        url="https://github.com/google-deepmind/alphafold3",
+        role="Tier 2 stub; adapter not yet implemented.",
+    ),
+    "baek2021": Citation(
+        key="baek2021",
+        name="RoseTTAFold",
+        reference=(
+            "Baek, M., DiMaio, F., Anishchenko, I. et al. Accurate prediction of protein "
+            "structures and interactions using a three-track neural network. Science "
+            "373, 871-876 (2021). doi:10.1126/science.abj8754"
+        ),
+        url="https://github.com/RosettaCommons/RoseTTAFold",
+        role="Tier 2 stub; deprioritised relative to newer models.",
+    ),
+    "biopython": Citation(
+        key="biopython",
+        name="Biopython",
+        reference=(
+            "Cock, P. J. A., Antao, T., Chang, J. T. et al. Biopython: freely available "
+            "Python tools for computational molecular biology and bioinformatics. "
+            "Bioinformatics 25, 1422-1423 (2009). doi:10.1093/bioinformatics/btp163"
+        ),
+        url="https://biopython.org/",
+        role="Structure parsing and pairwise sequence alignment.",
+    ),
+    "kabsch1976": Citation(
+        key="kabsch1976",
+        name="Kabsch superposition",
+        reference=(
+            "Kabsch, W. A solution for the best rotation to relate two sets of vectors. "
+            "Acta Crystallographica A 32, 922-923 (1976). doi:10.1107/S0567739476001873"
+        ),
+        url="https://doi.org/10.1107/S0567739476001873",
+        role="Structural superposition in the consensus module.",
+    ),
+    "hendlich1997": Citation(
+        key="hendlich1997",
+        name="LIGSITE",
+        reference=(
+            "Hendlich, M., Rippmann, F. & Barnickel, G. LIGSITE: automatic and efficient "
+            "detection of potential small molecule-binding sites in proteins. Journal of "
+            "Molecular Graphics and Modelling 15, 359-363 (1997). "
+            "doi:10.1016/S1093-3263(98)00002-3"
+        ),
+        url="https://doi.org/10.1016/S1093-3263(98)00002-3",
+        role=(
+            "The grid buriedness scan the built-in offline fallback backend follows. "
+            "Only relevant when fpocket is unavailable."
+        ),
+    ),
+}
+
+
+def core_citations() -> list[Citation]:
+    """The references every run depends on, in reading order."""
+    return [
+        CITATIONS["fpocket"],
+        CITATIONS["fpocket_druggability"],
+        CITATIONS["gromacs"],
+        CITATIONS["charmm36m"],
+        CITATIONS["biopython"],
+    ]
+
+
+def citations_for_report(
+    source_keys: list[str], used_fpocket: bool, used_consensus: bool
+) -> list[Citation]:
+    """Assemble the 'Built on' list for one report, without duplicates."""
+    selected: list[Citation] = []
+
+    def add(citation: Citation | None) -> None:
+        if citation is not None and citation not in selected:
+            selected.append(citation)
+
+    if used_fpocket:
+        add(CITATIONS["fpocket"])
+        add(CITATIONS["fpocket_druggability"])
+    else:
+        add(CITATIONS["hendlich1997"])
+
+    for key in source_keys:
+        add(CITATIONS.get(key))
+
+    add(CITATIONS["gromacs"])
+    add(CITATIONS["charmm36m"])
+    add(CITATIONS["biopython"])
+    if used_consensus:
+        add(CITATIONS["kabsch1976"])
+    return selected

pocketscribe/cli.py

@@ -0,0 +1,315 @@
+"""Command-line interface.
+
+Four commands:
+
+``run``
+    Analyse one structure, or several structures of the same protein for cross-model
+    consensus.
+``demo``
+    Run end to end on bundled example structures, with no network access and no
+    external downloads.
+``sources``
+    List every structure-prediction source and its support tier.
+``version``
+    Print the version.
+
+Errors are printed as plain, specific messages rather than tracebacks: the target user
+is a bench scientist, and a Python traceback is not an error message.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import typer
+
+from . import __version__
+from .citations import CITATIONS
+from .config import RunConfig
+from .errors import PocketscribeError
+from .models import SupportTier
+from .pipeline import StructureInput, run_pipeline
+from .report.render import render_report
+from .sources import all_sources
+
+app = typer.Typer(
+    name="pocketscribe",
+    help=(
+        "Confidence-aware binding-pocket triage and MD setup for predicted protein "
+        "structures. Research use only."
+    ),
+    add_completion=False,
+    no_args_is_help=True,
+)
+
+_TIER_TEXT = {
+    SupportTier.TIER_1: "Tier 1 (full support)",
+    SupportTier.TIER_2_REFERENCE: "Tier 2 (reference adapter)",
+    SupportTier.TIER_2_STUB: "Tier 2 (stub - not implemented)",
+}
+
+
+def _echo(message: str) -> None:
+    typer.echo(message)
+
+
+def _fail(error: Exception) -> None:
+    """Print a clean error and exit non-zero."""
+    typer.secho(f"\nError: {error}", fg=typer.colors.RED, err=True)
+    raise typer.Exit(code=1)
+
+
+@app.command()
+def run(
+    pdb: list[str] = typer.Option(
+        ...,
+        "--pdb",
+        help=(
+            "Structure file. Optionally tag it with its source as PATH:SOURCE, e.g. "
+            "model.pdb:esmfold. Pass --pdb more than once, with 2+ structures of the "
+            "SAME protein, to enable cross-model consensus."
+        ),
+    ),
+    source: str = typer.Option(
+        "auto",
+        "--source",
+        help=(
+            "Structure source when it is not tagged per file: alphafold2, openfold, "
+            "colabfold, esmfold, boltz, or auto to detect it from the file."
+        ),
+    ),
+    output: Path = typer.Option(Path("report.html"), "--output", "-o", help="Report path."),
+    top_pockets: int = typer.Option(3, "--top-pockets", min=1, max=50),
+    md_setup: bool = typer.Option(
+        False, "--md-setup", help="Generate GROMACS input files for the top pocket."
+    ),
+    md_dir: Path = typer.Option(
+        Path("md_setup"), "--md-dir", help="Directory for the generated MD files."
+    ),
+    pocket_backend: str = typer.Option(
+        "fpocket",
+        "--pocket-backend",
+        help=(
+            "'fpocket' (default, recommended) or 'builtin' (offline geometric fallback "
+            "whose scores are a heuristic, not fpocket druggability scores)."
+        ),
+    ),
+    min_identity: float = typer.Option(
+        0.95,
+        "--min-identity",
+        min=0.0,
+        max=1.0,
+        help="Sequence identity required between structures in consensus mode.",
+    ),
+    no_narrative: bool = typer.Option(
+        False, "--no-narrative", help="Skip the optional AI narrative section entirely."
+    ),
+    config_file: Path | None = typer.Option(
+        None, "--config", help="YAML configuration file; CLI options override it."
+    ),
+) -> None:
+    """Analyse a predicted structure and write an HTML report."""
+    try:
+        config = RunConfig.from_yaml(config_file) if config_file else RunConfig()
+
+        config.pockets.backend = pocket_backend
+        config.pockets.top_pockets = top_pockets
+        config.consensus.min_sequence_identity = min_identity
+        config.md.enabled = md_setup
+        if no_narrative:
+            config.narrative.enabled = False
+
+        inputs: list[StructureInput] = []
+        for raw in pdb:
+            item = StructureInput.parse(raw)
+            if item.source_id == "auto" and source != "auto":
+                item.source_id = source
+            item.label = item.path.name
+            inputs.append(item)
+
+        if len(inputs) > 1:
+            _echo(
+                f"Cross-model consensus mode: {len(inputs)} structures. They must be "
+                "independent predictions of the same protein."
+            )
+
+        result, parsed = run_pipeline(
+            inputs=inputs,
+            config=config,
+            md_output_dir=md_dir,
+            allow_backend_fallback=False,
+            progress=_echo,
+        )
+
+        _echo(f"Rendering report to {output}")
+        path = render_report(result, parsed, output, max_images=min(top_pockets, 3))
+
+        _echo("")
+        _summarise(result)
+        typer.secho(f"Report written to {path}", fg=typer.colors.GREEN)
+
+    except PocketscribeError as exc:
+        _fail(exc)
+    except KeyboardInterrupt:
+        typer.secho("\nInterrupted.", fg=typer.colors.YELLOW, err=True)
+        raise typer.Exit(code=130) from None
+
+
+@app.command()
+def demo(
+    output: Path = typer.Option(Path("demo_report.html"), "--output", "-o"),
+    consensus: bool = typer.Option(
+        False,
+        "--consensus",
+        help="Run the cross-model consensus path on two bundled example models.",
+    ),
+    md_setup: bool = typer.Option(False, "--md-setup", help="Also generate MD inputs."),
+) -> None:
+    """Run end to end on bundled example structures. No network access needed."""
+    from .data import demo_consensus_structures, demo_structure
+
+    try:
+        if consensus:
+            paths = demo_consensus_structures()
+            inputs = [
+                StructureInput(path=path, source_id=source_id, label=path.name)
+                for path, source_id in paths
+            ]
+            _echo(
+                "Demo (consensus): "
+                + ", ".join(f"{path.name} [{source_id}]" for path, source_id in paths)
+            )
+        else:
+            path, source_id = demo_structure()
+            inputs = [StructureInput(path=path, source_id=source_id, label=path.name)]
+            _echo(f"Demo: {path.name} [{source_id}]")
+
+        _echo(
+            "These are synthetic structures with known geometry, bundled so the demo "
+            "runs offline. They are not real proteins."
+        )
+
+        config = RunConfig()
+        config.md.enabled = md_setup
+        # The demo is allowed to fall back to the built-in backend so it runs on a
+        # machine without fpocket. A real analysis run never does this silently.
+        result, parsed = run_pipeline(
+            inputs=inputs,
+            config=config,
+            allow_backend_fallback=True,
+            progress=_echo,
+        )
+        path = render_report(result, parsed, output, max_images=3)
+
+        _echo("")
+        _summarise(result)
+        typer.secho(f"Demo report written to {path}", fg=typer.colors.GREEN)
+
+    except PocketscribeError as exc:
+        _fail(exc)
+
+
+@app.command()
+def sources() -> None:
+    """List supported structure-prediction sources and their support tiers."""
+    _echo("")
+    _echo("Pocketscribe structure sources")
+    _echo("=" * 78)
+
+    for adapter in all_sources():
+        info = adapter.info
+        _echo("")
+        _echo(f"  {info.id}")
+        _echo(f"    name          {info.display_name}")
+        _echo(f"    support       {_TIER_TEXT[info.tier]}")
+        _echo(f"    family        {info.family.value}")
+        _echo(f"    confidence    {info.metric.value}")
+        _echo(f"    uses MSA      {'yes' if info.uses_msa else 'no (single sequence)'}")
+        citation = CITATIONS.get(info.citation_key)
+        if citation:
+            _echo(f"    cite          {citation.reference}")
+        if info.notes:
+            for line in _wrap(info.notes, 70):
+                _echo(f"    {line}")
+
+    _echo("")
+    _echo("-" * 78)
+    _echo(
+        "Tier 2 stubs fail with a specific 'not yet implemented' message rather than\n"
+        "attempting a parse that would be wrong. Adding one is the most useful\n"
+        "contribution you can make: see CONTRIBUTING.md."
+    )
+    _echo("")
+
+
+@app.command()
+def version() -> None:
+    """Print the Pocketscribe version."""
+    _echo(f"pocketscribe {__version__}")
+
+
+def _summarise(result) -> None:
+    """Terminal summary of what the report contains."""
+    pockets = result.primary_pockets
+    _echo("Summary")
+    _echo("-" * 60)
+    _echo(f"  structure        {result.primary_structure.label}")
+    _echo(f"  source           {result.primary_structure.source.display_name}")
+    _echo(
+        f"  mean pLDDT       {result.primary_structure.confidence.mean:.1f} "
+        f"({result.primary_structure.confidence.fraction_below_70:.0%} below 70)"
+    )
+    _echo(f"  pockets          {len(pockets.pockets)} (backend: {pockets.backend})")
+
+    for pocket in pockets.top(result.top_pockets_requested):
+        score = (
+            f"{pocket.druggability_score:.3f}"
+            if pocket.druggability_score is not None
+            else "n/a"
+        )
+        mean_confidence = (
+            f"{pocket.confidence.mean_confidence:.0f}"
+            if pocket.confidence.mean_confidence is not None
+            else "n/a"
+        )
+        volume = f"{pocket.volume:.0f} A^3" if pocket.volume is not None else "n/a"
+        _echo(f"    #{pocket.rank}  score {score}  volume {volume}")
+        _echo(
+            f"         mean pLDDT {mean_confidence}  "
+            f"caveat: {pocket.confidence.level.value}"
+        )
+
+    if result.consensus is not None:
+        _echo(
+            f"  consensus        {len(result.consensus.groups)} group(s); "
+            f"{result.consensus.n_cross_family_pockets} cross-family, "
+            f"{result.consensus.n_same_family_only_pockets} same-family only, "
+            f"{result.consensus.n_single_model_pockets} single-model"
+        )
+    if result.md_setup is not None:
+        _echo(f"  MD setup         {len(result.md_setup.files)} files in {result.md_setup.output_dir}")
+    _echo(
+        "  narrative        "
+        + ("included" if result.narrative.enabled else "skipped (optional)")
+    )
+    _echo("")
+
+
+def _wrap(text: str, width: int) -> list[str]:
+    import textwrap
+
+    return textwrap.wrap(text, width=width)
+
+
+def main() -> None:
+    """Entry point used by the console script."""
+    try:
+        app()
+    except PocketscribeError as exc:  # safety net; commands handle their own errors
+        typer.secho(f"Error: {exc}", fg=typer.colors.RED, err=True)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()