dnakit 0.1.0.dev0__py3-none-any.whl

dnakit/descriptors/homopolymer.py

@@ -0,0 +1,105 @@
+"""Native exact homopolymer descriptors."""
+
+from __future__ import annotations
+
+from dnakit.core._json import FrozenDict
+from dnakit.core.gap import Gap
+from dnakit.descriptors._shared import (
+    DescriptorAmbiguityPolicy,
+    SequenceInput,
+    coerce_ambiguity_policy,
+    reject_ambiguity,
+    sequence_and_id,
+    symbol_view,
+    validate_bool,
+    validate_positive_int,
+)
+from dnakit.descriptors.results import HomopolymerResult, HomopolymerRun
+
+
+def homopolymer_runs(
+    value: SequenceInput,
+    *,
+    min_run_length: int = 2,
+    ambiguity_policy: DescriptorAmbiguityPolicy | str = DescriptorAmbiguityPolicy.ERROR,
+    cross_gaps: bool = False,
+) -> HomopolymerResult:
+    """Find canonical-base runs in zero-based, half-open symbol coordinates.
+
+    Ignored IUPAC symbols always terminate a run. Gaps also terminate a run
+    unless ``cross_gaps=True``; any such crossing is recorded on the run.
+    """
+
+    sequence, sequence_id = sequence_and_id(value)
+    policy = coerce_ambiguity_policy(ambiguity_policy)
+    reject_ambiguity(sequence, policy)
+    validate_positive_int(min_run_length, "min_run_length")
+    validate_bool(cross_gaps, "cross_gaps")
+    view = symbol_view(sequence)
+    run_segments = view.crossable_segment_ids if cross_gaps else view.segment_ids
+    found: list[HomopolymerRun] = []
+    longest = {base: 0 for base in "ACGT"}
+    run_start: int | None = None
+
+    def close_run(end: int) -> None:
+        nonlocal run_start
+        if run_start is None:
+            return
+        base = view.text[run_start]
+        length = end - run_start
+        longest[base] = max(longest[base], length)
+        if length >= min_run_length:
+            first_segment = view.segment_ids[run_start]
+            last_segment = view.segment_ids[end - 1]
+            crossed_gap_count = last_segment - first_segment
+            crossed_unknown = any(
+                boundary in view.unknown_gap_boundaries
+                for boundary in range(first_segment + 1, last_segment + 1)
+            )
+            coordinate_start = view.coordinate_positions[run_start]
+            last_coordinate = view.coordinate_positions[end - 1]
+            found.append(
+                HomopolymerRun(
+                    base=base,
+                    length=length,
+                    symbol_start=run_start,
+                    symbol_end=end,
+                    coordinate_start=coordinate_start,
+                    coordinate_end=None if last_coordinate is None else last_coordinate + 1,
+                    crossed_gap_count=crossed_gap_count,
+                    crossed_unknown_gap=crossed_unknown,
+                )
+            )
+        run_start = None
+
+    for index, symbol in enumerate(view.text):
+        same_segment = run_start is None or run_segments[index] == run_segments[index - 1]
+        if symbol not in "ACGT":
+            close_run(index)
+        elif run_start is None:
+            run_start = index
+        elif symbol != view.text[run_start] or not same_segment:
+            close_run(index)
+            run_start = index
+    close_run(len(view.text))
+
+    gaps = tuple(part for part in sequence.parts if isinstance(part, Gap))
+    return HomopolymerResult(
+        name="homopolymer",
+        method="exact_canonical_run",
+        sequence_id=sequence_id,
+        ambiguity_policy=policy,
+        cross_gaps=cross_gaps,
+        gap_count=len(gaps),
+        unknown_gap_count=sum(gap.length is None for gap in gaps),
+        min_run_length=min_run_length,
+        longest_length=max(longest.values(), default=0),
+        longest_by_base=FrozenDict(longest),
+        runs=tuple(found),
+        ignored_ambiguity_count=(
+            sequence.ambiguity_count if policy is DescriptorAmbiguityPolicy.IGNORE else 0
+        ),
+    )
+
+
+__all__ = ["homopolymer_runs"]

