mdprep 0.2.0__py3-none-any.whl

mdprep/reports/structure_report.py

@@ -0,0 +1,92 @@
+"""Structure-stage report writers."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from mdprep.structure.normalize import StructureNormalizationResult
+
+
+def write_structure_reports(
+    result: StructureNormalizationResult,
+    *,
+    json_path: str | Path,
+    markdown_path: str | Path,
+) -> dict[str, Any]:
+    report = result.to_report_dict()
+    json_output = Path(json_path)
+    markdown_output = Path(markdown_path)
+    json_output.parent.mkdir(parents=True, exist_ok=True)
+    markdown_output.parent.mkdir(parents=True, exist_ok=True)
+    json_output.write_text(json.dumps(report, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    markdown_output.write_text(_render_markdown(report), encoding="utf-8")
+    return report
+
+
+def _render_markdown(report: dict[str, Any]) -> str:
+    lines = [
+        "# Structure Normalization Report",
+        "",
+        f"- Input: `{report['input_path']}`",
+        f"- Normalized PDB: `{report['output_normalized_pdb_path']}`",
+        f"- Atoms: {report['atom_count_before']} -> {report['atom_count_after']}",
+        f"- Residues: {report['residue_count_before']} -> {report['residue_count_after']}",
+        "",
+        "## Waters",
+        "",
+        f"- Kept: {len(report['waters_kept'])}",
+        f"- Removed: {len(report['waters_removed'])}",
+        "",
+        "## Configured Ligands",
+        "",
+    ]
+    lines.extend(_residue_lines(report["configured_ligands_kept"]))
+    lines.extend(["", "## Configured Metal Ions", ""])
+    if report["configured_metal_ions_kept"]:
+        for item in report["configured_metal_ions_kept"]:
+            lines.append(
+                f"- {item['site_id']}: {_format_residue(item)}@{item['atom_name']} "
+                f"({item['element']}{int(item['charge']):+d})"
+            )
+    else:
+        lines.append("- None")
+    lines.extend(["", "## Unknown Heterogens Removed", ""])
+    lines.extend(_residue_lines(report["unknown_heterogens_removed"]))
+    lines.extend(["", "## Histidines", ""])
+    lines.extend(_residue_lines(report["histidines"]))
+    lines.extend(["", "## Titratable Residues", ""])
+    lines.extend(_residue_lines(report["titratable_residues"]))
+    lines.extend(["", "## Possible Disulfides", ""])
+    if report["possible_disulfides"]:
+        for item in report["possible_disulfides"]:
+            a = item["a"]
+            b = item["b"]
+            lines.append(
+                f"- {_format_residue(a)} -- {_format_residue(b)}: {item['distance_angstrom']:.3f} A"
+            )
+    else:
+        lines.append("- None")
+    lines.extend(["", "## Warnings", ""])
+    if report["warnings"]:
+        lines.extend(f"- {warning}" for warning in report["warnings"])
+    else:
+        lines.append("- None")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def _residue_lines(items: list[dict[str, Any]]) -> list[str]:
+    if not items:
+        return ["- None"]
+    lines = []
+    for item in items:
+        prefix = f"{item['id']}: " if "id" in item else ""
+        lines.append(f"- {prefix}{_format_residue(item)} ({item['atom_count']} atoms)")
+    return lines
+
+
+def _format_residue(item: dict[str, Any]) -> str:
+    chain = item["chain_id"] or "<blank>"
+    return f"{chain}:{item['resname']}{item['resid']}{item.get('icode') or ''}"

mdprep/structure/__init__.py

@@ -0,0 +1,14 @@
+"""PDB structure parsing, classification, inspection, and selectors."""
+
+from __future__ import annotations
+
+from mdprep.structure.inspect import InspectionSummary, inspect_pdb_structure
+from mdprep.structure.pdb import PdbParseError, read_pdb
+
+__all__ = [
+    "InspectionSummary",
+    "PdbParseError",
+    "inspect_pdb_structure",
+    "read_pdb",
+]
+

mdprep/structure/classify.py

@@ -0,0 +1,92 @@
+"""Residue classification helpers."""
+
+from __future__ import annotations
+
+from mdprep.structure.models import ResidueRecord
+
+
+STANDARD_PROTEIN_RESIDUES = {
+    "ALA",
+    "ARG",
+    "ASN",
+    "ASP",
+    "ASH",
+    "CYS",
+    "CYM",
+    "CYX",
+    "GLN",
+    "GLU",
+    "GLH",
+    "GLY",
+    "HIS",
+    "HID",
+    "HIE",
+    "HIP",
+    "ILE",
+    "LEU",
+    "LYS",
+    "LYN",
+    "MET",
+    "PHE",
+    "PRO",
+    "SER",
+    "THR",
+    "TRP",
+    "TYR",
+    "VAL",
+}
+
+WATER_RESIDUES = {"HOH", "WAT", "H2O", "TIP3", "OPC"}
+
+TITRATABLE_RESIDUES = {
+    "ASP",
+    "ASH",
+    "GLU",
+    "GLH",
+    "HIS",
+    "HID",
+    "HIE",
+    "HIP",
+    "LYS",
+    "LYN",
+    "ARG",
+    "CYS",
+    "CYM",
+    "CYX",
+}
+
+HISTIDINE_RESIDUES = {"HIS", "HID", "HIE", "HIP"}
+
+
+def is_standard_protein_residue(residue: ResidueRecord) -> bool:
+    # Residue names alone are insufficient: free proline substrates and other
+    # amino-acid-like ligands are valid HETATM residues.  Polymer identity is
+    # carried by ATOM records (and preserved TER boundaries).
+    return (
+        residue.id.resname in STANDARD_PROTEIN_RESIDUES
+        and "ATOM" in residue.record_names
+    )
+
+
+def is_water_residue(residue: ResidueRecord) -> bool:
+    return residue.id.resname in WATER_RESIDUES
+
+
+def is_histidine(residue: ResidueRecord) -> bool:
+    return is_standard_protein_residue(residue) and residue.id.resname in HISTIDINE_RESIDUES
+
+
+def is_titratable_residue(residue: ResidueRecord) -> bool:
+    return is_standard_protein_residue(residue) and residue.id.resname in TITRATABLE_RESIDUES
+
+
+def is_nonstandard_nonwater_residue(residue: ResidueRecord) -> bool:
+    return not is_water_residue(residue) and not is_standard_protein_residue(residue)
+
+
+def is_likely_ligand_or_cofactor(residue: ResidueRecord) -> bool:
+    return is_nonstandard_nonwater_residue(residue)
+
+
+def likely_ligands_or_cofactors(residues: list[ResidueRecord]) -> list[ResidueRecord]:
+    return [residue for residue in residues if is_likely_ligand_or_cofactor(residue)]

mdprep/structure/disulfides.py

@@ -0,0 +1,51 @@
+"""Disulfide candidate detection."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from itertools import combinations
+from math import dist
+
+from mdprep.structure.models import AtomRecord, ResidueId, ResidueRecord
+
+
+@dataclass(frozen=True)
+class DisulfideCandidate:
+    a: ResidueId
+    b: ResidueId
+    distance_angstrom: float
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "a": self.a.to_dict(),
+            "b": self.b.to_dict(),
+            "distance_angstrom": self.distance_angstrom,
+        }
+
+
+def detect_possible_disulfides(
+    residues: list[ResidueRecord],
+    *,
+    cutoff_angstrom: float = 2.2,
+) -> list[DisulfideCandidate]:
+    cys_sg_atoms: list[tuple[ResidueRecord, AtomRecord]] = []
+    for residue in residues:
+        if residue.id.resname not in {"CYS", "CYX"}:
+            continue
+        sg = next((atom for atom in residue.atoms if atom.name == "SG"), None)
+        if sg is not None:
+            cys_sg_atoms.append((residue, sg))
+
+    candidates: list[DisulfideCandidate] = []
+    for (residue_a, atom_a), (residue_b, atom_b) in combinations(cys_sg_atoms, 2):
+        distance_angstrom = dist((atom_a.x, atom_a.y, atom_a.z), (atom_b.x, atom_b.y, atom_b.z))
+        if distance_angstrom <= cutoff_angstrom:
+            candidates.append(
+                DisulfideCandidate(
+                    a=residue_a.id,
+                    b=residue_b.id,
+                    distance_angstrom=distance_angstrom,
+                )
+            )
+    return candidates
+

