dnakit 0.1.0.dev0__py3-none-any.whl

dnakit/structure3d/pdb.py

@@ -0,0 +1,253 @@
+"""Bounded parser for canonical DNA atoms in legacy PDB coordinate files."""
+
+from __future__ import annotations
+
+import hashlib
+import math
+from collections import defaultdict
+from pathlib import Path
+
+from dnakit.exceptions import ConfigurationError, InputFormatError
+
+from .results import Atom3D, DNA3DStructure, Residue3D
+
+_DNA_RESIDUES = {
+    "DA": "A",
+    "DC": "C",
+    "DG": "G",
+    "DT": "T",
+    "A": "A",
+    "C": "C",
+    "G": "G",
+    "T": "T",
+    "ADE": "A",
+    "CYT": "C",
+    "GUA": "G",
+    "THY": "T",
+}
+_MAX_PDB_BYTES = 100_000_000
+_MAX_ATOMS = 1_000_000
+_MAX_MODELS = 10_000
+
+
+def _integer(text: str, field: str, line_number: int) -> int:
+    try:
+        return int(text.strip())
+    except ValueError as exc:
+        raise InputFormatError(
+            f"PDB {field} is not an integer.",
+            code="INVALID_PDB_FIELD",
+            context={"field": field, "line_number": line_number, "value": text},
+        ) from exc
+
+
+def _number(text: str, field: str, line_number: int, *, default: float | None = None) -> float:
+    if not text.strip() and default is not None:
+        return default
+    try:
+        value = float(text.strip())
+    except ValueError as exc:
+        raise InputFormatError(
+            f"PDB {field} is not numeric.",
+            code="INVALID_PDB_FIELD",
+            context={"field": field, "line_number": line_number, "value": text},
+        ) from exc
+    if not math.isfinite(value):
+        raise InputFormatError(
+            f"PDB {field} must be finite.",
+            code="INVALID_PDB_FIELD",
+            context={"field": field, "line_number": line_number},
+        )
+    return value
+
+
+def _element(atom_name: str, explicit: str) -> str:
+    if explicit.strip():
+        return explicit.strip().upper()
+    letters = "".join(character for character in atom_name if character.isalpha())
+    return letters[:1].upper() or "X"
+
+
+def _structure(
+    *,
+    path: Path,
+    digest: str,
+    pdb_id: str | None,
+    title: str | None,
+    model_index: int,
+    atoms: tuple[Atom3D, ...],
+) -> DNA3DStructure:
+    residue_atoms: dict[tuple[str, int, str, str], list[Atom3D]] = {}
+    residue_order: list[tuple[str, int, str, str]] = []
+    for atom in atoms:
+        key = (atom.chain_id, atom.residue_number, atom.insertion_code, atom.residue_name)
+        if key not in residue_atoms:
+            residue_atoms[key] = []
+            residue_order.append(key)
+        residue_atoms[key].append(atom)
+    residues = tuple(
+        Residue3D(
+            name=residue_name,
+            base=_DNA_RESIDUES[residue_name],
+            chain_id=chain_id,
+            number=number,
+            insertion_code=insertion_code,
+            atoms=tuple(residue_atoms[(chain_id, number, insertion_code, residue_name)]),
+        )
+        for chain_id, number, insertion_code, residue_name in residue_order
+    )
+    chain_ids = tuple(dict.fromkeys(residue.chain_id for residue in residues))
+    sequence_by_chain = tuple(
+        "".join(residue.base for residue in residues if residue.chain_id == chain_id)
+        for chain_id in chain_ids
+    )
+    return DNA3DStructure(
+        pdb_id=pdb_id,
+        title=title,
+        model_index=model_index,
+        source_path=str(path),
+        source_sha256=digest,
+        atoms=atoms,
+        residues=residues,
+        chain_ids=chain_ids,
+        sequence_by_chain=sequence_by_chain,
+        parser="dnakit-bounded-legacy-pdb-parser-v1",
+    )
+
+
+def load_pdb_ensemble(path: str | Path) -> tuple[DNA3DStructure, ...]:
+    """Load all PDB MODEL records, retaining canonical DNA ATOM records only."""
+
+    if not isinstance(path, (str, Path)):
+        raise ConfigurationError("path must be text or Path.", code="INVALID_PDB_PATH")
+    source = Path(path).expanduser().resolve()
+    if not source.is_file():
+        raise InputFormatError(
+            "PDB path is not a readable file.",
+            code="PDB_FILE_NOT_FOUND",
+            context={"path": str(source)},
+        )
+    size = source.stat().st_size
+    if not 1 <= size <= _MAX_PDB_BYTES:
+        raise InputFormatError(
+            f"PDB file size must be in [1, {_MAX_PDB_BYTES}] bytes.",
+            code="PDB_FILE_SIZE_LIMIT",
+            context={"size_bytes": size},
+        )
+    payload = source.read_bytes()
+    digest = hashlib.sha256(payload).hexdigest()
+    try:
+        text = payload.decode("ascii")
+    except UnicodeDecodeError as exc:
+        raise InputFormatError(
+            "Legacy PDB files must contain ASCII text.", code="INVALID_PDB_ENCODING"
+        ) from exc
+    pdb_id: str | None = None
+    title_parts: list[str] = []
+    current_model = 1
+    explicit_models = False
+    selected_atoms: dict[int, dict[tuple[str, int, str, str, str], tuple[int, float, Atom3D]]] = (
+        defaultdict(dict)
+    )
+    atom_records = 0
+    for line_number, raw_line in enumerate(text.splitlines(), start=1):
+        line = raw_line.ljust(80)
+        record = line[:6]
+        if record == "HEADER":
+            candidate = line[62:66].strip().upper()
+            if candidate:
+                pdb_id = candidate
+        elif record == "TITLE ":
+            part = line[10:80].strip()
+            if part:
+                title_parts.append(part)
+        elif record == "MODEL ":
+            explicit_models = True
+            current_model = _integer(line[10:14], "model", line_number)
+            if not 1 <= current_model <= _MAX_MODELS:
+                raise InputFormatError(
+                    "PDB model index exceeds the safety limit.",
+                    code="PDB_MODEL_LIMIT",
+                    context={"model_index": current_model},
+                )
+        elif record == "ATOM  ":
+            residue_name = line[17:20].strip().upper()
+            if residue_name not in _DNA_RESIDUES:
+                continue
+            atom_records += 1
+            if atom_records > _MAX_ATOMS:
+                raise InputFormatError(
+                    "PDB DNA atom count exceeds the safety limit.",
+                    code="PDB_ATOM_LIMIT",
+                )
+            altloc = line[16].strip()
+            if altloc not in {"", "A"}:
+                continue
+            serial = _integer(line[6:11], "serial", line_number)
+            atom_name = line[12:16].strip()
+            chain_id = line[21].strip() or "_"
+            residue_number = _integer(line[22:26], "residue_number", line_number)
+            insertion_code = line[26].strip()
+            occupancy = _number(line[54:60], "occupancy", line_number, default=1.0)
+            atom = Atom3D(
+                serial=serial,
+                name=atom_name,
+                element=_element(atom_name, line[76:78]),
+                residue_name=residue_name,
+                chain_id=chain_id,
+                residue_number=residue_number,
+                insertion_code=insertion_code,
+                x_angstrom=_number(line[30:38], "x", line_number),
+                y_angstrom=_number(line[38:46], "y", line_number),
+                z_angstrom=_number(line[46:54], "z", line_number),
+                occupancy=occupancy,
+                model_index=current_model,
+            )
+            key = (chain_id, residue_number, insertion_code, residue_name, atom_name)
+            priority = 2 if not altloc else 1
+            previous = selected_atoms[current_model].get(key)
+            if previous is None or (priority, occupancy) > (previous[0], previous[1]):
+                selected_atoms[current_model][key] = (priority, occupancy, atom)
+    if not selected_atoms:
+        raise InputFormatError(
+            "PDB file contains no canonical DNA ATOM records.",
+            code="PDB_DNA_ATOMS_NOT_FOUND",
+        )
+    if explicit_models and len(selected_atoms) > _MAX_MODELS:
+        raise InputFormatError("PDB model count exceeds the safety limit.", code="PDB_MODEL_LIMIT")
+    title = " ".join(title_parts) or None
+    return tuple(
+        _structure(
+            path=source,
+            digest=digest,
+            pdb_id=pdb_id,
+            title=title,
+            model_index=model_index,
+            atoms=tuple(value[2] for value in model_atoms.values()),
+        )
+        for model_index, model_atoms in sorted(selected_atoms.items())
+    )
+
+
+def load_pdb(path: str | Path, *, model_index: int = 1) -> DNA3DStructure:
+    """Load one selected PDB model."""
+
+    if isinstance(model_index, bool) or not isinstance(model_index, int) or model_index <= 0:
+        raise ConfigurationError(
+            "model_index must be a positive integer.", code="INVALID_PDB_MODEL_INDEX"
+        )
+    structures = load_pdb_ensemble(path)
+    for structure in structures:
+        if structure.model_index == model_index:
+            return structure
+    raise InputFormatError(
+        "Requested PDB model is absent.",
+        code="PDB_MODEL_NOT_FOUND",
+        context={
+            "model_index": model_index,
+            "available_models": tuple(item.model_index for item in structures),
+        },
+    )
+
+
+__all__ = ["load_pdb", "load_pdb_ensemble"]

