jupytermind 0.3.0

package/src/ai_structural_biology_scientist/secondary_structure.py

@@ -0,0 +1,95 @@
+"""Secondary-structure heuristic module (DES-ASTRUCT-010 / REQ-ASTRUCT-010)."""
+
+from __future__ import annotations
+
+from ai_structural_biology_scientist.validation import (
+    fail,
+    register_validator,
+    validate_uppercase_sequence,
+)
+
+_MODULE_NAME = "secondary-structure-heuristic"
+_PROPENSITIES = {
+    "A": (1.42, 0.83, 0.75),
+    "R": (0.98, 0.93, 1.09),
+    "N": (0.67, 0.89, 1.44),
+    "D": (1.01, 0.54, 1.45),
+    "C": (0.70, 1.19, 1.11),
+    "Q": (1.11, 1.10, 0.79),
+    "E": (1.51, 0.37, 1.12),
+    "G": (0.57, 0.75, 1.68),
+    "H": (1.00, 0.87, 1.13),
+    "I": (1.08, 1.60, 0.32),
+    "L": (1.21, 1.30, 0.49),
+    "K": (1.16, 0.74, 1.10),
+    "M": (1.45, 1.05, 0.50),
+    "F": (1.13, 1.38, 0.49),
+    "P": (0.57, 0.55, 1.88),
+    "S": (0.77, 0.75, 1.48),
+    "T": (0.83, 1.19, 0.98),
+    "W": (1.08, 1.37, 0.55),
+    "Y": (0.69, 1.47, 0.84),
+    "V": (1.06, 1.70, 0.41),
+}
+_CLASS_ORDER = ("H", "E", "C")
+
+LIMITATION_LABEL_KEY = "secondary_structure_heuristic_limitation"
+LIMITATION_LABEL_TEXT = {
+    "en": (
+        "Heuristic only: a fixed illustrative per-residue propensity lookup, not a "
+        "validated secondary-structure predictor (no windowing, no real Chou-Fasman "
+        "statistics)."
+    ),
+    "ja": (
+        "ヒューリスティックのみ：固定の説明用残基別 propensity lookup であり、"
+        "検証済みの二次構造予測器ではない（windowing なし、実際の Chou-Fasman "
+        "統計なし）。"
+    ),
+}
+
+
+def _secondary_structure_validator(params: dict) -> dict:
+    """DES-ASTRUCT-002 registered atomic validator for this module."""
+    if "sequence" not in params:
+        return fail("sequence", "is required")
+    return validate_uppercase_sequence(params)
+
+
+register_validator(_MODULE_NAME, _secondary_structure_validator)
+
+
+# @id CODE-ASTRUCT-010
+# @implements REQ-ASTRUCT-010
+# @design DES-ASTRUCT-010
+def run_secondary_structure(sequence: str) -> dict:
+    """Compute the fixed-table structural assignment for ``sequence``."""
+    sequence_validation = validate_uppercase_sequence({"sequence": sequence})
+    if not sequence_validation["ok"]:
+        raise ValueError("sequence must already be validated by the handler wrapper")
+
+    residues = []
+    classes = []
+    for position, residue in enumerate(sequence):
+        helix, sheet, coil = _PROPENSITIES[residue]
+        propensity_by_class = {"H": helix, "E": sheet, "C": coil}
+        # Documented fixed tie-break order H > E > C: ``_CLASS_ORDER`` is
+        # iterated in that exact order and ``max`` keeps the first maximal
+        # element on ties, so this is equivalent to, but clearer than, an
+        # explicit negated-index secondary sort key.
+        assigned_class = max(
+            _CLASS_ORDER,
+            key=lambda klass: propensity_by_class[klass],
+        )
+        residues.append({"position": position, "residue": residue, "class": assigned_class})
+        classes.append(assigned_class)
+
+    secondary_structure = "".join(classes)
+    length = len(sequence)
+    return {
+        "residues": residues,
+        "secondary_structure": secondary_structure,
+        "helix_fraction": secondary_structure.count("H") / length,
+        "sheet_fraction": secondary_structure.count("E") / length,
+        "coil_fraction": secondary_structure.count("C") / length,
+        "limitation_label_key": LIMITATION_LABEL_KEY,
+    }

package/src/ai_structural_biology_scientist/structural_similarity.py

