dnakit 0.1.0.dev0__py3-none-any.whl

dnakit/evaluation/synthesis.py

@@ -0,0 +1,249 @@
+"""Rule-based synthesis-risk screening with no experimental success claim."""
+
+from __future__ import annotations
+
+import hashlib
+import math
+
+from dnakit.core import IssueSeverity, Topology
+from dnakit.core._json import FrozenDict, to_json_compatible
+from dnakit.descriptors import gc_at_content, homopolymer_runs, window_descriptors
+from dnakit.exceptions import ConfigurationError, UnsupportedGapOperationError
+from dnakit.patterns import find_inverted_repeats, find_tandem_repeats
+
+from ._shared import EvaluationInput, aggregate_numeric, as_float, issue, materialize_input, report
+from .config import SynthesisRiskConfig
+from .results import EvaluationEntry, EvaluationReport
+
+_DISCLAIMER = (
+    "DNAKit transparent sequence-rule screen only; this score is not a vendor acceptance "
+    "criterion, thermodynamic structure prediction, or experimental synthesis-success probability."
+)
+
+
+def _window_count(
+    sequence_length: int,
+    *,
+    window_size: int,
+    step: int,
+    include_partial: bool,
+) -> int:
+    """Return the exact number of rows produced by ``window_descriptors``."""
+
+    last_start = sequence_length if include_partial else sequence_length - window_size + 1
+    stop = max(0, last_start)
+    return (stop + step - 1) // step if stop else 0
+
+
+def _risk_entry(item: object, index: int, config: SynthesisRiskConfig) -> EvaluationEntry:
+    from ._shared import InputItem
+
+    if not isinstance(item, InputItem):
+        raise TypeError("Internal synthesis input must be InputItem.")
+    sequence = item.sequence
+    if sequence.is_gapped:
+        raise UnsupportedGapOperationError(
+            "Synthesis-risk rules require gap-free input.",
+            code="SYNTHESIS_RISK_GAP_UNSUPPORTED",
+            context={"subject_id": item.subject_id},
+        )
+    if sequence.topology is Topology.CIRCULAR:
+        raise ConfigurationError(
+            "Synthesis-risk rules currently require linear topology.",
+            code="SYNTHESIS_RISK_LINEAR_REQUIRED",
+            context={"subject_id": item.subject_id},
+        )
+    canonical_symbols = sequence.symbols
+    canonical_sequence_sha256 = hashlib.sha256(canonical_symbols.encode("ascii")).hexdigest()
+    window_count = _window_count(
+        sequence.symbol_length,
+        window_size=config.window_size,
+        step=config.window_step,
+        include_partial=True,
+    )
+    if window_count > config.max_windows_per_sequence:
+        raise ConfigurationError(
+            "Synthesis-risk calculation exceeds max_windows_per_sequence.",
+            code="SYNTHESIS_RISK_WINDOW_LIMIT",
+            context={
+                "window_count": window_count,
+                "max_windows_per_sequence": config.max_windows_per_sequence,
+                "sequence_length": sequence.symbol_length,
+                "window_size": config.window_size,
+                "window_step": config.window_step,
+                "include_partial": True,
+            },
+        )
+    global_gc = gc_at_content(sequence, ambiguity_policy="ignore").gc_fraction
+    windows = window_descriptors(
+        sequence,
+        ("gc",),
+        window_size=config.window_size,
+        step=config.window_step,
+        include_partial=True,
+        ambiguity_policy="ignore",
+    )
+    risky_windows = tuple(
+        {
+            "start": window.symbol_start,
+            "end": window.symbol_end,
+            "gc_fraction": window.values["gc_fraction"],
+        }
+        for window in windows.windows
+        if isinstance(window.values["gc_fraction"], (int, float))
+        and not config.local_gc_min <= float(window.values["gc_fraction"]) <= config.local_gc_max
+    )
+    homopolymer = homopolymer_runs(
+        sequence,
+        min_run_length=config.homopolymer_threshold,
+        ambiguity_policy="ignore",
+    )
+    tandem = find_tandem_repeats(
+        sequence,
+        min_unit_length=config.tandem_min_unit,
+        max_unit_length=config.tandem_max_unit,
+        min_repeats=config.tandem_min_repeats,
+        max_comparisons=config.max_pattern_comparisons_per_sequence,
+        max_comparison_cells=config.max_pattern_comparisons_per_sequence,
+        max_matches=config.max_matches_per_sequence,
+    )
+    inverted = find_inverted_repeats(
+        sequence,
+        min_arm_length=config.inverted_min_arm,
+        max_arm_length=config.inverted_max_arm,
+        max_loop_length=config.inverted_max_loop,
+        max_comparisons=config.max_pattern_comparisons_per_sequence,
+        max_comparison_cells=config.max_pattern_comparisons_per_sequence,
+        max_matches=config.max_matches_per_sequence,
+    )
+    components = {
+        "global_gc": float(
+            global_gc is None or not config.global_gc_min <= global_gc <= config.global_gc_max
+        ),
+        "local_gc": min(1.0, len(risky_windows) / max(1, len(windows.windows))),
+        "homopolymer": min(
+            1.0,
+            max(0, homopolymer.longest_length - config.homopolymer_threshold + 1)
+            / config.homopolymer_threshold,
+        ),
+        "tandem_repeat": min(1.0, len(tandem.hits) / 5.0),
+        "inverted_repeat_structure_proxy": min(1.0, len(inverted.hits) / 5.0),
+    }
+    score = math.fsum(components.values()) / len(components)
+    findings = []
+    if any(value > 0 for value in components.values()):
+        findings.append(
+            issue(
+                "EVAL_SYNTHESIS_RULE_FINDING",
+                IssueSeverity.WARNING,
+                "One or more transparent sequence-risk rules were triggered.",
+                triggered=tuple(name for name, value in components.items() if value > 0),
+            )
+        )
+    if sequence.ambiguity_count:
+        findings.append(
+            issue(
+                "EVAL_SYNTHESIS_AMBIGUITY_IGNORED",
+                IssueSeverity.WARNING,
+                "Ambiguous IUPAC symbols were excluded from composition-based calculations.",
+                ambiguity_count=sequence.ambiguity_count,
+            )
+        )
+    return EvaluationEntry(
+        item.subject_id,
+        index,
+        FrozenDict(
+            {
+                "score": score,
+                "risk_score": score,
+                "risk_level": "high" if score >= 0.5 else ("medium" if score >= 0.2 else "low"),
+                "canonical_sequence_sha256": canonical_sequence_sha256,
+                "canonical_sequence_length": sequence.symbol_length,
+                "components": components,
+                "global_gc_fraction": global_gc,
+                "risky_gc_windows": risky_windows,
+                "window_count": window_count,
+                "longest_homopolymer": homopolymer.longest_length,
+                "homopolymer_runs": to_json_compatible(homopolymer.runs),
+                "tandem_repeat_hits": to_json_compatible(tandem.hits),
+                "inverted_repeat_hits": to_json_compatible(inverted.hits),
+                "tandem_scan_truncated": tandem.truncated,
+                "inverted_repeat_scan_truncated": inverted.truncated,
+                "tandem_comparisons": tandem.parameters["comparisons"],
+                "inverted_repeat_comparisons": inverted.parameters["comparisons"],
+                "disclaimer": _DISCLAIMER,
+            }
+        ),
+        tuple(findings),
+    )
+
+
+def evaluate_synthesis_risk(
+    value: EvaluationInput,
+    *,
+    config: SynthesisRiskConfig | None = None,
+) -> EvaluationReport:
+    """Screen transparent GC, run, repeat, and inverted-repeat proxy rules."""
+
+    resolved = SynthesisRiskConfig() if config is None else config
+    if not isinstance(resolved, SynthesisRiskConfig):
+        raise TypeError("config must be SynthesisRiskConfig or None.")
+    items = materialize_input(value, limits=resolved.limits)
+    entries = tuple(_risk_entry(item, index, resolved) for index, item in enumerate(items))
+    return report(
+        name="synthesis_risk",
+        method="equal-weight-transparent-sequence-rule-screen",
+        version="eval-synthesis-risk-v2",
+        parameters={
+            "global_gc_range": (resolved.global_gc_min, resolved.global_gc_max),
+            "local_gc_range": (resolved.local_gc_min, resolved.local_gc_max),
+            "window_size": resolved.window_size,
+            "window_step": resolved.window_step,
+            "partial_windows": True,
+            "homopolymer_threshold": resolved.homopolymer_threshold,
+            "tandem": {
+                "min_unit": resolved.tandem_min_unit,
+                "max_unit": resolved.tandem_max_unit,
+                "min_repeats": resolved.tandem_min_repeats,
+            },
+            "inverted_repeat": {
+                "min_arm": resolved.inverted_min_arm,
+                "max_arm": resolved.inverted_max_arm,
+                "max_loop": resolved.inverted_max_loop,
+            },
+            "aggregation": "arithmetic mean of five component risk values",
+            "structure_method": "inverted-repeat count proxy; no folding backend",
+            "sequence_binding": {
+                "digest": "SHA-256",
+                "payload": "DNASequence.symbols encoded as ASCII",
+                "length": "DNASequence.symbol_length",
+            },
+            "vendor_rule_set": None,
+            "disclaimer": _DISCLAIMER,
+            "resource_limits": {
+                "max_windows_per_sequence": resolved.max_windows_per_sequence,
+                "max_pattern_comparisons_per_sequence": (
+                    resolved.max_pattern_comparisons_per_sequence
+                ),
+                "max_matches_per_sequence": resolved.max_matches_per_sequence,
+                "evaluation_limits": resolved.limits,
+            },
+        },
+        metrics={
+            "score": (
+                math.fsum(as_float(entry.metrics, "score") for entry in entries) / len(entries)
+                if entries
+                else None
+            ),
+            "record_count": len(entries),
+            "risk_score_summary": aggregate_numeric(entries, "risk_score"),
+            "high_risk_count": sum(entry.metrics["risk_level"] == "high" for entry in entries),
+            "medium_risk_count": sum(entry.metrics["risk_level"] == "medium" for entry in entries),
+            "low_risk_count": sum(entry.metrics["risk_level"] == "low" for entry in entries),
+            "disclaimer": _DISCLAIMER,
+        },
+        entries=entries,
+    )
+
+
+__all__ = ["evaluate_synthesis_risk"]