dnakit/structure3d/results.py

@@ -0,0 +1,233 @@
+"""Immutable coordinate, geometry, flexibility, and 3DNA/DSSR result objects."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, cast
+
+from dnakit.core import Provenance
+from dnakit.core._json import to_json_compatible
+
+
+class _SerializableResult:
+    def to_dict(self) -> dict[str, Any]:
+        return cast(dict[str, Any], to_json_compatible(self))
+
+
+@dataclass(frozen=True)
+class Atom3D(_SerializableResult):
+    serial: int
+    name: str
+    element: str
+    residue_name: str
+    chain_id: str
+    residue_number: int
+    insertion_code: str
+    x_angstrom: float
+    y_angstrom: float
+    z_angstrom: float
+    occupancy: float
+    model_index: int
+
+    @property
+    def coordinates(self) -> tuple[float, float, float]:
+        return (self.x_angstrom, self.y_angstrom, self.z_angstrom)
+
+
+@dataclass(frozen=True)
+class Residue3D(_SerializableResult):
+    name: str
+    base: str
+    chain_id: str
+    number: int
+    insertion_code: str
+    atoms: tuple[Atom3D, ...]
+
+
+@dataclass(frozen=True)
+class DNA3DStructure(_SerializableResult):
+    pdb_id: str | None
+    title: str | None
+    model_index: int
+    source_path: str
+    source_sha256: str
+    atoms: tuple[Atom3D, ...]
+    residues: tuple[Residue3D, ...]
+    chain_ids: tuple[str, ...]
+    sequence_by_chain: tuple[str, ...]
+    parser: str
+
+
+@dataclass(frozen=True)
+class ChainGeometry(_SerializableResult):
+    chain_id: str
+    residue_count: int
+    contour_length_angstrom: float
+    end_to_end_distance_angstrom: float
+    anchor_atom: str
+
+
+@dataclass(frozen=True)
+class ShapeGeometry(_SerializableResult):
+    center_of_mass_angstrom: tuple[float, float, float]
+    radius_of_gyration_angstrom: float
+    principal_moments_dalton_angstrom2: tuple[float, float, float]
+    gyration_eigenvalues_angstrom2: tuple[float, float, float]
+    sphericity: float
+    eccentricity: float
+    asphericity_angstrom2: float
+    relative_shape_anisotropy: float
+
+
+@dataclass(frozen=True)
+class HydrogenBondGeometry(_SerializableResult):
+    explicit_hydrogen_bond_count: int | None
+    geometric_base_n_o_contact_count: int
+    heavy_atom_distance_cutoff_angstrom: float
+    method: str
+    limitation: str
+
+
+@dataclass(frozen=True)
+class BackboneTorsion(_SerializableResult):
+    chain_id: str
+    residue_number: int
+    insertion_code: str
+    alpha_degree: float | None
+    beta_degree: float | None
+    gamma_degree: float | None
+    delta_degree: float | None
+    epsilon_degree: float | None
+    zeta_degree: float | None
+
+
+@dataclass(frozen=True)
+class HelixGeometry(_SerializableResult):
+    chain_ids: tuple[str, str]
+    base_pair_count: int
+    helical_axis_unit_vector: tuple[float, float, float]
+    helical_contour_length_angstrom: float
+    mean_rise_angstrom: float
+    mean_twist_degree: float
+    helical_pitch_angstrom: float
+    base_pairs_per_turn: float
+    bending_angle_degree: float
+    mean_curvature_inverse_angstrom: float
+    method: str
+    limitation: str
+
+
+@dataclass(frozen=True)
+class Conditional3DFeature(_SerializableResult):
+    name: str
+    status: str
+    required_input_or_backend: str
+    reason: str
+
+
+@dataclass(frozen=True)
+class Structure3DAnalysisResult(_SerializableResult):
+    pdb_id: str | None
+    model_index: int
+    atom_count: int
+    residue_count: int
+    chain_count: int
+    chain_geometry: tuple[ChainGeometry, ...]
+    shape: ShapeGeometry
+    solvent_accessible_surface_area_angstrom2: float
+    molecular_volume_angstrom3: float
+    sasa_probe_radius_angstrom: float
+    sasa_points_per_atom: int
+    volume_grid_spacing_angstrom: float
+    hydrogen_bonds: HydrogenBondGeometry
+    backbone_torsions: tuple[BackboneTorsion, ...]
+    helix: HelixGeometry | None
+    conditional_features: tuple[Conditional3DFeature, ...]
+    method: str
+    provenance: Provenance
+
+
+@dataclass(frozen=True)
+class ResidueFlexibility(_SerializableResult):
+    chain_id: str
+    residue_number: int
+    insertion_code: str
+    rmsf_angstrom: float
+    common_atom_count: int
+
+
+@dataclass(frozen=True)
+class EnsembleFlexibilityResult(_SerializableResult):
+    model_count: int
+    common_atom_count: int
+    mean_atomic_rmsf_angstrom: float
+    max_atomic_rmsf_angstrom: float
+    residue_flexibility: tuple[ResidueFlexibility, ...]
+    method: str
+    limitation: str
+    provenance: Provenance
+
+
+@dataclass(frozen=True)
+class BasePairStepParameters(_SerializableResult):
+    index: int
+    base_pair: str
+    shear_angstrom: float
+    stretch_angstrom: float
+    stagger_angstrom: float
+    buckle_degree: float
+    propeller_degree: float
+    opening_degree: float
+    shift_angstrom: float
+    slide_angstrom: float
+    rise_angstrom: float
+    tilt_degree: float
+    roll_degree: float
+    twist_degree: float
+
+
+@dataclass(frozen=True)
+class ThreeDNAParameterResult(_SerializableResult):
+    source_path: str
+    base_pair_count: int
+    parameters: tuple[BasePairStepParameters, ...]
+    mean_rise_angstrom: float | None
+    mean_twist_degree: float | None
+    helical_pitch_angstrom: float | None
+    base_pairs_per_turn: float | None
+    method: str
+    provenance: Provenance
+
+
+@dataclass(frozen=True)
+class DSSRSummaryResult(_SerializableResult):
+    source_path: str
+    program_version: str
+    nucleotide_count: int
+    pair_count: int
+    helix_count: int
+    stem_count: int
+    hairpin_count: int
+    hydrogen_bond_count: int
+    backbone_torsion_record_count: int
+    method: str
+    provenance: Provenance
+
+
+__all__ = [
+    "Atom3D",
+    "BackboneTorsion",
+    "BasePairStepParameters",
+    "ChainGeometry",
+    "Conditional3DFeature",
+    "DNA3DStructure",
+    "DSSRSummaryResult",
+    "EnsembleFlexibilityResult",
+    "HelixGeometry",
+    "HydrogenBondGeometry",
+    "Residue3D",
+    "ResidueFlexibility",
+    "ShapeGeometry",
+    "Structure3DAnalysisResult",
+    "ThreeDNAParameterResult",
+]

dnakit/structure3d/threedna.py

@@ -0,0 +1,174 @@
+"""Parsers for standard 3DNA base-pair steps and DSSR JSON summaries."""
+
+from __future__ import annotations
+
+import json
+import math
+from collections.abc import Mapping
+from pathlib import Path
+from typing import cast
+
+from dnakit.exceptions import ConfigurationError, InputFormatError
+
+from ._shared import threedna_provenance
+from .results import BasePairStepParameters, DSSRSummaryResult, ThreeDNAParameterResult
+
+_MAX_PARAMETER_BYTES = 100_000_000
+_MAX_BASE_PAIRS = 1_000_000
+
+
+def _source(path: str | Path) -> tuple[Path, str]:
+    if not isinstance(path, (str, Path)):
+        raise ConfigurationError("path must be text or Path.", code="INVALID_3DNA_PATH")
+    source = Path(path).expanduser().resolve()
+    if not source.is_file():
+        raise InputFormatError(
+            "3DNA/DSSR input file does not exist.",
+            code="THREEDNA_FILE_NOT_FOUND",
+            context={"path": str(source)},
+        )
+    size = source.stat().st_size
+    if not 1 <= size <= _MAX_PARAMETER_BYTES:
+        raise InputFormatError(
+            f"3DNA/DSSR input size must be in [1, {_MAX_PARAMETER_BYTES}] bytes.",
+            code="THREEDNA_FILE_SIZE_LIMIT",
+        )
+    try:
+        return source, source.read_text(encoding="utf-8")
+    except UnicodeDecodeError as exc:
+        raise InputFormatError(
+            "3DNA/DSSR text must be UTF-8 compatible.", code="INVALID_3DNA_ENCODING"
+        ) from exc
+
+
+def read_3dna_bp_step(path: str | Path) -> ThreeDNAParameterResult:
+    """Parse the 12 standard rigid-body columns from ``bp_step.par``."""
+
+    source, text = _source(path)
+    lines = tuple(line.strip() for line in text.splitlines() if line.strip())
+    if not lines:
+        raise InputFormatError("3DNA parameter file is empty.", code="EMPTY_3DNA_PARAMETERS")
+    try:
+        declared_count = int(lines[0].split()[0])
+    except (ValueError, IndexError) as exc:
+        raise InputFormatError(
+            "The first 3DNA bp_step.par line must declare the base-pair count.",
+            code="INVALID_3DNA_PARAMETERS",
+        ) from exc
+    if not 1 <= declared_count <= _MAX_BASE_PAIRS:
+        raise InputFormatError(
+            "Declared 3DNA base-pair count is outside safety limits.",
+            code="INVALID_3DNA_PARAMETERS",
+        )
+    parameters: list[BasePairStepParameters] = []
+    for line in lines[1:]:
+        tokens = line.split()
+        if len(tokens) != 13 or not any(separator in tokens[0] for separator in ("-", "/")):
+            continue
+        try:
+            values = tuple(float(token) for token in tokens[1:])
+        except ValueError:
+            continue
+        if any(not math.isfinite(value) for value in values):
+            raise InputFormatError(
+                "3DNA parameters must be finite.", code="INVALID_3DNA_PARAMETERS"
+            )
+        parameters.append(
+            BasePairStepParameters(
+                len(parameters) + 1,
+                tokens[0],
+                *values,
+            )
+        )
+    if len(parameters) != declared_count:
+        raise InputFormatError(
+            "Parsed 3DNA parameter rows do not match the declared base-pair count.",
+            code="THREEDNA_PARAMETER_COUNT_MISMATCH",
+            context={"declared": declared_count, "parsed": len(parameters)},
+        )
+    step_rows = parameters[1:]
+    mean_rise = (
+        None
+        if not step_rows
+        else math.fsum(item.rise_angstrom for item in step_rows) / len(step_rows)
+    )
+    mean_twist = (
+        None
+        if not step_rows
+        else math.fsum(item.twist_degree for item in step_rows) / len(step_rows)
+    )
+    base_pairs_per_turn = None if mean_twist is None or mean_twist == 0.0 else 360.0 / mean_twist
+    pitch = (
+        None
+        if mean_rise is None or base_pairs_per_turn is None
+        else mean_rise * base_pairs_per_turn
+    )
+    return ThreeDNAParameterResult(
+        source_path=str(source),
+        base_pair_count=declared_count,
+        parameters=tuple(parameters),
+        mean_rise_angstrom=mean_rise,
+        mean_twist_degree=mean_twist,
+        helical_pitch_angstrom=pitch,
+        base_pairs_per_turn=base_pairs_per_turn,
+        method="3dna-bp-step-12-parameter-parser-v1",
+        provenance=threedna_provenance(),
+    )
+
+
+def _count(data: Mapping[str, object], count_key: str, array_key: str) -> int:
+    raw_count = data.get(count_key)
+    raw_array = data.get(array_key, ())
+    if raw_count is None:
+        if isinstance(raw_array, list):
+            return len(raw_array)
+        return 0
+    if isinstance(raw_count, bool) or not isinstance(raw_count, int) or raw_count < 0:
+        raise InputFormatError(
+            f"DSSR {count_key} must be a non-negative integer.",
+            code="INVALID_DSSR_JSON",
+        )
+    if isinstance(raw_array, list) and len(raw_array) != raw_count:
+        raise InputFormatError(
+            f"DSSR {count_key} disagrees with {array_key} length.",
+            code="DSSR_COUNT_MISMATCH",
+        )
+    return raw_count
+
+
+def read_dssr_json(path: str | Path) -> DSSRSummaryResult:
+    """Parse audited capability counts from an x3dna-dssr ``--json`` result."""
+
+    source, text = _source(path)
+    try:
+        raw = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise InputFormatError(
+            "DSSR input is not valid JSON.",
+            code="INVALID_DSSR_JSON",
+            context={"line": exc.lineno, "column": exc.colno},
+        ) from exc
+    if not isinstance(raw, Mapping):
+        raise InputFormatError("DSSR JSON root must be an object.", code="INVALID_DSSR_JSON")
+    data = cast(Mapping[str, object], raw)
+    version = data.get("dssr_ver", data.get("program", "unknown DSSR version"))
+    if not isinstance(version, str) or not version.strip() or len(version) > 1_000:
+        raise InputFormatError("DSSR program version is invalid.", code="INVALID_DSSR_JSON")
+    torsions_key = "ntParams" if "ntParams" in data else "ntPars"
+    raw_torsions = data.get(torsions_key)
+    return DSSRSummaryResult(
+        source_path=str(source),
+        program_version=version,
+        nucleotide_count=_count(data, "num_nts", "nts"),
+        pair_count=_count(data, "num_pairs", "pairs"),
+        helix_count=_count(data, "num_helices", "helices"),
+        stem_count=_count(data, "num_stems", "stems"),
+        hairpin_count=_count(data, "num_hairpins", "hairpins"),
+        hydrogen_bond_count=_count(data, "num_hbonds", "hbonds"),
+        backbone_torsion_record_count=len(raw_torsions) if isinstance(raw_torsions, list) else 0,
+        method="x3dna-dssr-json-summary-parser-v1",
+        provenance=threedna_provenance(),
+    )
+
+
+__all__ = ["read_3dna_bp_step", "read_dssr_json"]