dnakit/descriptors/kmer.py

@@ -0,0 +1,88 @@
+"""Native exact k-mer statistics."""
+
+from __future__ import annotations
+
+from collections import Counter
+
+from dnakit.core._json import FrozenDict
+from dnakit.core.gap import Gap
+from dnakit.descriptors._shared import (
+    DescriptorAmbiguityPolicy,
+    SequenceInput,
+    coerce_ambiguity_policy,
+    iter_kmers,
+    reject_ambiguity,
+    sequence_and_id,
+    validate_bool,
+)
+from dnakit.descriptors.results import KmerResult
+from dnakit.exceptions import ConfigurationError
+
+_COMPLEMENT = str.maketrans("ACGT", "TGCA")
+
+
+def canonical_kmer(value: str) -> str:
+    """Return the lexicographically smaller strand representation."""
+
+    if not isinstance(value, str) or not value or any(base not in "ACGT" for base in value):
+        raise ConfigurationError(
+            "A canonical k-mer must be a non-empty A/C/G/T string.",
+            context={"kmer": value},
+        )
+    reverse_complement = value.translate(_COMPLEMENT)[::-1]
+    return min(value, reverse_complement)
+
+
+def kmer_statistics(
+    value: SequenceInput,
+    k: int,
+    *,
+    overlapping: bool = True,
+    canonical: bool = False,
+    ambiguity_policy: DescriptorAmbiguityPolicy | str = DescriptorAmbiguityPolicy.ERROR,
+    cross_gaps: bool = False,
+) -> KmerResult:
+    """Return sparse count, frequency, and presence data for valid k-mers.
+
+    Under ``ignore``, any window containing an IUPAC ambiguity is omitted and
+    k-mers never bridge that symbol. If ``k`` exceeds every eligible run, the
+    three sparse outputs are empty and the denominator is zero.
+    """
+
+    sequence, sequence_id = sequence_and_id(value)
+    policy = coerce_ambiguity_policy(ambiguity_policy)
+    reject_ambiguity(sequence, policy)
+    validate_bool(canonical, "canonical")
+    observed = iter_kmers(
+        sequence,
+        k=k,
+        overlapping=overlapping,
+        cross_gaps=cross_gaps,
+    )
+    counts = Counter(canonical_kmer(item) if canonical else item for item in observed)
+    ordered_counts = dict(sorted(counts.items()))
+    denominator = sum(ordered_counts.values())
+    frequencies = {item: count / denominator for item, count in ordered_counts.items()}
+    gaps = tuple(part for part in sequence.parts if isinstance(part, Gap))
+    return KmerResult(
+        name="kmer",
+        method="exact_sliding_kmer",
+        sequence_id=sequence_id,
+        ambiguity_policy=policy,
+        cross_gaps=cross_gaps,
+        gap_count=len(gaps),
+        unknown_gap_count=sum(gap.length is None for gap in gaps),
+        k=k,
+        overlapping=overlapping,
+        canonical=canonical,
+        counts=FrozenDict(ordered_counts),
+        frequencies=FrozenDict(frequencies),
+        presence=tuple(ordered_counts),
+        denominator=denominator,
+        ignored_ambiguity_count=(
+            sequence.ambiguity_count if policy is DescriptorAmbiguityPolicy.IGNORE else 0
+        ),
+    )
+
+
+__all__ = ["canonical_kmer", "kmer_statistics"]

dnakit/descriptors/results.py

