dnakit 0.1.0.dev0__py3-none-any.whl

dnakit/ops/translation.py

@@ -0,0 +1,257 @@
+"""Deterministic transcription and genetic-code translation."""
+
+from __future__ import annotations
+
+from typing import Literal, TypeAlias
+
+from dnakit.core import DNASequence
+from dnakit.exceptions import ConfigurationError, InvalidAlphabetError, UnsupportedGapOperationError
+from dnakit.ops._common import require_sequence
+
+StrandPolicy: TypeAlias = Literal["forward", "reverse"]
+StopPolicy: TypeAlias = Literal["include", "truncate", "error"]
+UnknownCodonPolicy: TypeAlias = Literal["x", "error"]
+IncompleteCodonPolicy: TypeAlias = Literal["ignore", "error"]
+
+_IUPAC_DNA = frozenset("ACGTRYSWKMBDHVN")
+_IUPAC_RNA = frozenset("ACGURYSWKMBDHVN")
+_DNA_COMPLEMENT = str.maketrans(
+    {
+        "A": "T",
+        "C": "G",
+        "G": "C",
+        "T": "A",
+        "R": "Y",
+        "Y": "R",
+        "S": "S",
+        "W": "W",
+        "K": "M",
+        "M": "K",
+        "B": "V",
+        "D": "H",
+        "H": "D",
+        "V": "B",
+        "N": "N",
+    }
+)
+
+# NCBI genetic code table 1, represented with DNA codons.
+_TABLE_1 = {
+    "TTT": "F",
+    "TTC": "F",
+    "TTA": "L",
+    "TTG": "L",
+    "TCT": "S",
+    "TCC": "S",
+    "TCA": "S",
+    "TCG": "S",
+    "TAT": "Y",
+    "TAC": "Y",
+    "TAA": "*",
+    "TAG": "*",
+    "TGT": "C",
+    "TGC": "C",
+    "TGA": "*",
+    "TGG": "W",
+    "CTT": "L",
+    "CTC": "L",
+    "CTA": "L",
+    "CTG": "L",
+    "CCT": "P",
+    "CCC": "P",
+    "CCA": "P",
+    "CCG": "P",
+    "CAT": "H",
+    "CAC": "H",
+    "CAA": "Q",
+    "CAG": "Q",
+    "CGT": "R",
+    "CGC": "R",
+    "CGA": "R",
+    "CGG": "R",
+    "ATT": "I",
+    "ATC": "I",
+    "ATA": "I",
+    "ATG": "M",
+    "ACT": "T",
+    "ACC": "T",
+    "ACA": "T",
+    "ACG": "T",
+    "AAT": "N",
+    "AAC": "N",
+    "AAA": "K",
+    "AAG": "K",
+    "AGT": "S",
+    "AGC": "S",
+    "AGA": "R",
+    "AGG": "R",
+    "GTT": "V",
+    "GTC": "V",
+    "GTA": "V",
+    "GTG": "V",
+    "GCT": "A",
+    "GCC": "A",
+    "GCA": "A",
+    "GCG": "A",
+    "GAT": "D",
+    "GAC": "D",
+    "GAA": "E",
+    "GAG": "E",
+    "GGT": "G",
+    "GGC": "G",
+    "GGA": "G",
+    "GGG": "G",
+}
+
+
+def _coerce_strand(strand: StrandPolicy) -> StrandPolicy:
+    if strand not in ("forward", "reverse"):
+        raise ConfigurationError(
+            "strand must be 'forward' or 'reverse'.",
+            code="INVALID_STRAND_POLICY",
+            context={"strand": strand},
+        )
+    return strand
+
+
+def _ungapped_symbols(sequence: DNASequence, *, operation: str) -> str:
+    resolved = require_sequence(sequence)
+    if resolved.is_gapped:
+        raise UnsupportedGapOperationError(
+            f"{operation} does not silently omit Gap objects.",
+            code="UNSUPPORTED_GAPPED_OPERATION",
+            context={"operation": operation},
+            hint="Translate or transcribe each nucleotide fragment separately.",
+        )
+    return resolved.symbols
+
+
+def transcribe(sequence: DNASequence, *, strand: StrandPolicy = "forward") -> str:
+    """Transcribe DNA to RNA on the selected strand.
+
+    The return value is uppercase RNA text.  Explicit gaps are rejected rather
+    than silently removed.  ``strand='reverse'`` transcribes the reverse
+    complement of the supplied DNA representation.
+    """
+
+    symbols = _ungapped_symbols(sequence, operation="transcribe")
+    if _coerce_strand(strand) == "reverse":
+        symbols = symbols.translate(_DNA_COMPLEMENT)[::-1]
+    return symbols.replace("T", "U")
+
+
+def _coerce_nucleic_text(sequence: DNASequence | str) -> str:
+    if isinstance(sequence, DNASequence):
+        return _ungapped_symbols(sequence, operation="translate")
+    if not isinstance(sequence, str):
+        raise InvalidAlphabetError(
+            "Translation input must be DNASequence or uppercase DNA/RNA text.",
+            context={"type": type(sequence).__name__},
+        )
+    symbols = set(sequence)
+    if "T" in symbols and "U" in symbols:
+        raise InvalidAlphabetError(
+            "Translation input cannot mix thymine and uracil.",
+            code="MIXED_NUCLEIC_ACID_ALPHABET",
+        )
+    allowed = _IUPAC_RNA if "U" in symbols else _IUPAC_DNA
+    invalid = sorted(symbols - allowed)
+    if invalid:
+        raise InvalidAlphabetError(
+            "Translation input contains invalid or non-normalized symbols.",
+            context={"invalid_symbols": invalid},
+            hint="Uppercase and clean raw input before translation.",
+        )
+    return sequence.replace("U", "T")
+
+
+def translate(
+    sequence: DNASequence | str,
+    *,
+    frame: int = 0,
+    table: int = 1,
+    strand: StrandPolicy = "forward",
+    stop_policy: StopPolicy = "include",
+    unknown_policy: UnknownCodonPolicy = "x",
+    incomplete_policy: IncompleteCodonPolicy = "ignore",
+) -> str:
+    """Translate DNA or RNA using NCBI genetic code table 1.
+
+    Coordinates use a zero-based frame (0, 1, or 2).  Ambiguous codons become
+    ``X`` or raise according to ``unknown_policy``.  Stop codons are included as
+    ``*``, truncate translation, or raise according to ``stop_policy``.  A
+    trailing partial codon is ignored or rejected according to
+    ``incomplete_policy``.
+    """
+
+    if isinstance(frame, bool) or not isinstance(frame, int) or frame not in (0, 1, 2):
+        raise ConfigurationError(
+            "frame must be one of 0, 1, or 2.",
+            code="INVALID_READING_FRAME",
+            context={"frame": frame},
+        )
+    if isinstance(table, bool) or not isinstance(table, int) or table != 1:
+        raise ConfigurationError(
+            "Only NCBI genetic code table 1 is available in the MVP.",
+            code="UNSUPPORTED_GENETIC_CODE",
+            context={"table": table},
+        )
+    _coerce_strand(strand)
+    if stop_policy not in ("include", "truncate", "error"):
+        raise ConfigurationError(
+            "stop_policy must be 'include', 'truncate', or 'error'.",
+            code="INVALID_STOP_POLICY",
+            context={"stop_policy": stop_policy},
+        )
+    if unknown_policy not in ("x", "error"):
+        raise ConfigurationError(
+            "unknown_policy must be 'x' or 'error'.",
+            code="INVALID_UNKNOWN_CODON_POLICY",
+            context={"unknown_policy": unknown_policy},
+        )
+    if incomplete_policy not in ("ignore", "error"):
+        raise ConfigurationError(
+            "incomplete_policy must be 'ignore' or 'error'.",
+            code="INVALID_INCOMPLETE_CODON_POLICY",
+            context={"incomplete_policy": incomplete_policy},
+        )
+
+    dna = _coerce_nucleic_text(sequence)
+    if strand == "reverse":
+        dna = dna.translate(_DNA_COMPLEMENT)[::-1]
+    coding = dna[frame:]
+    remainder = len(coding) % 3
+    if remainder and incomplete_policy == "error":
+        raise InvalidAlphabetError(
+            "Translation input has a trailing incomplete codon.",
+            code="INCOMPLETE_CODON",
+            context={"frame": frame, "trailing_symbols": remainder},
+        )
+
+    protein: list[str] = []
+    coding_end = len(coding) - remainder
+    for offset in range(0, coding_end, 3):
+        codon = coding[offset : offset + 3]
+        amino_acid = _TABLE_1.get(codon)
+        if amino_acid is None:
+            if unknown_policy == "error":
+                raise InvalidAlphabetError(
+                    "Ambiguous codon cannot be translated under unknown_policy='error'.",
+                    code="AMBIGUOUS_CODON",
+                    context={"codon": codon, "codon_index": offset // 3},
+                )
+            amino_acid = "X"
+        if amino_acid == "*":
+            if stop_policy == "truncate":
+                break
+            if stop_policy == "error":
+                raise InvalidAlphabetError(
+                    "Stop codon encountered under stop_policy='error'.",
+                    code="STOP_CODON",
+                    context={"codon": codon, "codon_index": offset // 3},
+                )
+        protein.append(amino_acid)
+    return "".join(protein)
+
+
+__all__ = ["transcribe", "translate"]

dnakit/patterns/__init__.py

@@ -0,0 +1,81 @@
+"""Deterministic sequence-pattern annotation APIs."""
+
+from dnakit.patterns.coding import scan_codon_sites, scan_orfs
+from dnakit.patterns.crispr import (
+    BUILTIN_PAM_RULES,
+    PAM_CATALOG_VERSION,
+    PAMRule,
+    scan_pam_candidates,
+)
+from dnakit.patterns.motif import (
+    PROMOTER_CATALOG_VERSION,
+    PROMOTER_MOTIFS,
+    PWM,
+    scan_motif,
+    scan_promoter_motifs,
+    scan_pwm,
+    scan_tf_pwm,
+)
+from dnakit.patterns.regions import find_cpg_islands, find_low_complexity_regions
+from dnakit.patterns.repeats import (
+    find_inverted_repeats,
+    find_microsatellites,
+    find_reverse_complement_palindromes,
+    find_tandem_repeats,
+)
+from dnakit.patterns.restriction import (
+    BUILTIN_RESTRICTION_ENZYMES,
+    RESTRICTION_CATALOG_VERSION,
+    RestrictionEnzyme,
+    scan_restriction_sites,
+)
+from dnakit.patterns.results import (
+    CodonSite,
+    GuideCandidate,
+    InvertedRepeatHit,
+    LowComplexityResult,
+    MotifHit,
+    ORFHit,
+    PalindromeHit,
+    PatternResult,
+    RegionHit,
+    RestrictionSiteHit,
+    TandemRepeatHit,
+)
+
+__all__ = [
+    "BUILTIN_PAM_RULES",
+    "BUILTIN_RESTRICTION_ENZYMES",
+    "PAM_CATALOG_VERSION",
+    "PROMOTER_CATALOG_VERSION",
+    "PROMOTER_MOTIFS",
+    "PWM",
+    "RESTRICTION_CATALOG_VERSION",
+    "CodonSite",
+    "GuideCandidate",
+    "InvertedRepeatHit",
+    "LowComplexityResult",
+    "MotifHit",
+    "ORFHit",
+    "PAMRule",
+    "PalindromeHit",
+    "PatternResult",
+    "RegionHit",
+    "RestrictionEnzyme",
+    "RestrictionSiteHit",
+    "TandemRepeatHit",
+    "find_cpg_islands",
+    "find_inverted_repeats",
+    "find_low_complexity_regions",
+    "find_microsatellites",
+    "find_reverse_complement_palindromes",
+    "find_tandem_repeats",
+    "scan_codon_sites",
+    "scan_motif",
+    "scan_orfs",
+    "scan_pam_candidates",
+    "scan_promoter_motifs",
+    "scan_pwm",
+    "scan_restriction_sites",
+    "scan_tf_pwm",
+]

dnakit/patterns/_shared.py

@@ -0,0 +1,282 @@
+"""Shared bounded traversal and coordinate helpers for pattern analyses."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from typing import TypeAlias
+
+from dnakit.core import (
+    DNA,
+    CompoundLocation,
+    DNARecord,
+    DNASequence,
+    ExecutionMode,
+    ImplementationInfo,
+    ImplementationLabel,
+    Interval,
+    Issue,
+    IssueSeverity,
+    Location,
+    OriginClass,
+    Provenance,
+    ReferenceInfo,
+    Strand,
+    UnresolvedLocation,
+)
+from dnakit.core._json import FrozenDict, freeze_mapping
+from dnakit.core.facade import resolve_single_dna
+from dnakit.core.gap import Gap
+from dnakit.exceptions import ConfigurationError, SequenceError
+from dnakit.patterns.results import PatternResult
+
+SequenceInput: TypeAlias = DNA | DNASequence | DNARecord
+
+IUPAC_BASES: Mapping[str, frozenset[str]] = {
+    "A": frozenset("A"),
+    "C": frozenset("C"),
+    "G": frozenset("G"),
+    "T": frozenset("T"),
+    "R": frozenset("AG"),
+    "Y": frozenset("CT"),
+    "S": frozenset("CG"),
+    "W": frozenset("AT"),
+    "K": frozenset("GT"),
+    "M": frozenset("AC"),
+    "B": frozenset("CGT"),
+    "D": frozenset("AGT"),
+    "H": frozenset("ACT"),
+    "V": frozenset("ACG"),
+    "N": frozenset("ACGT"),
+}
+
+
+@dataclass(frozen=True)
+class Segment:
+    text: str
+    symbol_start: int
+    coordinate_start: int | None
+
+
+def resolve_sequence(value: SequenceInput) -> tuple[DNASequence, str | None]:
+    if isinstance(value, (DNA, DNARecord, DNASequence)):
+        sequence, record = resolve_single_dna(value)
+        return sequence, None if record is None else record.id
+    raise ConfigurationError(
+        "Pattern input must be a DNASequence or DNARecord.",
+        context={"input_type": type(value).__name__},
+    )
+
+
+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 validate_non_negative_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 non-negative integer.", context={name: value})
+
+
+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 segments(sequence: DNASequence) -> tuple[Segment, ...]:
+    """Split at every explicit Gap and retain all resolvable coordinates."""
+
+    resolved: list[Segment] = []
+    symbol_start = 0
+    coordinate: int | None = 0
+    for part in sequence.parts:
+        if isinstance(part, str):
+            if part:
+                resolved.append(Segment(part, symbol_start, coordinate))
+                symbol_start += len(part)
+                if coordinate is not None:
+                    coordinate += len(part)
+        else:
+            if part.length is None:
+                coordinate = None
+            elif coordinate is not None:
+                coordinate += part.length
+    return tuple(resolved)
+
+
+def _split_location(start: int, length: int, total: int) -> Location:
+    if length < 0 or length > total:
+        raise ConfigurationError(
+            "A circular match length must be between zero and sequence length."
+        )
+    end = start + length
+    if end <= total:
+        return Interval(start, end)
+    return CompoundLocation((Interval(start, total), Interval(0, end - total)))
+
+
+def segment_location(
+    segment: Segment,
+    local_start: int,
+    local_end: int,
+) -> tuple[Location, Location]:
+    """Map one non-wrapping segment-local interval to symbol and genomic coordinates."""
+
+    symbol_location = Interval(
+        segment.symbol_start + local_start,
+        segment.symbol_start + local_end,
+    )
+    if segment.coordinate_start is None:
+        coordinate_location: Location = UnresolvedLocation(
+            "unknown-length gap precedes this pattern hit",
+            (symbol_location,),
+        )
+    else:
+        coordinate_location = Interval(
+            segment.coordinate_start + local_start,
+            segment.coordinate_start + local_end,
+        )
+    return symbol_location, coordinate_location
+
+
+def circular_location(start: int, length: int, total: int) -> tuple[Location, Location, bool]:
+    start %= total
+    location = _split_location(start, length, total)
+    return location, location, isinstance(location, CompoundLocation)
+
+
+def reverse_complement_text(text: str) -> str:
+    return DNASequence(text, alphabet="iupac").reverse_complement().symbols
+
+
+def iupac_compatible(left: str, right: str) -> bool:
+    return bool(IUPAC_BASES[left] & IUPAC_BASES[right])
+
+
+def validate_iupac_text(value: str, name: str, *, allow_empty: bool = False) -> str:
+    if not isinstance(value, str):
+        raise ConfigurationError(f"{name} must be a string.")
+    resolved = value.upper()
+    if not resolved and not allow_empty:
+        raise ConfigurationError(f"{name} must be non-empty.")
+    invalid = sorted(set(resolved) - set(IUPAC_BASES))
+    if invalid:
+        raise ConfigurationError(
+            f"{name} contains symbols outside the DNA IUPAC alphabet.",
+            context={"invalid_symbols": invalid},
+        )
+    return resolved
+
+
+def require_ungapped_circular(sequence: DNASequence, operation: str) -> None:
+    if sequence.topology.value == "circular" and sequence.is_gapped:
+        raise SequenceError(
+            f"{operation} cannot resolve a circular origin across explicit gaps.",
+            code="GAPPED_CIRCULAR_PATTERN_UNSUPPORTED",
+        )
+
+
+def require_linear(sequence: DNASequence, operation: str) -> None:
+    if sequence.topology.value == "circular":
+        raise SequenceError(
+            f"{operation} currently requires linear topology.",
+            code="CIRCULAR_PATTERN_UNSUPPORTED",
+            hint="Linearize at a documented origin before running this analysis.",
+        )
+
+
+def pattern_provenance(
+    *,
+    reimplementation: bool,
+    reference_name: str | None = None,
+    reference_version: str | None = None,
+) -> Provenance:
+    return Provenance(
+        implementation=ImplementationInfo(
+            label=(
+                ImplementationLabel.REIMPLEMENTATION
+                if reimplementation
+                else ImplementationLabel.NATIVE
+            ),
+            execution_mode=ExecutionMode.INTERNAL,
+            origin_class=(
+                OriginClass.PUBLISHED_ALGORITHM if reimplementation else OriginClass.DNAKIT
+            ),
+        ),
+        reference=(
+            None
+            if reference_name is None
+            else ReferenceInfo(reference_name, version=reference_version)
+        ),
+    )
+
+
+def build_result(
+    sequence: DNASequence,
+    sequence_id: str | None,
+    *,
+    name: str,
+    method: str,
+    algorithm_version: str,
+    parameters: Mapping[str, object],
+    hits: Iterable[object],
+    max_matches: int,
+    truncated: bool,
+    provenance: Provenance,
+    issues: Iterable[Issue] = (),
+) -> PatternResult[object]:
+    gap_count = sum(isinstance(part, Gap) for part in sequence.parts)
+    unknown_gap_count = sum(
+        isinstance(part, Gap) and part.length is None for part in sequence.parts
+    )
+    resolved_issues = list(issues)
+    if truncated:
+        resolved_issues.append(
+            Issue(
+                "PATTERN_MATCH_LIMIT_REACHED",
+                IssueSeverity.WARNING,
+                "Pattern hits were truncated at max_matches.",
+                details={"max_matches": max_matches},
+            )
+        )
+    return PatternResult(
+        name=name,
+        method=method,
+        algorithm_version=algorithm_version,
+        sequence_id=sequence_id,
+        parameters=freeze_mapping(parameters),
+        hits=tuple(hits),
+        inspected_symbol_count=sequence.symbol_length,
+        gap_count=gap_count,
+        unknown_gap_count=unknown_gap_count,
+        max_matches=max_matches,
+        truncated=truncated,
+        coordinate_system="0-based-half-open",
+        gap_policy="split-no-crossing",
+        topology=sequence.topology.value,
+        provenance=provenance,
+        issues=tuple(resolved_issues),
+    )
+
+
+def frozen(values: Mapping[str, object]) -> FrozenDict:
+    return freeze_mapping(values)
+
+
+def coerce_strands(value: Strand | str) -> tuple[Strand, ...]:
+    try:
+        strand = value if isinstance(value, Strand) else Strand(value)
+    except (TypeError, ValueError) as exc:
+        raise ConfigurationError(
+            "Unknown strand selection.",
+            context={"strand": value},
+            hint="Choose 'forward', 'reverse', or 'both'.",
+        ) from exc
+    if strand is Strand.BOTH:
+        return (Strand.FORWARD, Strand.REVERSE)
+    if strand not in (Strand.FORWARD, Strand.REVERSE):
+        raise ConfigurationError("Pattern strand must be forward, reverse, or both.")
+    return (strand,)
+
+
+__all__ = ["IUPAC_BASES", "SequenceInput"]