mdprep/structure/inspect.py

@@ -0,0 +1,105 @@
+"""Structure inspection summaries."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from mdprep.structure.classify import (
+    is_histidine,
+    is_likely_ligand_or_cofactor,
+    is_nonstandard_nonwater_residue,
+    is_standard_protein_residue,
+    is_titratable_residue,
+    is_water_residue,
+)
+from mdprep.structure.disulfides import DisulfideCandidate, detect_possible_disulfides
+from mdprep.structure.models import PdbStructure, ResidueRecord
+from mdprep.structure.pdb import AltlocPolicy, read_pdb
+
+
+@dataclass(frozen=True)
+class InspectionSummary:
+    structure: PdbStructure
+    protein_residues: list[ResidueRecord]
+    water_residues: list[ResidueRecord]
+    heterogen_residues: list[ResidueRecord]
+    likely_ligands: list[ResidueRecord]
+    histidines: list[ResidueRecord]
+    titratable_residues: list[ResidueRecord]
+    possible_disulfides: list[DisulfideCandidate]
+
+    @property
+    def chain_ids(self) -> list[str]:
+        seen: list[str] = []
+        for residue in self.structure.residues:
+            if residue.id.chain_id not in seen:
+                seen.append(residue.id.chain_id)
+        return seen
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "path": str(self.structure.path),
+            "total_atoms": len(self.structure.atoms),
+            "total_residues": len(self.structure.residues),
+            "model_count": self.structure.model_count,
+            "used_model": self.structure.used_model,
+            "warnings": list(self.structure.warnings),
+            "chains": [{"chain_id": chain_id, "display": chain_id or "<blank>"} for chain_id in self.chain_ids],
+            "counts": {
+                "protein_residues": len(self.protein_residues),
+                "water_residues": len(self.water_residues),
+                "heterogen_residues": len(self.heterogen_residues),
+                "likely_ligands": len(self.likely_ligands),
+                "histidines": len(self.histidines),
+                "titratable_residues": len(self.titratable_residues),
+                "possible_disulfides": len(self.possible_disulfides),
+            },
+            "likely_ligands": [_residue_to_dict(residue) for residue in self.likely_ligands],
+            "histidines": [_residue_to_dict(residue) for residue in self.histidines],
+            "titratable_residues": [_residue_to_dict(residue) for residue in self.titratable_residues],
+            "possible_disulfides": [candidate.to_dict() for candidate in self.possible_disulfides],
+        }
+
+
+def inspect_pdb_structure(
+    path: str | Path,
+    *,
+    altloc_policy: AltlocPolicy = "highest_occupancy",
+    disulfide_cutoff_angstrom: float = 2.2,
+) -> InspectionSummary:
+    structure = read_pdb(path, altloc_policy=altloc_policy)
+    residues = structure.residues
+    protein_residues = [residue for residue in residues if is_standard_protein_residue(residue)]
+    water_residues = [residue for residue in residues if is_water_residue(residue)]
+    heterogen_residues = [
+        residue
+        for residue in residues
+        if is_nonstandard_nonwater_residue(residue)
+    ]
+    likely_ligands = [residue for residue in residues if is_likely_ligand_or_cofactor(residue)]
+    histidines = [residue for residue in residues if is_histidine(residue)]
+    titratable_residues = [residue for residue in residues if is_titratable_residue(residue)]
+    possible_disulfides = detect_possible_disulfides(
+        residues,
+        cutoff_angstrom=disulfide_cutoff_angstrom,
+    )
+    return InspectionSummary(
+        structure=structure,
+        protein_residues=protein_residues,
+        water_residues=water_residues,
+        heterogen_residues=heterogen_residues,
+        likely_ligands=likely_ligands,
+        histidines=histidines,
+        titratable_residues=titratable_residues,
+        possible_disulfides=possible_disulfides,
+    )
+
+
+def _residue_to_dict(residue: ResidueRecord) -> dict[str, object]:
+    return {
+        **residue.id.to_dict(),
+        "atom_count": len(residue.atoms),
+        "record_names": sorted(residue.record_names),
+        "original_index": residue.original_index,
+    }

mdprep/structure/models.py

@@ -0,0 +1,86 @@
+"""Internal structure data models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal
+
+
+RecordName = Literal["ATOM", "HETATM"]
+
+
+@dataclass(frozen=True)
+class AtomRecord:
+    serial: int | None
+    name: str
+    altloc: str | None
+    resname: str
+    chain_id: str
+    resid: int
+    icode: str | None
+    x: float
+    y: float
+    z: float
+    occupancy: float | None
+    bfactor: float | None
+    element: str | None
+    record_name: RecordName
+    original_line: str
+
+    @property
+    def residue_key(self) -> tuple[str, str, int, str | None]:
+        return (self.chain_id, self.resname, self.resid, self.icode)
+
+    @property
+    def atom_identity(self) -> tuple[str, str, int, str | None, str]:
+        return (self.chain_id, self.resname, self.resid, self.icode, self.name)
+
+
+@dataclass(frozen=True)
+class ResidueId:
+    chain_id: str
+    resname: str
+    resid: int
+    icode: str | None = None
+
+    def to_dict(self) -> dict[str, str | int | None]:
+        return {
+            "chain_id": self.chain_id,
+            "resname": self.resname,
+            "resid": self.resid,
+            "icode": self.icode,
+        }
+
+    def display(self) -> str:
+        chain = self.chain_id if self.chain_id else "<blank>"
+        icode = self.icode or ""
+        return f"{chain}:{self.resname}{self.resid}{icode}"
+
+
+@dataclass
+class ResidueRecord:
+    id: ResidueId
+    atoms: list[AtomRecord]
+    record_names: set[str]
+    original_index: int
+
+    def atom_names(self) -> list[str]:
+        return [atom.name for atom in self.atoms]
+
+
+@dataclass
+class PdbStructure:
+    path: Path
+    atoms: list[AtomRecord]
+    residues: list[ResidueRecord]
+    model_count: int
+    used_model: int = 1
+    warnings: list[str] = field(default_factory=list)
+    # Connectivity is stored by PDB atom serial so it survives residue
+    # renaming and filtering.  Each pair is canonicalized as (min, max).
+    conect_bonds: set[tuple[int, int]] = field(default_factory=set)
+    # TER is a polymer/chain boundary, not decoration.  Store the serial of
+    # the last atom before each explicit input TER so writers cannot
+    # accidentally reconnect an unresolved chain break or a heterogen.
+    ter_after_serials: set[int] = field(default_factory=set)