@@ -0,0 +1,286 @@
+"""Immutable result objects returned by native descriptor functions."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, cast
+
+from dnakit.core import Provenance
+from dnakit.core._json import FrozenDict, to_json_compatible
+from dnakit.descriptors._shared import DescriptorAmbiguityPolicy
+from dnakit.descriptors.schema import DESCRIPTOR_NAMES_V1, DESCRIPTOR_SCHEMA_VERSION
+from dnakit.exceptions import ConfigurationError
+
+
+@dataclass(frozen=True)
+class DescriptorResult:
+    """Common auditable context shared by all descriptor result types."""
+
+    name: str
+    method: str
+    sequence_id: str | None
+    ambiguity_policy: DescriptorAmbiguityPolicy | None
+    cross_gaps: bool
+    gap_count: int
+    unknown_gap_count: int
+
+    def to_dict(self) -> dict[str, Any]:
+        return cast(dict[str, Any], to_json_compatible(self))
+
+
+@dataclass(frozen=True)
+class AllDescriptorsResult:
+    """One ordered 240-field vector plus explicit unavailable-value reasons."""
+
+    schema_version: str
+    sequence_id: str | None
+    values: FrozenDict
+    unavailable_reasons: FrozenDict
+    conditions: FrozenDict
+    provenance: Provenance
+
+    def __post_init__(self) -> None:
+        if self.schema_version != DESCRIPTOR_SCHEMA_VERSION:
+            raise ConfigurationError("Unknown all-descriptor schema version.")
+        if self.sequence_id is not None and (
+            not isinstance(self.sequence_id, str) or not self.sequence_id.strip()
+        ):
+            raise ConfigurationError("AllDescriptorsResult sequence_id must be non-empty or None.")
+        if tuple(self.values) != DESCRIPTOR_NAMES_V1:
+            raise ConfigurationError(
+                "AllDescriptorsResult values must exactly match descriptor_schema_v1 order."
+            )
+        unavailable = {name for name, value in self.values.items() if value is None}
+        if set(self.unavailable_reasons) != unavailable or any(
+            not isinstance(reason, str) or not reason.strip()
+            for reason in self.unavailable_reasons.values()
+        ):
+            raise ConfigurationError(
+                "Every unavailable descriptor must have exactly one non-empty reason."
+            )
+        if not isinstance(self.conditions, FrozenDict):
+            raise ConfigurationError("AllDescriptorsResult conditions must be FrozenDict.")
+        if not isinstance(self.provenance, Provenance):
+            raise ConfigurationError("AllDescriptorsResult provenance must be Provenance.")
+
+    def to_dict(self) -> dict[str, Any]:
+        return cast(dict[str, Any], to_json_compatible(self))
+
+
+@dataclass(frozen=True)
+class LengthResult(DescriptorResult):
+    """Explicit symbol, coordinate, ambiguity, and gap lengths."""
+
+    symbol_length: int
+    coordinate_span: int | None
+    canonical_base_count: int
+    ambiguity_length: int
+    known_gap_length: int
+
+
+@dataclass(frozen=True)
+class CompositionResult(DescriptorResult):
+    """Canonical base counts and fractions with an explicit denominator."""
+
+    counts: FrozenDict
+    fractions: FrozenDict
+    denominator: int
+    ignored_ambiguity_count: int
+
+
+@dataclass(frozen=True)
+class ContentResult(DescriptorResult):
+    """GC and AT composition calculated over canonical bases."""
+
+    gc_count: int
+    at_count: int
+    gc_fraction: float | None
+    at_fraction: float | None
+    denominator: int
+    ignored_ambiguity_count: int
+
+
+@dataclass(frozen=True)
+class SkewResult(DescriptorResult):
+    """GC=(G-C)/(G+C) and AT=(A-T)/(A+T), or None at zero denominator."""
+
+    gc_skew: float | None
+    at_skew: float | None
+    gc_denominator: int
+    at_denominator: int
+    ignored_ambiguity_count: int
+
+
+@dataclass(frozen=True)
+class CpGResult(DescriptorResult):
+    """CpG count, adjacency density, and observed/expected ratio."""
+
+    cpg_count: int
+    density: float | None
+    observed_expected: float | None
+    adjacent_pair_denominator: int
+    expected_length_denominator: int
+    c_count: int
+    g_count: int
+    ignored_ambiguity_count: int
+    density_formula: str
+    observed_expected_formula: str
+
+
+@dataclass(frozen=True)
+class KmerResult(DescriptorResult):
+    """Sparse k-mer counts, frequencies, and presence values."""
+
+    k: int
+    overlapping: bool
+    canonical: bool
+    counts: FrozenDict
+    frequencies: FrozenDict
+    presence: tuple[str, ...]
+    denominator: int
+    ignored_ambiguity_count: int
+
+
+@dataclass(frozen=True)
+class EntropyResult(DescriptorResult):
+    """Shannon entropy of canonical bases or valid canonical k-mers."""
+
+    entropy: float
+    unit: str
+    k: int
+    log_base: float
+    observation_count: int
+    category_count: int
+    ignored_ambiguity_count: int
+
+
+@dataclass(frozen=True)
+class HomopolymerRun:
+    """One canonical-base run in zero-based, half-open coordinates."""
+
+    base: str
+    length: int
+    symbol_start: int
+    symbol_end: int
+    coordinate_start: int | None
+    coordinate_end: int | None
+    crossed_gap_count: int
+    crossed_unknown_gap: bool
+
+
+@dataclass(frozen=True)
+class HomopolymerResult(DescriptorResult):
+    """Longest runs and all runs meeting the requested minimum length."""
+
+    min_run_length: int
+    longest_length: int
+    longest_by_base: FrozenDict
+    runs: tuple[HomopolymerRun, ...]
+    ignored_ambiguity_count: int
+
+
+@dataclass(frozen=True)
+class WindowResult:
+    """Descriptors for one zero-based, half-open symbol window."""
+
+    symbol_start: int
+    symbol_end: int
+    coordinate_start: int | None
+    coordinate_end: int | None
+    is_partial: bool
+    crossed_gap_count: int
+    crossed_unknown_gap: bool
+    values: FrozenDict
+
+
+@dataclass(frozen=True)
+class WindowDescriptorResult(DescriptorResult):
+    """Ordered position-by-feature rows for a sliding-window calculation."""
+
+    window_size: int
+    step: int
+    include_partial: bool
+    entropy_log_base: float
+    descriptors: tuple[str, ...]
+    windows: tuple[WindowResult, ...]
+
+
+@dataclass(frozen=True)
+class CodonResult(DescriptorResult):
+    """In-frame codon counts, frequencies, and start/stop densities."""
+
+    frame: int
+    genetic_code: int
+    counts: FrozenDict
+    frequencies: FrozenDict
+    codon_count: int
+    start_count: int
+    stop_count: int
+    start_density: float | None
+    stop_density: float | None
+    incomplete_base_count: int
+    ignored_ambiguity_codon_count: int
+    gap_interrupted_codon_count: int
+    phase_coordinate_system: str = "sequence-coordinate"
+    phase_unresolved_after_gap: bool = False
+    unresolved_downstream_base_count: int = 0
+
+
+@dataclass(frozen=True)
+class ComplexityResult(DescriptorResult):
+    """Linguistic vocabulary complexity with per-word-size audit."""
+
+    score: float
+    max_word_size: int
+    by_k: FrozenDict
+    observed_by_k: FrozenDict
+    possible_by_k: FrozenDict
+    observation_count: int
+    max_observations: int
+    formula: str
+
+
+@dataclass(frozen=True)
+class RepeatRun:
+    unit: str
+    unit_length: int
+    repeat_count: int
+    symbol_start: int
+    symbol_end: int
+
+
+@dataclass(frozen=True)
+class ExactRepeatResult(DescriptorResult):
+    """Union coverage and runs from an exact tandem-repeat scan."""
+
+    repeat_fraction: float
+    repeated_base_count: int
+    denominator: int
+    min_unit_length: int
+    max_unit_length: int
+    min_repeats: int
+    runs: tuple[RepeatRun, ...]
+    repeat_count_by_unit: FrozenDict
+    comparisons: int
+    max_comparisons: int
+
+
+__all__ = [
+    "AllDescriptorsResult",
+    "CodonResult",
+    "ComplexityResult",
+    "CompositionResult",
+    "ContentResult",
+    "CpGResult",
+    "DescriptorResult",
+    "EntropyResult",
+    "ExactRepeatResult",
+    "HomopolymerResult",
+    "HomopolymerRun",
+    "KmerResult",
+    "LengthResult",
+    "RepeatRun",
+    "SkewResult",
+    "WindowDescriptorResult",
+    "WindowResult",
+]