@@ -0,0 +1,74 @@
+"""Structural similarity module (DES-ASTRUCT-040 / REQ-ASTRUCT-040)."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from ai_structural_biology_scientist.validation import fail, register_validator, validate_coordinate
+
+_MODULE_NAME = "structural-similarity-rmsd"
+
+
+def _structural_similarity_validator(params: dict) -> dict:
+    """DES-ASTRUCT-002 registered atomic validator for this module."""
+    for name in ("structure_a", "structure_b"):
+        if name not in params:
+            return fail(name, "is required")
+
+    structure_a = params["structure_a"]
+    structure_b = params["structure_b"]
+    if not isinstance(structure_a, (list, tuple)):
+        return fail("structure_a", "must be a list/tuple of coordinates")
+    if not isinstance(structure_b, (list, tuple)):
+        return fail("structure_b", "must be a list/tuple of coordinates")
+    if len(structure_a) != len(structure_b):
+        return fail("structure_b", "must have the same length as structure_a")
+    if len(structure_a) < 3:
+        return fail("structure_a", "must contain at least 3 coordinates")
+
+    for name, structure in (("structure_a", structure_a), ("structure_b", structure_b)):
+        for index, coordinate in enumerate(structure):
+            coordinate_validation = validate_coordinate(coordinate, parameter=f"{name}[{index}]")
+            if not coordinate_validation["ok"]:
+                return coordinate_validation
+
+    return {"ok": True}
+
+
+register_validator(_MODULE_NAME, _structural_similarity_validator)
+
+
+# @id CODE-ASTRUCT-040
+# @implements REQ-ASTRUCT-040
+# @design DES-ASTRUCT-040
+def run_structural_similarity(structure_a: list, structure_b: list) -> dict:
+    """Compute Kabsch RMSD after optimal rigid-body superposition."""
+    validation = _structural_similarity_validator(
+        {"structure_a": structure_a, "structure_b": structure_b}
+    )
+    if not validation["ok"]:
+        raise ValueError("parameters must already be validated by the handler wrapper")
+
+    a = np.asarray(structure_a, dtype=float)
+    b = np.asarray(structure_b, dtype=float)
+    centroid_a = a.mean(axis=0)
+    centroid_b = b.mean(axis=0)
+    centered_a = a - centroid_a
+    centered_b = b - centroid_b
+
+    cross_covariance = centered_a.T @ centered_b
+    u, _, vt = np.linalg.svd(cross_covariance)
+    rotation = vt.T @ u.T
+    if np.linalg.det(rotation) < 0:
+        vt[-1, :] *= -1
+        rotation = vt.T @ u.T
+
+    translation = centroid_b - rotation @ centroid_a
+    aligned_a = (rotation @ a.T).T + translation
+    rmsd = np.sqrt(np.mean(np.sum((aligned_a - b) ** 2, axis=1)))
+
+    return {
+        "rmsd": float(rmsd),
+        "rotation_matrix": rotation.tolist(),
+        "translation": translation.tolist(),
+    }

package/src/ai_structural_biology_scientist/validation.py

@@ -0,0 +1,100 @@
+"""Shared parameter validator (DES-ASTRUCT-002 / REQ-ASTRUCT-003)."""
+
+from __future__ import annotations
+
+import importlib
+import math
+from collections.abc import Callable, Mapping, Sequence
+from numbers import Real
+from typing import Any
+
+ValidationResult = dict[str, Any]
+ValidatorFn = Callable[[dict[str, Any]], ValidationResult]
+
+_REGISTRY: dict[str, ValidatorFn] = {}
+_VALIDATOR_MODULES = {
+    "secondary-structure-heuristic": "ai_structural_biology_scientist.secondary_structure",
+    "hydrophobicity-burial-heuristic": "ai_structural_biology_scientist.hydrophobicity",
+    "protein-protein-docking-score": "ai_structural_biology_scientist.protein_docking_score",
+    "structural-similarity-rmsd": "ai_structural_biology_scientist.structural_similarity",
+    "residue-contact-map": "ai_structural_biology_scientist.contact_map",
+}
+_SEQUENCE_ALPHABET = "ACDEFGHIKLMNPQRSTVWY"
+_COORDINATE_CONSTRAINT = "must be a list/tuple of exactly 3 finite real numbers"
+
+
+def ok() -> ValidationResult:
+    return {"ok": True}
+
+
+def fail(parameter: str, constraint: str) -> ValidationResult:
+    return {"ok": False, "parameter": parameter, "constraint": constraint}
+
+
+def is_finite_real(value: Any) -> bool:
+    return isinstance(value, Real) and not isinstance(value, bool) and math.isfinite(value)
+
+
+def validate_uppercase_sequence(
+    params: dict[str, Any], parameter: str = "sequence"
+) -> ValidationResult:
+    sequence = params.get(parameter)
+    if not isinstance(sequence, str) or sequence == "":
+        return fail(parameter, f"must be a non-empty uppercase sequence over {_SEQUENCE_ALPHABET}")
+    for index, residue in enumerate(sequence):
+        if residue not in _SEQUENCE_ALPHABET:
+            return fail(
+                parameter,
+                (
+                    f"must contain only uppercase residues from {_SEQUENCE_ALPHABET}; "
+                    f"first invalid character {residue!r} at index {index}"
+                ),
+            )
+    return ok()
+
+
+def validate_coordinate(
+    coordinate: Any,
+    *,
+    parameter: str,
+    constraint: str = _COORDINATE_CONSTRAINT,
+) -> ValidationResult:
+    if not isinstance(coordinate, (list, tuple)) or len(coordinate) != 3:
+        return fail(parameter, constraint)
+    if any(not is_finite_real(value) for value in coordinate):
+        return fail(parameter, constraint)
+    return ok()
+
+
+def _ensure_validator_registered(module_name: str) -> None:
+    if module_name in _REGISTRY:
+        return
+    module_path = _VALIDATOR_MODULES.get(module_name)
+    if module_path is not None:
+        importlib.import_module(module_path)
+
+
+# @id CODE-ASTRUCT-002
+# @implements REQ-ASTRUCT-003
+# @design DES-ASTRUCT-002
+def register_validator(module_name: str, validator: ValidatorFn) -> None:
+    """Register ``module_name``'s documented atomic validator."""
+    if module_name in _REGISTRY:
+        raise ValueError(  # noqa: TRY004
+            f"validator already registered for module '{module_name}'"
+        )
+    _REGISTRY[module_name] = validator
+
+
+# @id CODE-ASTRUCT-902
+# @implements REQ-ASTRUCT-003
+# @design DES-ASTRUCT-002
+def validate_parameters(module_name: str, params: dict[str, Any]) -> ValidationResult:
+    """Dispatch to ``module_name``'s registered atomic validator."""
+    _ensure_validator_registered(module_name)
+    validator = _REGISTRY.get(module_name)
+    if validator is None:
+        return fail("module", f"no validator registered for module '{module_name}'")
+    if not isinstance(params, Mapping):
+        return fail("params", "must be a dict")
+    return validator(dict(params))