mdprep 0.2.0__py3-none-any.whl

mdprep/protonation/propka.py

@@ -0,0 +1,174 @@
+"""PropKa execution workflow."""
+
+from __future__ import annotations
+
+import csv
+from dataclasses import dataclass
+from pathlib import Path
+
+from mdprep.config.models import ManifestConfig
+from mdprep.external.discovery import which_executable
+from mdprep.external.runner import CommandResult, run_command
+from mdprep.protonation.propka_parser import PropkaRecord, parse_propka_file
+from mdprep.structure.models import AtomRecord, PdbStructure, ResidueId, ResidueRecord
+from mdprep.structure.writer import write_pdb
+from dataclasses import replace
+
+
+class PropkaExecutionError(RuntimeError):
+    """Raised when PropKa execution fails or produces no pKa file."""
+
+
+@dataclass(frozen=True)
+class PropkaWorkflowResult:
+    executable: str
+    command: tuple[str, ...]
+    cwd: str
+    returncode: int
+    runtime_seconds: float
+    stdout_path: Path
+    stderr_path: Path
+    output_pka_path: Path
+    parsed_pkas_path: Path
+    records: list[PropkaRecord]
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "executable": self.executable,
+            "command": list(self.command),
+            "cwd": self.cwd,
+            "returncode": self.returncode,
+            "runtime_seconds": self.runtime_seconds,
+            "stdout_path": str(self.stdout_path),
+            "stderr_path": str(self.stderr_path),
+            "output_pka_path": str(self.output_pka_path),
+            "parsed_pkas_path": str(self.parsed_pkas_path),
+        }
+
+
+def run_propka_workflow(
+    structure: PdbStructure,
+    manifest: ManifestConfig,
+    *,
+    work_dir: str | Path,
+) -> PropkaWorkflowResult:
+    propka_dir = Path(work_dir)
+    propka_dir.mkdir(parents=True, exist_ok=True)
+    executable = resolve_propka_executable(manifest)
+    input_pdb = propka_dir / "propka_input.pdb"
+    propka_structure = _canonicalized_structure_for_propka(structure, input_pdb)
+    write_pdb(propka_structure, input_pdb)
+
+    command = [executable, input_pdb.name, *manifest.protonation.propka.extra_args]
+    result = run_command(command, cwd=propka_dir)
+    stdout_path = propka_dir / "propka_stdout.txt"
+    stderr_path = propka_dir / "propka_stderr.txt"
+    stdout_path.write_text(result.stdout, encoding="utf-8")
+    stderr_path.write_text(result.stderr, encoding="utf-8")
+    if manifest.protonation.propka.require_success and result.returncode != 0:
+        raise PropkaExecutionError(
+            f"PropKa failed with exit code {result.returncode}. See {stdout_path} and {stderr_path}."
+        )
+
+    pka_path = _locate_pka_file(propka_dir)
+    output_pka_path = propka_dir / "propka_output.pka"
+    output_pka_path.write_text(pka_path.read_text(encoding="utf-8"), encoding="utf-8")
+    records = parse_propka_file(output_pka_path)
+    parsed_path = propka_dir / "parsed_pkas.csv"
+    _write_parsed_csv(records, parsed_path)
+    return PropkaWorkflowResult(
+        executable=executable,
+        command=result.command,
+        cwd=result.cwd,
+        returncode=result.returncode,
+        runtime_seconds=result.runtime_seconds,
+        stdout_path=stdout_path,
+        stderr_path=stderr_path,
+        output_pka_path=output_pka_path,
+        parsed_pkas_path=parsed_path,
+        records=records,
+    )
+
+
+def resolve_propka_executable(manifest: ManifestConfig) -> str:
+    configured = manifest.protonation.propka.executable
+    if configured:
+        if Path(configured).exists():
+            return configured
+        found = which_executable(configured)
+        if found:
+            return found
+        raise PropkaExecutionError(f"Configured PropKa executable not found: {configured}")
+    for name in manifest.protonation.propka.fallback_executables:
+        found = which_executable(name)
+        if found:
+            return found
+    searched = ", ".join(manifest.protonation.propka.fallback_executables)
+    raise PropkaExecutionError(f"PropKa executable not found. Searched: {searched}")
+
+
+def _canonicalized_structure_for_propka(structure: PdbStructure, path: Path) -> PdbStructure:
+    atoms = [replace(atom, resname=_canonical_resname(atom.resname)) for atom in structure.atoms]
+    residues: list[ResidueRecord] = []
+    current_key: tuple[str, str, int, str | None] | None = None
+    current_atoms: list[AtomRecord] = []
+    for atom in atoms:
+        key = atom.residue_key
+        if current_key is not None and key != current_key:
+            residues.append(_residue_from_atoms(current_key, current_atoms, len(residues)))
+            current_atoms = []
+        current_key = key
+        current_atoms.append(atom)
+    if current_key is not None:
+        residues.append(_residue_from_atoms(current_key, current_atoms, len(residues)))
+    return PdbStructure(
+        path=path,
+        atoms=atoms,
+        residues=residues,
+        model_count=structure.model_count,
+        used_model=structure.used_model,
+        warnings=list(structure.warnings),
+    )
+
+
+def _residue_from_atoms(
+    key: tuple[str, str, int, str | None],
+    atoms: list[AtomRecord],
+    index: int,
+) -> ResidueRecord:
+    chain_id, resname, resid, icode = key
+    return ResidueRecord(
+        id=ResidueId(chain_id=chain_id, resname=resname, resid=resid, icode=icode),
+        atoms=atoms,
+        record_names={atom.record_name for atom in atoms},
+        original_index=index,
+    )
+
+
+def _canonical_resname(resname: str) -> str:
+    return {
+        "ASH": "ASP",
+        "GLH": "GLU",
+        "HID": "HIS",
+        "HIE": "HIS",
+        "HIP": "HIS",
+        "CYM": "CYS",
+        "CYX": "CYS",
+        "LYN": "LYS",
+    }.get(resname, resname)
+
+
+def _locate_pka_file(propka_dir: Path) -> Path:
+    candidates = sorted(path for path in propka_dir.glob("*.pka") if path.name != "propka_output.pka")
+    if not candidates:
+        raise PropkaExecutionError(f"PropKa did not produce a .pka file in {propka_dir}")
+    return candidates[0]
+
+
+def _write_parsed_csv(records: list[PropkaRecord], path: Path) -> None:
+    with path.open("w", encoding="utf-8", newline="") as handle:
+        writer = csv.DictWriter(handle, fieldnames=["resname", "resid", "chain_id", "pka", "raw_line"])
+        writer.writeheader()
+        for record in records:
+            writer.writerow(record.to_dict())
+

