dnakit 0.1.0.dev0__py3-none-any.whl

dnakit/secondary_structure/results.py

@@ -0,0 +1,142 @@
+"""Immutable secondary-structure and ensemble result objects."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, cast
+
+from dnakit.core import BackendInfo, 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 SecondaryBasePair(_SerializableResult):
+    first_global_index: int
+    second_global_index: int
+    first_strand_index: int
+    first_local_index: int
+    second_strand_index: int
+    second_local_index: int
+    bracket_type: str
+    inter_strand: bool
+
+
+@dataclass(frozen=True)
+class SecondaryStem(_SerializableResult):
+    base_pairs: tuple[SecondaryBasePair, ...]
+    length: int
+    inter_strand: bool
+
+
+@dataclass(frozen=True)
+class SecondaryStructureSummary(_SerializableResult):
+    strands_5to3: tuple[str, ...]
+    dot_bracket: str
+    base_pairs: tuple[SecondaryBasePair, ...]
+    stems: tuple[SecondaryStem, ...]
+    structure_type: str
+    base_pair_count: int
+    paired_base_fraction: float
+    stem_lengths: tuple[int, ...]
+    hairpin_count: int
+    hairpin_loop_lengths: tuple[int, ...]
+    max_contiguous_pair_count: int
+    three_prime_window: int
+    three_prime_dimer: bool
+    three_prime_dimer_max_contiguous_pairs: int
+    method: str
+
+
+@dataclass(frozen=True)
+class AccessibilityWindow(_SerializableResult):
+    start: int
+    end: int
+    mean_unpaired_probability: float
+
+
+@dataclass(frozen=True)
+class PairProbabilityResult(_SerializableResult):
+    strands_5to3: tuple[str, ...]
+    pair_probabilities: tuple[tuple[float, ...], ...]
+    pairing_probabilities_by_base: tuple[float, ...]
+    unpaired_probabilities_by_base: tuple[float, ...]
+    accessibility_window_size: int
+    accessibility_windows: tuple[AccessibilityWindow, ...]
+    most_accessible_window_start: int | None
+    method: str
+    applicability: str
+
+
+@dataclass(frozen=True)
+class PredictedSecondaryStructure(_SerializableResult):
+    summary: SecondaryStructureSummary
+    free_energy_kcal_per_mol: float
+    stack_free_energy_kcal_per_mol: float | None
+
+
+@dataclass(frozen=True)
+class NupackComplexResult(_SerializableResult):
+    strands_5to3: tuple[str, ...]
+    material: str
+    temperature_celsius: float
+    monovalent_molar: float
+    magnesium_molar: float
+    ensemble: str
+    partition_function_log: float
+    ensemble_free_energy_kcal_per_mol: float
+    mfe_structures: tuple[PredictedSecondaryStructure, ...]
+    pair_probabilities: PairProbabilityResult
+    suboptimal_structures: tuple[PredictedSecondaryStructure, ...]
+    boltzmann_samples: tuple[str, ...]
+    ensemble_size: int
+    target_structure: SecondaryStructureSummary | None
+    target_structure_probability: float | None
+    target_ensemble_defect: float | None
+    method: str
+    backend: BackendInfo
+    provenance: Provenance
+
+
+@dataclass(frozen=True)
+class ComplexConcentration(_SerializableResult):
+    name: str
+    strand_names: tuple[str, ...]
+    concentration_molar: float
+    is_target: bool
+
+
+@dataclass(frozen=True)
+class NupackTubeResult(_SerializableResult):
+    strand_names: tuple[str, ...]
+    sequences_5to3: tuple[str, ...]
+    input_concentrations_molar: tuple[float, ...]
+    complex_concentrations: tuple[ComplexConcentration, ...]
+    target_complex_name: str
+    target_strand_names: tuple[str, ...]
+    target_complex_concentration_molar: float
+    complex_fraction_denominator_molar: float
+    target_complex_fraction: float
+    non_target_complex_fraction: float
+    fraction_bases_unpaired: float
+    max_complex_size: int
+    method: str
+    backend: BackendInfo
+    provenance: Provenance
+
+
+__all__ = [
+    "AccessibilityWindow",
+    "ComplexConcentration",
+    "NupackComplexResult",
+    "NupackTubeResult",
+    "PairProbabilityResult",
+    "PredictedSecondaryStructure",
+    "SecondaryBasePair",
+    "SecondaryStem",
+    "SecondaryStructureSummary",
+]

dnakit/similarity/__init__.py

@@ -0,0 +1,125 @@
+"""Deterministic native sequence and fingerprint similarity tools."""
+
+from dnakit.similarity.approximate import (
+    DEFAULT_MAX_APPROXIMATE_CELLS,
+    DEFAULT_MAX_APPROXIMATE_MATCHES,
+    DEFAULT_MAX_APPROXIMATE_TARGETS,
+    approximate_search,
+)
+from dnakit.similarity.compare import compare, exact_similarity
+from dnakit.similarity.dashing import (
+    DEFAULT_MAX_DASHING_CAPTURE_BYTES,
+    DEFAULT_MAX_DASHING_INPUT_BYTES,
+    DEFAULT_MAX_DASHING_ITEMS,
+    DEFAULT_MAX_DASHING_OUTPUT_BYTES,
+    DEFAULT_MAX_DASHING_SKETCH_MEMORY_BYTES,
+    DashingAdapter,
+    DashingInput,
+    DashingMode,
+)
+from dnakit.similarity.distance import (
+    DEFAULT_MAX_EDIT_CELLS,
+    edit_distance,
+    hamming_distance,
+    levenshtein_distance,
+)
+from dnakit.similarity.index import (
+    SketchIndex,
+    build_sketch_index,
+    load_sketch_index,
+    nearest_neighbors,
+    save_sketch_index,
+)
+from dnakit.similarity.matrix import (
+    DEFAULT_MAX_MATRIX_ITEMS,
+    pairwise_matrix,
+    similarity_matrix,
+)
+from dnakit.similarity.results import (
+    ApproximateMatch,
+    ApproximateSearchResult,
+    DashingJaccardMatrixResult,
+    DashingNeighborHit,
+    DashingNeighborRow,
+    DashingTopKResult,
+    DistanceResult,
+    EditStep,
+    Mismatch,
+    NearestNeighborHit,
+    NearestNeighborResult,
+    SearchResult,
+    SequenceMatch,
+    SimilarityMatrixResult,
+    SimilarityResult,
+    SketchSimilarityResult,
+)
+from dnakit.similarity.search import (
+    DEFAULT_MAX_SEARCH_MATCHES,
+    DEFAULT_MAX_SEARCH_TARGETS,
+    exact_search,
+    find_subsequence,
+    reverse_complement_search,
+    subsequence_search,
+)
+from dnakit.similarity.sketch import SketchMetric, sketch_similarity
+from dnakit.similarity.vector import (
+    fingerprint_similarity,
+    kmer_similarity,
+    kmer_vector_similarity,
+)
+
+__all__ = [
+    "DEFAULT_MAX_APPROXIMATE_CELLS",
+    "DEFAULT_MAX_APPROXIMATE_MATCHES",
+    "DEFAULT_MAX_APPROXIMATE_TARGETS",
+    "DEFAULT_MAX_DASHING_CAPTURE_BYTES",
+    "DEFAULT_MAX_DASHING_INPUT_BYTES",
+    "DEFAULT_MAX_DASHING_ITEMS",
+    "DEFAULT_MAX_DASHING_OUTPUT_BYTES",
+    "DEFAULT_MAX_DASHING_SKETCH_MEMORY_BYTES",
+    "DEFAULT_MAX_EDIT_CELLS",
+    "DEFAULT_MAX_MATRIX_ITEMS",
+    "DEFAULT_MAX_SEARCH_MATCHES",
+    "DEFAULT_MAX_SEARCH_TARGETS",
+    "ApproximateMatch",
+    "ApproximateSearchResult",
+    "DashingAdapter",
+    "DashingInput",
+    "DashingJaccardMatrixResult",
+    "DashingMode",
+    "DashingNeighborHit",
+    "DashingNeighborRow",
+    "DashingTopKResult",
+    "DistanceResult",
+    "EditStep",
+    "Mismatch",
+    "NearestNeighborHit",
+    "NearestNeighborResult",
+    "SearchResult",
+    "SequenceMatch",
+    "SimilarityMatrixResult",
+    "SimilarityResult",
+    "SketchIndex",
+    "SketchMetric",
+    "SketchSimilarityResult",
+    "approximate_search",
+    "build_sketch_index",
+    "compare",
+    "edit_distance",
+    "exact_search",
+    "exact_similarity",
+    "find_subsequence",
+    "fingerprint_similarity",
+    "hamming_distance",
+    "kmer_similarity",
+    "kmer_vector_similarity",
+    "levenshtein_distance",
+    "load_sketch_index",
+    "nearest_neighbors",
+    "pairwise_matrix",
+    "reverse_complement_search",
+    "save_sketch_index",
+    "similarity_matrix",
+    "sketch_similarity",
+    "subsequence_search",
+]

dnakit/similarity/_shared.py

@@ -0,0 +1,152 @@
+"""Shared input and policy helpers for native similarity functions."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Iterable, Mapping, Sequence
+from typing import TypeAlias
+
+from dnakit.core import DNA, DNARecord, DNASequence, DNASet, Gap
+from dnakit.core.facade import resolve_single_dna
+from dnakit.exceptions import ConfigurationError, UnsupportedGapOperationError
+
+SequenceInput: TypeAlias = DNA | DNASequence | DNARecord
+NumericVector: TypeAlias = Sequence[int | float]
+NamedVector: TypeAlias = Mapping[str, int | float]
+
+
+def sequence_and_id(value: SequenceInput, *, role: str) -> tuple[DNASequence, str | None]:
+    """Resolve a sequence input and reject untyped values consistently."""
+
+    if isinstance(value, (DNA, DNARecord, DNASequence)):
+        sequence, record = resolve_single_dna(value)
+        sequence_id = None if record is None else record.id
+    else:
+        raise ConfigurationError(
+            f"{role} must be DNASequence or DNARecord.",
+            code="INVALID_SIMILARITY_SEQUENCE",
+            context={"role": role, "input_type": type(value).__name__},
+        )
+    reject_gaps(sequence, role=role)
+    return sequence, sequence_id
+
+
+def reject_gaps(sequence: DNASequence, *, role: str) -> None:
+    """Reject every explicit Gap instead of silently omitting it."""
+
+    gaps = tuple(part for part in sequence.parts if isinstance(part, Gap))
+    if gaps:
+        raise UnsupportedGapOperationError(
+            "Native MVP similarity does not accept explicit Gap objects.",
+            code="SIMILARITY_GAP_NOT_ALLOWED",
+            context={
+                "role": role,
+                "gap_count": len(gaps),
+                "unknown_gap_count": sum(gap.length is None for gap in gaps),
+            },
+            hint="Compare gap-free fragments explicitly; gaps are never silently omitted.",
+        )
+
+
+def materialize_targets(
+    targets: object,
+    *,
+    max_targets: int,
+) -> tuple[SequenceInput, ...]:
+    """Materialize at most ``max_targets`` targets without exhausting iterators."""
+
+    resolved: tuple[SequenceInput, ...]
+    if isinstance(targets, DNA):
+        resolved = targets.records[: max_targets + 1]
+    elif isinstance(targets, (DNASequence, DNARecord)):
+        resolved = (targets,)
+    elif isinstance(targets, DNASet):
+        resolved = targets.records[: max_targets + 1]
+    elif isinstance(targets, (str, bytes)):
+        raise ConfigurationError(
+            "Search targets must be DNASequence/DNARecord objects, not raw text.",
+            code="INVALID_SEARCH_TARGETS",
+        )
+    elif not isinstance(targets, Iterable):
+        raise ConfigurationError(
+            "Search targets must be one sequence, DNASet, or iterable of sequences.",
+            code="INVALID_SEARCH_TARGETS",
+        )
+    else:
+        collected: list[SequenceInput] = []
+        for index, item in enumerate(targets):
+            if not isinstance(item, (DNA, DNASequence, DNARecord)):
+                raise ConfigurationError(
+                    "Every search target must be DNASequence or DNARecord.",
+                    code="INVALID_SEARCH_TARGET",
+                    context={"target_index": index, "type": type(item).__name__},
+                )
+            if index >= max_targets:
+                raise ConfigurationError(
+                    "Search target input exceeds max_targets.",
+                    code="SEARCH_TARGET_LIMIT_EXCEEDED",
+                    context={
+                        "target_count": max_targets + 1,
+                        "target_count_is_lower_bound": True,
+                        "max_targets": max_targets,
+                    },
+                    hint="Reduce the target input or increase max_targets explicitly.",
+                )
+            if isinstance(item, DNA):
+                if not item.is_single:
+                    raise ConfigurationError(
+                        "A nested DNA search target must contain exactly one record.",
+                        code="INVALID_SEARCH_TARGET",
+                        context={"target_index": index, "record_count": len(item)},
+                    )
+                collected.append(item.record)
+            else:
+                collected.append(item)
+        resolved = tuple(collected)
+    if len(resolved) > max_targets:
+        raise ConfigurationError(
+            "Search target input exceeds max_targets.",
+            code="SEARCH_TARGET_LIMIT_EXCEEDED",
+            context={
+                "target_count": max_targets + 1,
+                "target_count_is_lower_bound": True,
+                "max_targets": max_targets,
+            },
+            hint="Reduce the target input or increase max_targets explicitly.",
+        )
+    if any(not isinstance(item, (DNASequence, DNARecord)) for item in resolved):
+        raise ConfigurationError(
+            "Every search target must be DNASequence or DNARecord.",
+            code="INVALID_SEARCH_TARGET",
+        )
+    return resolved
+
+
+def validate_bool(value: bool, name: str) -> None:
+    if not isinstance(value, bool):
+        raise ConfigurationError(f"{name} must be 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 validate_non_negative_number(value: int | float, name: str) -> float:
+    if (
+        isinstance(value, bool)
+        or not isinstance(value, (int, float))
+        or not math.isfinite(value)
+        or value < 0
+    ):
+        raise ConfigurationError(
+            f"{name} must be a finite non-negative number.",
+            context={name: value},
+        )
+    return float(value)
+
+
+__all__ = ["NamedVector", "NumericVector", "SequenceInput"]

dnakit/similarity/approximate.py

@@ -0,0 +1,258 @@
+"""Bounded approximate substring matching by dynamic programming."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Iterable
+
+from dnakit.core import DNA, DNARecord, DNASequence, Strand, Topology
+from dnakit.core._json import FrozenDict
+from dnakit.core.facade import resolve_single_dna
+from dnakit.exceptions import ConfigurationError, UnsupportedGapOperationError
+
+from ._shared import SequenceInput, materialize_targets, validate_bool
+from .results import ApproximateMatch, ApproximateSearchResult
+
+DEFAULT_MAX_APPROXIMATE_CELLS = 5_000_000
+DEFAULT_MAX_APPROXIMATE_MATCHES = 100_000
+DEFAULT_MAX_APPROXIMATE_TARGETS = 100_000
+
+
+def _finite_non_negative(value: object, name: str) -> float:
+    if (
+        isinstance(value, bool)
+        or not isinstance(value, (int, float))
+        or not math.isfinite(value)
+        or value < 0
+    ):
+        raise ConfigurationError(
+            f"{name} must be a finite non-negative number.",
+            code="INVALID_APPROXIMATE_MATCH_COST",
+            context={"field": name, "value": value},
+        )
+    return float(value)
+
+
+def _positive_int(value: object, name: str) -> int:
+    if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
+        raise ConfigurationError(
+            f"{name} must be a positive integer.",
+            code="INVALID_APPROXIMATE_MATCH_LIMIT",
+        )
+    return value
+
+
+def _sequence_and_id_without_gap_policy(
+    value: SequenceInput, *, role: str
+) -> tuple[DNASequence, str | None]:
+    """Resolve approximate-search inputs before applying its domain-specific Gap error."""
+
+    if isinstance(value, (DNA, DNARecord, DNASequence)):
+        sequence, record = resolve_single_dna(value)
+        return sequence, None if record is None else record.id
+    raise ConfigurationError(
+        f"{role} must be DNASequence or DNARecord.",
+        code="INVALID_SIMILARITY_SEQUENCE",
+        context={"role": role, "input_type": type(value).__name__},
+    )
+
+
+def _scan_one(
+    query: str,
+    target: str,
+    *,
+    max_distance: float,
+    substitution_cost: float,
+    insertion_cost: float,
+    deletion_cost: float,
+    target_index: int,
+    target_id: str | None,
+    strand: Strand,
+    remaining_matches: int,
+) -> tuple[ApproximateMatch, ...]:
+    columns = len(target) + 1
+    previous = [0.0] * columns
+    starts_previous = list(range(columns))
+    for query_index, query_symbol in enumerate(query, start=1):
+        current = [query_index * deletion_cost] + [0.0] * len(target)
+        starts_current = [0] * columns
+        for target_index_1, target_symbol in enumerate(target, start=1):
+            candidates = (
+                (
+                    previous[target_index_1 - 1]
+                    + (0.0 if query_symbol == target_symbol else substitution_cost),
+                    starts_previous[target_index_1 - 1],
+                    0,
+                ),
+                (
+                    previous[target_index_1] + deletion_cost,
+                    starts_previous[target_index_1],
+                    1,
+                ),
+                (
+                    current[target_index_1 - 1] + insertion_cost,
+                    starts_current[target_index_1 - 1],
+                    2,
+                ),
+            )
+            score, start, _ = min(candidates, key=lambda item: (item[0], item[2], item[1]))
+            current[target_index_1] = score
+            starts_current[target_index_1] = start
+        previous, current = current, previous
+        starts_previous, starts_current = starts_current, starts_previous
+    matches: list[ApproximateMatch] = []
+    seen: set[tuple[int, int, float]] = set()
+    for end, distance in enumerate(previous[1:], start=1):
+        start = starts_previous[end]
+        key = (start, end, distance)
+        if distance <= max_distance and key not in seen:
+            if len(matches) >= remaining_matches:
+                raise ConfigurationError(
+                    "Approximate search exceeds max_matches.",
+                    code="APPROXIMATE_MATCH_LIMIT_EXCEEDED",
+                    context={"match_count_lower_bound": remaining_matches + 1},
+                )
+            seen.add(key)
+            matches.append(
+                ApproximateMatch(
+                    target_index=target_index,
+                    target_id=target_id,
+                    start=start,
+                    end=end,
+                    strand=strand,
+                    distance=distance,
+                )
+            )
+    return tuple(matches)
+
+
+def approximate_search(
+    query: SequenceInput,
+    targets: SequenceInput | Iterable[SequenceInput],
+    *,
+    max_distance: int | float,
+    substitution_cost: int | float = 1.0,
+    insertion_cost: int | float = 1.0,
+    deletion_cost: int | float = 1.0,
+    reverse_complement: bool = False,
+    max_targets: int = DEFAULT_MAX_APPROXIMATE_TARGETS,
+    max_matches: int = DEFAULT_MAX_APPROXIMATE_MATCHES,
+    max_cells: int = DEFAULT_MAX_APPROXIMATE_CELLS,
+) -> ApproximateSearchResult:
+    """Find bounded-cost query alignments ending at each target coordinate."""
+
+    maximum = _finite_non_negative(max_distance, "max_distance")
+    substitution = _finite_non_negative(substitution_cost, "substitution_cost")
+    insertion = _finite_non_negative(insertion_cost, "insertion_cost")
+    deletion = _finite_non_negative(deletion_cost, "deletion_cost")
+    if substitution == insertion == deletion == 0.0:
+        raise ConfigurationError(
+            "At least one edit cost must be positive.", code="DEGENERATE_APPROXIMATE_COSTS"
+        )
+    validate_bool(reverse_complement, "reverse_complement")
+    for name, value in (
+        ("max_targets", max_targets),
+        ("max_matches", max_matches),
+        ("max_cells", max_cells),
+    ):
+        _positive_int(value, name)
+    query_sequence, query_id = _sequence_and_id_without_gap_policy(query, role="query")
+    if query_sequence.topology is Topology.CIRCULAR:
+        raise ConfigurationError(
+            "Approximate query matching requires a linear query.",
+            code="APPROXIMATE_CIRCULAR_UNSUPPORTED",
+        )
+    if query_sequence.is_gapped:
+        raise UnsupportedGapOperationError(
+            "Approximate matching cannot silently omit explicit query Gap objects.",
+            code="APPROXIMATE_GAP_NOT_ALLOWED",
+            context={"role": "query"},
+        )
+    if query_sequence.symbol_length == 0:
+        raise ConfigurationError(
+            "Approximate matching does not accept an empty query.",
+            code="EMPTY_APPROXIMATE_QUERY",
+        )
+    materialized = materialize_targets(targets, max_targets=max_targets)
+    resolved_targets: list[tuple[DNASequence, str | None]] = []
+    total_cells = 0
+    for target in materialized:
+        target_sequence, target_id = _sequence_and_id_without_gap_policy(target, role="target")
+        if target_sequence.topology is Topology.CIRCULAR:
+            raise ConfigurationError(
+                "Approximate matching currently requires linear targets.",
+                code="APPROXIMATE_CIRCULAR_UNSUPPORTED",
+            )
+        if target_sequence.is_gapped:
+            raise UnsupportedGapOperationError(
+                "Approximate matching cannot silently omit explicit target Gap objects.",
+                code="APPROXIMATE_GAP_NOT_ALLOWED",
+                context={"role": "target"},
+            )
+        cells = (query_sequence.symbol_length + 1) * (target_sequence.symbol_length + 1)
+        total_cells += cells * (2 if reverse_complement else 1)
+        if total_cells > max_cells:
+            raise ConfigurationError(
+                "Approximate search exceeds max_cells.",
+                code="APPROXIMATE_MATCH_CELL_LIMIT",
+                context={"required_cells_lower_bound": total_cells, "max_cells": max_cells},
+            )
+        resolved_targets.append((target_sequence, target_id))
+    strands = [(query_sequence.symbols, Strand.FORWARD)]
+    if reverse_complement:
+        reverse = query_sequence.reverse_complement().symbols
+        if reverse != query_sequence.symbols:
+            strands.append((reverse, Strand.REVERSE))
+    matches: list[ApproximateMatch] = []
+    for target_index, (target_sequence, target_id) in enumerate(resolved_targets):
+        for query_symbols, strand in strands:
+            for match in _scan_one(
+                query_symbols,
+                target_sequence.symbols,
+                max_distance=maximum,
+                substitution_cost=substitution,
+                insertion_cost=insertion,
+                deletion_cost=deletion,
+                target_index=target_index,
+                target_id=target_id,
+                strand=strand,
+                remaining_matches=max_matches - len(matches),
+            ):
+                matches.append(match)
+    ordered = tuple(
+        sorted(
+            matches, key=lambda item: (item.target_index, item.start, item.end, item.strand.value)
+        )
+    )
+    return ApproximateSearchResult(
+        name="approximate_search",
+        method="semi-global-weighted-edit-distance",
+        algorithm_version="dnakit-approximate-search-v1",
+        query_id=query_id,
+        query_length=query_sequence.symbol_length,
+        target_count=len(resolved_targets),
+        matches=ordered,
+        max_distance=maximum,
+        reverse_complement=reverse_complement,
+        max_targets=max_targets,
+        max_matches=max_matches,
+        max_cells=max_cells,
+        dp_cells=total_cells,
+        parameters=FrozenDict(
+            {
+                "substitution_cost": substitution,
+                "insertion_cost": insertion,
+                "deletion_cost": deletion,
+                "iupac_matching": "literal",
+                "coordinate_system": "0-based-half-open",
+            }
+        ),
+    )
+
+
+__all__ = [
+    "DEFAULT_MAX_APPROXIMATE_CELLS",
+    "DEFAULT_MAX_APPROXIMATE_MATCHES",
+    "DEFAULT_MAX_APPROXIMATE_TARGETS",
+    "approximate_search",
+]