dnakit/exceptions.py

@@ -0,0 +1,189 @@
+"""DNAKit exception hierarchy.
+
+Exceptions are reserved for violated object invariants, invalid configuration,
+and failed infrastructure.  Recoverable sequence quality findings belong in an
+``Issue``-based report instead.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from types import MappingProxyType
+
+
+class DNAKitError(Exception):
+    """Base class carrying a stable code and actionable diagnostic context."""
+
+    default_code = "DNAKIT_ERROR"
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str | None = None,
+        context: Mapping[str, object] | None = None,
+        hint: str | None = None,
+    ) -> None:
+        if not isinstance(message, str) or not message.strip():
+            raise ValueError("An exception message must be a non-empty string.")
+        resolved_code = self.default_code if code is None else code
+        if not isinstance(resolved_code, str) or not resolved_code.strip():
+            raise ValueError("An exception code must be a non-empty string.")
+        if hint is not None and (not isinstance(hint, str) or not hint.strip()):
+            raise ValueError("An exception hint must be None or a non-empty string.")
+
+        self.message = message
+        self.code = resolved_code
+        self.context = MappingProxyType(dict(context or {}))
+        self.hint = hint
+        super().__init__(message)
+
+    @property
+    def error_code(self) -> str:
+        """Alias retained for callers that prefer the explicit name."""
+
+        return self.code
+
+    def __str__(self) -> str:
+        text = f"[{self.code}] {self.message}"
+        if self.hint is not None:
+            text += f" Hint: {self.hint}"
+        return text
+
+
+class SequenceError(DNAKitError):
+    """Base class for invalid sequence objects or unsupported sequence states."""
+
+    default_code = "SEQUENCE_ERROR"
+
+
+class InvalidAlphabetError(SequenceError):
+    """Raised when symbols do not satisfy the declared DNA alphabet."""
+
+    default_code = "INVALID_ALPHABET"
+
+
+class UnknownLengthError(SequenceError):
+    """Raised when an exact length is requested across an unknown-length gap."""
+
+    default_code = "UNKNOWN_LENGTH"
+
+
+class UnsupportedGapOperationError(SequenceError):
+    """Raised when an operation cannot safely process sequence gaps."""
+
+    default_code = "UNSUPPORTED_GAP_OPERATION"
+
+
+class CoordinateError(DNAKitError):
+    """Raised for invalid coordinates or impossible coordinate conversions."""
+
+    default_code = "COORDINATE_ERROR"
+
+
+class FeatureError(DNAKitError):
+    """Raised when a feature violates its structural invariants."""
+
+    default_code = "FEATURE_ERROR"
+
+
+class DuplicateIDError(DNAKitError):
+    """Raised when an operation requires unique record identifiers."""
+
+    default_code = "DUPLICATE_ID"
+
+
+class InputFormatError(DNAKitError):
+    """Raised when serialized input does not match its declared format."""
+
+    default_code = "INPUT_FORMAT_ERROR"
+
+
+class RecordSourceClosedError(DNAKitError):
+    """Raised when consuming a manually closed record source."""
+
+    default_code = "RECORD_SOURCE_CLOSED"
+
+
+class ConfigurationError(DNAKitError):
+    """Raised for invalid or internally inconsistent configuration."""
+
+    default_code = "CONFIGURATION_ERROR"
+
+
+class CacheError(DNAKitError):
+    """Raised for cache integrity or persistence failures."""
+
+    default_code = "CACHE_ERROR"
+
+
+class BackendError(DNAKitError):
+    """Base class for optional backend failures."""
+
+    default_code = "BACKEND_ERROR"
+
+
+class BackendUnavailableError(BackendError):
+    """Raised when a requested optional backend cannot be located."""
+
+    default_code = "BACKEND_UNAVAILABLE"
+
+
+class BackendVersionError(BackendError):
+    """Raised when a backend version is incompatible or unparseable."""
+
+    default_code = "BACKEND_VERSION_ERROR"
+
+
+class BackendTimeoutError(BackendError):
+    """Raised when a backend exceeds its configured timeout."""
+
+    default_code = "BACKEND_TIMEOUT"
+
+
+class BackendExecutionError(BackendError):
+    """Raised when a backend process or library call fails."""
+
+    default_code = "BACKEND_EXECUTION_ERROR"
+
+
+class DownloadError(BackendError):
+    """Raised when an external reference-data download fails."""
+
+    default_code = "DOWNLOAD_ERROR"
+
+
+class QueryError(BackendError):
+    """Raised when a public biological-database query fails."""
+
+    default_code = "QUERY_ERROR"
+
+
+class BatchExecutionError(DNAKitError):
+    """Raised when a batch cannot continue under its error policy."""
+
+    default_code = "BATCH_EXECUTION_ERROR"
+
+
+__all__ = [
+    "BackendError",
+    "BackendExecutionError",
+    "BackendTimeoutError",
+    "BackendUnavailableError",
+    "BackendVersionError",
+    "BatchExecutionError",
+    "CacheError",
+    "ConfigurationError",
+    "CoordinateError",
+    "DNAKitError",
+    "DownloadError",
+    "DuplicateIDError",
+    "FeatureError",
+    "InputFormatError",
+    "InvalidAlphabetError",
+    "QueryError",
+    "RecordSourceClosedError",
+    "SequenceError",
+    "UnknownLengthError",
+    "UnsupportedGapOperationError",
+]

dnakit/fingerprints/__init__.py

@@ -0,0 +1,109 @@
+"""Deterministic dependency-free encodings and fixed-schema fingerprints."""
+
+from dnakit.fingerprints._shared import (
+    FingerprintAmbiguityPolicy,
+    FingerprintRepresentation,
+    GapEncodingPolicy,
+    IntegerAmbiguityPolicy,
+    KmerFingerprintMode,
+    OneHotAmbiguityPolicy,
+    SequenceInput,
+)
+from dnakit.fingerprints.advanced import (
+    AdvancedFingerprintResult,
+    FeaturePreprocessor,
+    ThermodynamicMissingStrategy,
+    ThermodynamicStructureAdapter,
+    coding_fingerprint,
+    fit_preprocessor,
+    gc_spatial_fingerprint,
+    hybrid_fingerprint,
+    motif_fingerprint,
+    multiscale_fingerprint,
+    repeat_fingerprint,
+    restriction_fingerprint,
+    thermodynamic_fingerprint,
+)
+from dnakit.fingerprints.bit import (
+    DEFAULT_HASHED_KMER_BITS,
+    DEFAULT_MAX_PANEL_SIZE,
+    MAX_BIT_FINGERPRINT_DIMENSION,
+    PanelMode,
+    hashed_kmer_fingerprint,
+    panel_fingerprint,
+)
+from dnakit.fingerprints.encoding import (
+    CANONICAL_BASE_ORDER,
+    DEFAULT_MAX_OUTPUT_LENGTH,
+    INTEGER_AMBIGUITY_CODE,
+    INTEGER_GAP_CODE,
+    IUPAC_INTEGER_ORDER,
+    integer_encode,
+    one_hot_encode,
+)
+from dnakit.fingerprints.kmer import DEFAULT_MAX_DIMENSION, kmer, kmer_fingerprint
+from dnakit.fingerprints.results import (
+    BitFingerprintResult,
+    BitFingerprintValues,
+    FingerprintResult,
+    FingerprintValues,
+    IntegerEncodingResult,
+    KmerFingerprintResult,
+    Numeric,
+    OneHotEncodingResult,
+    RepresentationResult,
+    SketchResult,
+)
+from dnakit.fingerprints.sketch import DEFAULT_MAX_SKETCH_HASHES, fracminhash, minhash
+
+__all__ = [
+    "CANONICAL_BASE_ORDER",
+    "DEFAULT_HASHED_KMER_BITS",
+    "DEFAULT_MAX_DIMENSION",
+    "DEFAULT_MAX_OUTPUT_LENGTH",
+    "DEFAULT_MAX_PANEL_SIZE",
+    "DEFAULT_MAX_SKETCH_HASHES",
+    "INTEGER_AMBIGUITY_CODE",
+    "INTEGER_GAP_CODE",
+    "IUPAC_INTEGER_ORDER",
+    "MAX_BIT_FINGERPRINT_DIMENSION",
+    "AdvancedFingerprintResult",
+    "BitFingerprintResult",
+    "BitFingerprintValues",
+    "FeaturePreprocessor",
+    "FingerprintAmbiguityPolicy",
+    "FingerprintRepresentation",
+    "FingerprintResult",
+    "FingerprintValues",
+    "GapEncodingPolicy",
+    "IntegerAmbiguityPolicy",
+    "IntegerEncodingResult",
+    "KmerFingerprintMode",
+    "KmerFingerprintResult",
+    "Numeric",
+    "OneHotAmbiguityPolicy",
+    "OneHotEncodingResult",
+    "PanelMode",
+    "RepresentationResult",
+    "SequenceInput",
+    "SketchResult",
+    "ThermodynamicMissingStrategy",
+    "ThermodynamicStructureAdapter",
+    "coding_fingerprint",
+    "fit_preprocessor",
+    "fracminhash",
+    "gc_spatial_fingerprint",
+    "hashed_kmer_fingerprint",
+    "hybrid_fingerprint",
+    "integer_encode",
+    "kmer",
+    "kmer_fingerprint",
+    "minhash",
+    "motif_fingerprint",
+    "multiscale_fingerprint",
+    "one_hot_encode",
+    "panel_fingerprint",
+    "repeat_fingerprint",
+    "restriction_fingerprint",
+    "thermodynamic_fingerprint",
+]

dnakit/fingerprints/_shared.py

@@ -0,0 +1,116 @@
+"""Shared public policies and validation for native fingerprints."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import TypeAlias, TypeVar
+
+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
+
+SequenceInput: TypeAlias = DNA | DNASequence | DNARecord
+
+
+class GapEncodingPolicy(str, Enum):
+    """Treatment of explicit :class:`~dnakit.core.Gap` parts."""
+
+    ERROR = "error"
+    OMIT = "omit"
+    EXPAND = "expand"
+
+
+class IntegerAmbiguityPolicy(str, Enum):
+    """Treatment of non-canonical IUPAC symbols in integer encoding."""
+
+    ERROR = "error"
+    IUPAC = "iupac"
+    SENTINEL = "sentinel"
+
+
+class OneHotAmbiguityPolicy(str, Enum):
+    """Treatment of non-canonical IUPAC symbols in one-hot encoding."""
+
+    ERROR = "error"
+    FRACTIONAL = "fractional"
+    ZERO = "zero"
+
+
+class FingerprintAmbiguityPolicy(str, Enum):
+    """Treatment of IUPAC symbols in exact k-mer fingerprints."""
+
+    ERROR = "error"
+    IGNORE = "ignore"
+
+
+class KmerFingerprintMode(str, Enum):
+    """Aggregation applied to exact k-mer observations."""
+
+    COUNT = "count"
+    FREQUENCY = "frequency"
+    BINARY = "binary"
+
+
+class FingerprintRepresentation(str, Enum):
+    """Materialized fingerprint storage representation."""
+
+    DENSE = "dense"
+    SPARSE = "sparse"
+
+
+EnumType = TypeVar("EnumType", bound=Enum)
+
+
+def sequence_and_id(value: SequenceInput) -> tuple[DNASequence, str | None]:
+    """Return a sequence and the optional identifier of its source record."""
+
+    if isinstance(value, (DNA, DNARecord, DNASequence)):
+        sequence, record = resolve_single_dna(value)
+        return sequence, None if record is None else record.id
+    raise ConfigurationError(
+        "Fingerprint input must be a DNASequence or DNARecord.",
+        context={"input_type": type(value).__name__},
+    )
+
+
+def coerce_enum(value: EnumType | str, enum_type: type[EnumType], name: str) -> EnumType:
+    """Coerce a string enum value with a stable configuration diagnostic."""
+
+    try:
+        return value if isinstance(value, enum_type) else enum_type(value)
+    except (TypeError, ValueError) as exc:
+        choices = ", ".join(repr(item.value) for item in enum_type)
+        raise ConfigurationError(
+            f"Unknown {name}.",
+            context={name: value},
+            hint=f"Choose one of: {choices}.",
+        ) from exc
+
+
+def validate_bool(value: bool, name: str) -> None:
+    """Reject truthy integers where a real boolean is required."""
+
+    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:
+    """Validate a positive integer while rejecting booleans."""
+
+    if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
+        raise ConfigurationError(
+            f"{name} must be a positive integer.",
+            context={name: value},
+        )
+
+
+__all__ = [
+    "FingerprintAmbiguityPolicy",
+    "FingerprintRepresentation",
+    "GapEncodingPolicy",
+    "IntegerAmbiguityPolicy",
+    "KmerFingerprintMode",
+    "OneHotAmbiguityPolicy",
+    "SequenceInput",
+]