mdprep/protonation/propka_parser.py

@@ -0,0 +1,140 @@
+"""PropKa output parsing."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+import re
+
+from mdprep.structure.models import PdbStructure, ResidueRecord
+
+
+class PropkaParseError(ValueError):
+    """Raised when parsed PropKa records cannot be mapped safely."""
+
+
+_PKA_LINE = re.compile(
+    r"^\s*(?P<resname>ASP|GLU|HIS|LYS|CYS|ARG)\s+"
+    r"(?P<resid>-?\d+)\s+"
+    r"(?P<chain>\S)\s+"
+    r"(?P<pka>-?\d+(?:\.\d+)?)\b"
+)
+
+
+@dataclass(frozen=True)
+class PropkaRecord:
+    resname: str
+    resid: int
+    chain_id: str
+    pka: float
+    raw_line: str
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "resname": self.resname,
+            "resid": self.resid,
+            "chain_id": self.chain_id,
+            "pka": self.pka,
+            "raw_line": self.raw_line,
+        }
+
+
+def parse_propka_file(path: str | Path) -> list[PropkaRecord]:
+    lines = Path(path).read_text(encoding="utf-8").splitlines()
+    summary_records = _parse_summary_records(lines)
+    if summary_records:
+        return summary_records
+    records: list[PropkaRecord] = []
+    for line in lines:
+        record = parse_propka_line(line)
+        if record is not None:
+            records.append(record)
+    return records
+
+
+def parse_propka_line(line: str) -> PropkaRecord | None:
+    match = _PKA_LINE.match(line)
+    if match is None:
+        return None
+    chain_id = match.group("chain")
+    if chain_id in {"-", "_"}:
+        chain_id = ""
+    return PropkaRecord(
+        resname=match.group("resname"),
+        resid=int(match.group("resid")),
+        chain_id=chain_id,
+        pka=float(match.group("pka")),
+        raw_line=line,
+    )
+
+
+def _parse_summary_records(lines: list[str]) -> list[PropkaRecord]:
+    in_summary = False
+    records: list[PropkaRecord] = []
+    for line in lines:
+        if "SUMMARY OF THIS PREDICTION" in line:
+            in_summary = True
+            continue
+        if in_summary and line.startswith("----") and records:
+            break
+        if not in_summary:
+            continue
+        record = parse_propka_line(line)
+        if record is not None:
+            records.append(record)
+    return records
+
+
+def map_propka_records(
+    structure: PdbStructure,
+    records: list[PropkaRecord],
+) -> dict[int, PropkaRecord]:
+    mapped: dict[int, PropkaRecord] = {}
+    for record in records:
+        matches = [
+            residue
+            for residue in structure.residues
+            if residue.id.chain_id == record.chain_id
+            and residue.id.resid == record.resid
+            and _propka_family_name(residue.id.resname) == record.resname
+        ]
+        if len(matches) > 1:
+            formatted = ", ".join(_format_residue(residue) for residue in matches)
+            raise PropkaParseError(
+                f"PropKa record maps ambiguously to mdprep residues: {record.raw_line!r}. "
+                f"Matches: {formatted}. Use a manual override for residues with insertion codes."
+            )
+        if len(matches) == 0:
+            continue
+        residue = matches[0]
+        key = id(residue)
+        if key in mapped:
+            raise PropkaParseError(
+                f"Multiple PropKa records map to residue {_format_residue(residue)}."
+            )
+        mapped[key] = record
+    return mapped
+
+
+def _propka_family_name(resname: str) -> str | None:
+    return {
+        "ASP": "ASP",
+        "ASH": "ASP",
+        "GLU": "GLU",
+        "GLH": "GLU",
+        "HIS": "HIS",
+        "HID": "HIS",
+        "HIE": "HIS",
+        "HIP": "HIS",
+        "LYS": "LYS",
+        "LYN": "LYS",
+        "CYS": "CYS",
+        "CYM": "CYS",
+        "CYX": "CYS",
+        "ARG": "ARG",
+    }.get(resname)
+
+
+def _format_residue(residue: ResidueRecord) -> str:
+    chain = residue.id.chain_id if residue.id.chain_id else "<blank>"
+    return f"{chain}:{residue.id.resname}{residue.id.resid}{residue.id.icode or ''}"

mdprep/protonation/report.py

@@ -0,0 +1,187 @@
+"""Protonation-stage report writers."""
+
+from __future__ import annotations
+
+import csv
+import json
+from pathlib import Path
+from typing import Any
+
+from mdprep.protonation.apply import ProtonationRecord, ProtonationResult
+
+
+CSV_COLUMNS = [
+    "chain",
+    "resid",
+    "icode",
+    "original_resname",
+    "final_resname",
+    "source",
+    "pka",
+    "ph",
+    "reason",
+    "changed",
+]
+
+
+def write_protonation_reports(
+    result: ProtonationResult,
+    *,
+    json_path: str | Path,
+    csv_path: str | Path,
+    markdown_path: str | Path,
+) -> dict[str, Any]:
+    report = result.to_report_dict()
+    json_output = Path(json_path)
+    csv_output = Path(csv_path)
+    markdown_output = Path(markdown_path)
+    json_output.parent.mkdir(parents=True, exist_ok=True)
+    csv_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")
+    _write_csv(result.records, csv_output)
+    markdown_output.write_text(_render_markdown(report), encoding="utf-8")
+    return report
+
+
+def _write_csv(records: list[ProtonationRecord], path: Path) -> None:
+    with path.open("w", encoding="utf-8", newline="") as handle:
+        writer = csv.DictWriter(handle, fieldnames=CSV_COLUMNS)
+        writer.writeheader()
+        for record in records:
+            data = record.to_dict()
+            writer.writerow({column: data[column] for column in CSV_COLUMNS})
+
+
+def _render_markdown(report: dict[str, Any]) -> str:
+    lines = [
+        "# Protonation Report",
+        "",
+        "## Summary",
+        "",
+        f"- Method: `{report['method']}`",
+        f"- pH: {report['ph']}",
+        f"- Hydrogens removed: {report['hydrogen_atoms_removed']}",
+        "- Reused initial assignments after refinement: "
+        f"{report['reused_initial_assignments_after_refinement']}",
+        "- Refined hydrogens preserved: "
+        f"{report['preserved_refined_hydrogen_count']}",
+        f"- Residues changed: {len(report['residues_changed'])}",
+        f"- Explicit unchanged assignments: {len(report['residues_unchanged_but_explicitly_assigned'])}",
+        "",
+        "## Manual Overrides",
+        "",
+    ]
+    lines.extend(_record_lines(report["manual_overrides_applied"]))
+    lines.extend(["", "## Metal-Coordination Assignments", ""])
+    lines.extend(_record_lines(report.get("metal_coordination_assignments_applied", [])))
+    lines.extend(["", "## Disulfide Assignments", ""])
+    lines.extend(_record_lines(report["disulfide_assignments_applied"]))
+    lines.extend(["", "## PropKa Assignments", ""])
+    lines.extend(_record_lines(report.get("propka_assignments_applied", [])))
+    lines.extend(["", "## Input States Preserved", ""])
+    lines.extend(_record_lines(report.get("input_state_assignments_applied", [])))
+    lines.extend(["", "## xTB Histidine Selections", ""])
+    lines.extend(_xtb_lines(report.get("xtb_histidines", [])))
+    lines.extend(["", "## Temporary Protein Hydrogenation For xTB", ""])
+    lines.extend(
+        _temporary_protein_hydrogenation_lines(
+            report.get("xtb_temporary_protein_hydrogenation")
+        )
+    )
+    lines.extend(["", "## Temporary Water Hydrogens For xTB Clusters", ""])
+    lines.extend(_temporary_water_hydrogen_lines(report.get("temporary_water_hydrogens_for_xtb_clusters", [])))
+    lines.extend(["", "## Hydrogens Removed", ""])
+    lines.append(f"- {report['hydrogen_atoms_removed']}")
+    lines.extend(["", "## Remaining HIS Residues", ""])
+    lines.extend(_residue_lines(report["unresolved_histidines_remaining_as_his"]))
+    lines.extend(["", "## Unassigned Titratable Residues", ""])
+    lines.extend(_residue_lines(report["titratable_residues_not_explicitly_assigned"]))
+    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 _record_lines(records: list[dict[str, Any]]) -> list[str]:
+    if not records:
+        return ["- None"]
+    return [
+        f"- {_format_record(record)} via `{record['source']}`: {record['reason']}"
+        for record in records
+    ]
+
+
+def _residue_lines(residues: list[dict[str, Any]]) -> list[str]:
+    if not residues:
+        return ["- None"]
+    return [f"- {_format_residue(residue)}" for residue in residues]
+
+
+def _xtb_lines(selections: list[dict[str, Any]]) -> list[str]:
+    if not selections:
+        return ["- None"]
+    lines: list[str] = []
+    for selection in selections:
+        chain = selection["chain"] or "<blank>"
+        icode = selection["icode"] or ""
+        lines.append(
+            f"- {chain}:HIS{selection['resid']}{icode} -> {selection['selected_state']} "
+            f"(delta HID-HIE {selection['delta_kcal_mol']:.3f} kcal/mol, "
+            f"model `{selection['model']}`, mode `{selection['mode']}`)"
+        )
+    return lines
+
+
+def _temporary_water_hydrogen_lines(clusters: list[dict[str, Any]]) -> list[str]:
+    if not clusters:
+        return ["- None"]
+    lines: list[str] = []
+    for cluster in clusters:
+        lines.append(
+            f"- {cluster['histidine']}: added {cluster['temporary_water_hydrogens_added']} "
+            "temporary water hydrogens for xTB tautomer ranking only; final PDB modified: "
+            f"{cluster['final_pdb_modified']}"
+        )
+        for water in cluster["waters_modified_for_xtb_only"]:
+            chain = water["chain"] or "<blank>"
+            icode = water["icode"] or ""
+            lines.append(
+                f"  - {chain}:{water['resname']}{water['resid']}{icode}: "
+                f"{water['hydrogens_added']} added"
+            )
+    return lines
+
+
+def _temporary_protein_hydrogenation_lines(
+    hydrogenation: dict[str, Any] | None,
+) -> list[str]:
+    if hydrogenation is None:
+        return ["- Not required"]
+    return [
+        f"- Backend: `{hydrogenation['backend']}` "
+        f"({hydrogenation['backend_version'] or 'unknown version'})",
+        f"- Temporary hydrogens added: {hydrogenation['added_hydrogen_count']}",
+        "- Maximum displacement of an original atom: "
+        f"{hydrogenation['maximum_original_atom_displacement_angstrom']:.6f} A",
+        f"- Final prepared PDB modified: {hydrogenation['final_prepared_pdb_modified']}",
+        f"- Temporary hydrogenated environment: `{hydrogenation['restored_output_path']}`",
+    ]
+
+
+def _format_record(record: dict[str, Any]) -> str:
+    chain = record["chain"] or "<blank>"
+    icode = record["icode"] or ""
+    return (
+        f"{chain}:{record['original_resname']}{record['resid']}{icode} "
+        f"-> {record['final_resname']}"
+    )
+
+
+def _format_residue(residue: dict[str, Any]) -> str:
+    chain = residue["chain_id"] or "<blank>"
+    icode = residue["icode"] or ""
+    return f"{chain}:{residue['resname']}{residue['resid']}{icode}"

mdprep/protonation/states.py

@@ -0,0 +1,52 @@
+"""Residue protonation-state family validation."""
+
+from __future__ import annotations
+
+
+class ProtonationStateError(ValueError):
+    """Raised for incompatible residue protonation state assignments."""
+
+
+STATE_FAMILIES: dict[str, tuple[str, ...]] = {
+    "ASP": ("ASP", "ASH"),
+    "ASH": ("ASP", "ASH"),
+    "GLU": ("GLU", "GLH"),
+    "GLH": ("GLU", "GLH"),
+    "LYS": ("LYS", "LYN"),
+    "LYN": ("LYS", "LYN"),
+    "ARG": ("ARG",),
+    "HIS": ("HIS", "HID", "HIE", "HIP"),
+    "HID": ("HIS", "HID", "HIE", "HIP"),
+    "HIE": ("HIS", "HID", "HIE", "HIP"),
+    "HIP": ("HIS", "HID", "HIE", "HIP"),
+    "CYS": ("CYS", "CYM", "CYX"),
+    "CYM": ("CYS", "CYM", "CYX"),
+    "CYX": ("CYS", "CYM", "CYX"),
+}
+
+KNOWN_STATES = frozenset(STATE_FAMILIES)
+
+
+def allowed_states_for_resname(resname: str) -> tuple[str, ...]:
+    return STATE_FAMILIES.get(resname, ())
+
+
+def validate_state_transition(
+    *,
+    current_resname: str,
+    requested_state: str,
+    selector: str,
+) -> None:
+    if requested_state not in KNOWN_STATES:
+        raise ProtonationStateError(
+            f"Unknown protonation state for selector {selector}: requested {requested_state}."
+        )
+    allowed = allowed_states_for_resname(current_resname)
+    if not allowed or requested_state not in allowed:
+        allowed_text = ", ".join(allowed) if allowed else "none"
+        raise ProtonationStateError(
+            f"Incompatible protonation override for selector {selector}: "
+            f"current residue {current_resname}, requested {requested_state}, "
+            f"allowed states: {allowed_text}."
+        )
+