dnakit 0.1.0.dev0__py3-none-any.whl

dnakit/descriptors/_dinucleotide.py

@@ -0,0 +1,345 @@
+"""Validated user-supplied dinucleotide-property tables.
+
+DNAKit deliberately ships property names and units only. Numerical
+coefficients must be supplied by the caller in an explicitly loaded JSON file.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from dnakit.core._json import FrozenDict
+from dnakit.exceptions import ConfigurationError
+
+DINUCLEOTIDES = (
+    "AA",
+    "AC",
+    "AG",
+    "AT",
+    "CA",
+    "CC",
+    "CG",
+    "CT",
+    "GA",
+    "GC",
+    "GG",
+    "GT",
+    "TA",
+    "TC",
+    "TG",
+    "TT",
+)
+DINUCLEOTIDE_TABLE_SCHEMA_VERSION = "dnakit.dinucleotide_property_table.v1"
+DEFAULT_MAX_DINUCLEOTIDE_TABLE_BYTES = 1_000_000
+_MAX_METADATA_LENGTH = 1_000
+_MAX_ABSOLUTE_VALUE = 1.0e12
+
+
+@dataclass(frozen=True, slots=True)
+class DinucleotidePropertySpec:
+    """Stable output identity for one optional dinucleotide-property scale."""
+
+    key: str
+    display_name: str
+    unit: str
+
+
+DINUCLEOTIDE_PROPERTY_SPECS = (
+    DinucleotidePropertySpec("twist", "Twist", "degree"),
+    DinucleotidePropertySpec("tilt", "Tilt", "degree"),
+    DinucleotidePropertySpec("roll", "Roll", "degree"),
+    DinucleotidePropertySpec("shift", "Shift", "angstrom"),
+    DinucleotidePropertySpec("slide", "Slide", "angstrom"),
+    DinucleotidePropertySpec("rise", "Rise", "angstrom"),
+    DinucleotidePropertySpec("bend", "Bend", "degree"),
+    DinucleotidePropertySpec("inclination", "Inclination", "degree"),
+    DinucleotidePropertySpec("direction", "Direction", "degree"),
+    DinucleotidePropertySpec("propeller_twist", "Propeller twist", "degree"),
+    DinucleotidePropertySpec("major_groove_width", "Major groove width", "angstrom"),
+    DinucleotidePropertySpec("minor_groove_width", "Minor groove width", "angstrom"),
+    DinucleotidePropertySpec("persistence_length", "Persistence length", "nanometer"),
+    DinucleotidePropertySpec("stacking_energy", "Stacking energy", "kcal/mol"),
+    DinucleotidePropertySpec("free_energy", "Free energy", "kcal/mol"),
+)
+
+
+@dataclass(frozen=True, slots=True)
+class DinucleotideProperty:
+    """One fully validated 16-value property supplied by the caller."""
+
+    key: str
+    display_name: str
+    unit: str
+    values: FrozenDict
+
+    def __post_init__(self) -> None:
+        spec = next((item for item in DINUCLEOTIDE_PROPERTY_SPECS if item.key == self.key), None)
+        if spec is None or self.display_name != spec.display_name or self.unit != spec.unit:
+            raise ConfigurationError(
+                "Dinucleotide property identity does not match the fixed schema.",
+                code="INVALID_DINUCLEOTIDE_TABLE_PROPERTY",
+                context={"property": self.key},
+            )
+        object.__setattr__(self, "values", _validated_coefficients(self.values, spec))
+
+
+@dataclass(frozen=True, slots=True)
+class DinucleotidePropertyTable:
+    """An immutable, checksummed table loaded from a user-owned JSON file."""
+
+    name: str
+    version: str
+    source: str
+    sha256: str
+    properties: tuple[DinucleotideProperty, ...]
+
+    def __post_init__(self) -> None:
+        for field_name in ("name", "version", "source"):
+            value = getattr(self, field_name)
+            if not isinstance(value, str) or not value.strip() or len(value) > _MAX_METADATA_LENGTH:
+                raise ConfigurationError(
+                    f"Dinucleotide table {field_name} must be non-empty bounded text.",
+                    code="INVALID_DINUCLEOTIDE_TABLE_METADATA",
+                )
+        if (
+            not isinstance(self.sha256, str)
+            or len(self.sha256) != 64
+            or any(character not in "0123456789abcdef" for character in self.sha256)
+        ):
+            raise ConfigurationError(
+                "Dinucleotide table sha256 must contain 64 lowercase hexadecimal digits.",
+                code="INVALID_DINUCLEOTIDE_TABLE_CHECKSUM",
+            )
+        if not isinstance(self.properties, tuple) or not all(
+            isinstance(item, DinucleotideProperty) for item in self.properties
+        ):
+            raise ConfigurationError(
+                "Dinucleotide table properties must be a tuple of validated properties.",
+                code="INVALID_DINUCLEOTIDE_TABLE_PROPERTIES",
+            )
+        expected = tuple(spec.key for spec in DINUCLEOTIDE_PROPERTY_SPECS)
+        observed = tuple(item.key for item in self.properties)
+        if observed != expected:
+            raise ConfigurationError(
+                "Dinucleotide table properties must follow the required 15-property order.",
+                code="INVALID_DINUCLEOTIDE_TABLE_PROPERTIES",
+                context={"expected": expected, "observed": observed},
+            )
+
+    def property(self, key: str) -> DinucleotideProperty:
+        """Return one required property by its stable key."""
+
+        for item in self.properties:
+            if item.key == key:
+                return item
+        raise KeyError(key)  # pragma: no cover - construction enforces all keys.
+
+
+def _object_without_duplicates(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    for key, value in pairs:
+        if key in result:
+            raise ConfigurationError(
+                "Dinucleotide table JSON contains a duplicate object key.",
+                code="DUPLICATE_DINUCLEOTIDE_TABLE_KEY",
+                context={"key": key},
+            )
+        result[key] = value
+    return result
+
+
+def _bounded_metadata(value: object, name: str) -> str:
+    if not isinstance(value, str) or not value.strip() or len(value) > _MAX_METADATA_LENGTH:
+        raise ConfigurationError(
+            f"Dinucleotide table {name} must be non-empty bounded text.",
+            code="INVALID_DINUCLEOTIDE_TABLE_METADATA",
+            context={"field": name},
+        )
+    return value.strip()
+
+
+def _validated_coefficients(
+    raw_values: object,
+    spec: DinucleotidePropertySpec,
+) -> FrozenDict:
+    if not isinstance(raw_values, Mapping) or set(raw_values) != set(DINUCLEOTIDES):
+        raise ConfigurationError(
+            "Each property must define exactly the 16 canonical dinucleotides.",
+            code="INCOMPLETE_DINUCLEOTIDE_TABLE_PROPERTY",
+            context={"property": spec.key, "required_dinucleotides": DINUCLEOTIDES},
+        )
+    resolved: dict[str, float] = {}
+    for word in DINUCLEOTIDES:
+        item = raw_values[word]
+        if (
+            isinstance(item, bool)
+            or not isinstance(item, (int, float))
+            or not math.isfinite(item)
+            or abs(float(item)) > _MAX_ABSOLUTE_VALUE
+        ):
+            raise ConfigurationError(
+                "Dinucleotide coefficients must be finite bounded numbers.",
+                code="INVALID_DINUCLEOTIDE_TABLE_VALUE",
+                context={"property": spec.key, "dinucleotide": word},
+            )
+        resolved[word] = float(item)
+    return FrozenDict(resolved)
+
+
+def _property_values(value: object, spec: DinucleotidePropertySpec) -> FrozenDict:
+    if not isinstance(value, Mapping):
+        raise ConfigurationError(
+            "Each dinucleotide property must be a JSON object.",
+            code="INVALID_DINUCLEOTIDE_TABLE_PROPERTY",
+            context={"property": spec.key},
+        )
+    if set(value) != {"unit", "values"}:
+        raise ConfigurationError(
+            "Each dinucleotide property must contain exactly 'unit' and 'values'.",
+            code="INVALID_DINUCLEOTIDE_TABLE_PROPERTY",
+            context={"property": spec.key},
+        )
+    if value["unit"] != spec.unit:
+        raise ConfigurationError(
+            "Dinucleotide property unit does not match the fixed descriptor schema.",
+            code="DINUCLEOTIDE_TABLE_UNIT_MISMATCH",
+            context={
+                "property": spec.key,
+                "expected_unit": spec.unit,
+                "observed_unit": value["unit"],
+            },
+        )
+    return _validated_coefficients(value["values"], spec)
+
+
+def load_dinucleotide_property_table(
+    path: str | Path,
+    *,
+    max_bytes: int = DEFAULT_MAX_DINUCLEOTIDE_TABLE_BYTES,
+) -> DinucleotidePropertyTable:
+    """Load a bounded JSON table supplied and licensed by the caller.
+
+    Loading is explicit and local. DNAKit does not fetch, generate, cache, or
+    redistribute the table and records a SHA-256 digest for every calculation.
+    """
+
+    if (
+        isinstance(max_bytes, bool)
+        or not isinstance(max_bytes, int)
+        or not 1 <= max_bytes <= 10_000_000
+    ):
+        raise ConfigurationError("max_bytes must be an integer in [1, 10000000].")
+    try:
+        resolved_path = Path(path).expanduser().resolve(strict=True)
+        size = resolved_path.stat().st_size
+    except (OSError, RuntimeError, TypeError, ValueError) as exc:
+        raise ConfigurationError(
+            "Dinucleotide property table is unavailable.",
+            code="DINUCLEOTIDE_TABLE_UNAVAILABLE",
+            context={"path": str(path)},
+        ) from exc
+    if not resolved_path.is_file():
+        raise ConfigurationError(
+            "Dinucleotide property table must be a regular file.",
+            code="DINUCLEOTIDE_TABLE_UNAVAILABLE",
+            context={"path": str(resolved_path)},
+        )
+    if size > max_bytes:
+        raise ConfigurationError(
+            "Dinucleotide property table exceeds max_bytes.",
+            code="DINUCLEOTIDE_TABLE_SIZE_LIMIT",
+            context={"size": size, "max_bytes": max_bytes},
+        )
+    try:
+        with resolved_path.open("rb") as handle:
+            payload = handle.read(max_bytes + 1)
+    except OSError as exc:
+        raise ConfigurationError(
+            "Dinucleotide property table could not be read.",
+            code="DINUCLEOTIDE_TABLE_UNAVAILABLE",
+            context={"path": str(resolved_path)},
+        ) from exc
+    if len(payload) > max_bytes:
+        raise ConfigurationError(
+            "Dinucleotide property table exceeds max_bytes.",
+            code="DINUCLEOTIDE_TABLE_SIZE_LIMIT",
+            context={"size_at_least": len(payload), "max_bytes": max_bytes},
+        )
+    try:
+        decoded = payload.decode("utf-8")
+        raw = json.loads(decoded, object_pairs_hook=_object_without_duplicates)
+    except ConfigurationError:
+        raise
+    except (UnicodeDecodeError, json.JSONDecodeError, RecursionError) as exc:
+        raise ConfigurationError(
+            "Dinucleotide property table must be valid UTF-8 JSON.",
+            code="INVALID_DINUCLEOTIDE_TABLE_JSON",
+            context={"path": str(resolved_path), "error_type": type(exc).__name__},
+        ) from exc
+    if not isinstance(raw, Mapping) or set(raw) != {
+        "schema_version",
+        "name",
+        "version",
+        "source",
+        "properties",
+    }:
+        raise ConfigurationError(
+            "Dinucleotide table root fields do not match the required schema.",
+            code="INVALID_DINUCLEOTIDE_TABLE_SCHEMA",
+        )
+    if raw["schema_version"] != DINUCLEOTIDE_TABLE_SCHEMA_VERSION:
+        raise ConfigurationError(
+            "Unsupported dinucleotide table schema_version.",
+            code="UNSUPPORTED_DINUCLEOTIDE_TABLE_SCHEMA",
+            context={"schema_version": raw["schema_version"]},
+        )
+    raw_properties = raw["properties"]
+    if not isinstance(raw_properties, Mapping):
+        raise ConfigurationError(
+            "Dinucleotide table properties must be a JSON object.",
+            code="INVALID_DINUCLEOTIDE_TABLE_PROPERTIES",
+        )
+    expected_keys = {spec.key for spec in DINUCLEOTIDE_PROPERTY_SPECS}
+    if set(raw_properties) != expected_keys:
+        raise ConfigurationError(
+            "Dinucleotide table must contain exactly the 15 required properties.",
+            code="INVALID_DINUCLEOTIDE_TABLE_PROPERTIES",
+            context={
+                "missing": tuple(sorted(expected_keys - set(raw_properties))),
+                "extra": tuple(sorted(set(raw_properties) - expected_keys)),
+            },
+        )
+    properties = tuple(
+        DinucleotideProperty(
+            key=spec.key,
+            display_name=spec.display_name,
+            unit=spec.unit,
+            values=_property_values(raw_properties[spec.key], spec),
+        )
+        for spec in DINUCLEOTIDE_PROPERTY_SPECS
+    )
+    return DinucleotidePropertyTable(
+        name=_bounded_metadata(raw["name"], "name"),
+        version=_bounded_metadata(raw["version"], "version"),
+        source=_bounded_metadata(raw["source"], "source"),
+        sha256=hashlib.sha256(payload).hexdigest(),
+        properties=properties,
+    )
+
+
+__all__ = [
+    "DEFAULT_MAX_DINUCLEOTIDE_TABLE_BYTES",
+    "DINUCLEOTIDES",
+    "DINUCLEOTIDE_PROPERTY_SPECS",
+    "DINUCLEOTIDE_TABLE_SCHEMA_VERSION",
+    "DinucleotideProperty",
+    "DinucleotidePropertySpec",
+    "DinucleotidePropertyTable",
+    "load_dinucleotide_property_table",
+]

dnakit/descriptors/_shared.py

@@ -0,0 +1,180 @@
+"""Shared validation and sequence traversal for native descriptors."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from dataclasses import dataclass
+from enum import Enum
+from typing import TypeAlias
+
+from dnakit.core.facade import DNA, resolve_single_dna
+from dnakit.core.record import DNARecord
+from dnakit.core.sequence import DNASequence
+from dnakit.exceptions import ConfigurationError, InvalidAlphabetError
+
+SequenceInput: TypeAlias = DNA | DNASequence | DNARecord
+
+
+class DescriptorAmbiguityPolicy(str, Enum):
+    """Treatment of IUPAC symbols that are not one of A, C, G, and T."""
+
+    ERROR = "error"
+    IGNORE = "ignore"
+
+
+def sequence_and_id(value: SequenceInput) -> tuple[DNASequence, str | None]:
+    """Resolve the sequence and optional record identifier from public input."""
+
+    if isinstance(value, (DNA, DNARecord, DNASequence)):
+        sequence, record = resolve_single_dna(value)
+        return sequence, None if record is None else record.id
+    raise ConfigurationError(
+        "Descriptor input must be a DNASequence or DNARecord.",
+        context={"input_type": type(value).__name__},
+    )
+
+
+def coerce_ambiguity_policy(
+    value: DescriptorAmbiguityPolicy | str,
+) -> DescriptorAmbiguityPolicy:
+    """Coerce a public ambiguity policy and report stable configuration errors."""
+
+    try:
+        return (
+            value
+            if isinstance(value, DescriptorAmbiguityPolicy)
+            else DescriptorAmbiguityPolicy(value)
+        )
+    except (TypeError, ValueError) as exc:
+        raise ConfigurationError(
+            "Unknown descriptor ambiguity policy.",
+            context={"ambiguity_policy": value},
+            hint="Choose 'error' or 'ignore'.",
+        ) from exc
+
+
+def validate_bool(value: bool, name: str) -> None:
+    if not isinstance(value, bool):
+        raise ConfigurationError(f"{name} must be a boolean.", context={name: value})
+
+
+def validate_positive_int(value: int, name: str) -> None:
+    if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
+        raise ConfigurationError(
+            f"{name} must be a positive integer.",
+            context={name: value},
+        )
+
+
+def reject_ambiguity(sequence: DNASequence, policy: DescriptorAmbiguityPolicy) -> None:
+    """Reject ambiguity before any partial descriptor calculation."""
+
+    if policy is DescriptorAmbiguityPolicy.ERROR and sequence.ambiguity_count:
+        raise InvalidAlphabetError(
+            "This descriptor does not accept ambiguous IUPAC symbols under the error policy.",
+            code="DESCRIPTOR_AMBIGUITY_NOT_ALLOWED",
+            context={"ambiguity_count": sequence.ambiguity_count},
+            hint="Use ambiguity_policy='ignore' to omit affected symbols or windows.",
+        )
+
+
+def fragments(sequence: DNASequence, *, cross_gaps: bool) -> tuple[str, ...]:
+    """Return symbol fragments without crossing a gap that explicitly forbids it."""
+
+    validate_bool(cross_gaps, "cross_gaps")
+    if not cross_gaps:
+        return tuple(part for part in sequence.parts if isinstance(part, str))
+    resolved: list[str] = []
+    current: list[str] = []
+    for part in sequence.parts:
+        if isinstance(part, str):
+            current.append(part)
+        elif part.crossable is False and current:
+            resolved.append("".join(current))
+            current = []
+    if current:
+        resolved.append("".join(current))
+    return tuple(resolved)
+
+
+def canonical_runs(text: str) -> Iterator[str]:
+    """Yield uninterrupted A/C/G/T runs, splitting at ignored IUPAC symbols."""
+
+    start = 0
+    for index, symbol in enumerate(text):
+        if symbol not in "ACGT":
+            if start < index:
+                yield text[start:index]
+            start = index + 1
+    if start < len(text):
+        yield text[start:]
+
+
+def iter_kmers(
+    sequence: DNASequence,
+    *,
+    k: int,
+    overlapping: bool,
+    cross_gaps: bool,
+) -> Iterator[str]:
+    """Yield valid canonical k-mers without joining ignored ambiguity."""
+
+    validate_positive_int(k, "k")
+    validate_bool(overlapping, "overlapping")
+    step = 1 if overlapping else k
+    for fragment in fragments(sequence, cross_gaps=cross_gaps):
+        for run in canonical_runs(fragment):
+            for start in range(0, len(run) - k + 1, step):
+                yield run[start : start + k]
+
+
+@dataclass(frozen=True)
+class SymbolView:
+    """Flattened symbols with coordinate and gap-segment information."""
+
+    text: str
+    coordinate_positions: tuple[int | None, ...]
+    segment_ids: tuple[int, ...]
+    crossable_segment_ids: tuple[int, ...]
+    unknown_gap_boundaries: frozenset[int]
+
+
+def symbol_view(sequence: DNASequence) -> SymbolView:
+    """Build a symbol-indexed view without silently erasing gap boundaries."""
+
+    symbols: list[str] = []
+    coordinate_positions: list[int | None] = []
+    segment_ids: list[int] = []
+    crossable_segment_ids: list[int] = []
+    unknown_gap_boundaries: set[int] = set()
+    coordinate: int | None = 0
+    segment = 0
+    crossable_segment = 0
+    for part in sequence.parts:
+        if isinstance(part, str):
+            for symbol in part:
+                symbols.append(symbol)
+                coordinate_positions.append(coordinate)
+                segment_ids.append(segment)
+                crossable_segment_ids.append(crossable_segment)
+                if coordinate is not None:
+                    coordinate += 1
+        else:
+            segment += 1
+            if part.crossable is False:
+                crossable_segment += 1
+            if part.length is None:
+                unknown_gap_boundaries.add(segment)
+                coordinate = None
+            elif coordinate is not None:
+                coordinate += part.length
+    return SymbolView(
+        text="".join(symbols),
+        coordinate_positions=tuple(coordinate_positions),
+        segment_ids=tuple(segment_ids),
+        crossable_segment_ids=tuple(crossable_segment_ids),
+        unknown_gap_boundaries=frozenset(unknown_gap_boundaries),
+    )
+
+
+__all__ = ["DescriptorAmbiguityPolicy", "SequenceInput"]