dnakit 0.1.0.dev0__py3-none-any.whl

dnakit/descriptors/basic.py

@@ -0,0 +1,193 @@
+"""Native length, composition, skew, and CpG descriptors."""
+
+from __future__ import annotations
+
+from collections import Counter
+from typing import cast
+
+from dnakit.core._json import FrozenDict
+from dnakit.core.gap import Gap
+from dnakit.descriptors._shared import (
+    DescriptorAmbiguityPolicy,
+    SequenceInput,
+    canonical_runs,
+    coerce_ambiguity_policy,
+    fragments,
+    reject_ambiguity,
+    sequence_and_id,
+)
+from dnakit.descriptors.results import (
+    CompositionResult,
+    ContentResult,
+    CpGResult,
+    LengthResult,
+    SkewResult,
+)
+
+
+def length_features(value: SequenceInput) -> LengthResult:
+    """Return lengths without guessing the span of an unknown-length gap."""
+
+    sequence, sequence_id = sequence_and_id(value)
+    gaps = tuple(part for part in sequence.parts if isinstance(part, Gap))
+    return LengthResult(
+        name="length",
+        method="explicit_sequence_parts",
+        sequence_id=sequence_id,
+        ambiguity_policy=None,
+        cross_gaps=False,
+        gap_count=len(gaps),
+        unknown_gap_count=sum(gap.length is None for gap in gaps),
+        symbol_length=sequence.symbol_length,
+        coordinate_span=sequence.coordinate_span,
+        canonical_base_count=sequence.canonical_base_count,
+        ambiguity_length=sequence.ambiguity_count,
+        known_gap_length=sum(gap.length or 0 for gap in gaps),
+    )
+
+
+def base_composition(
+    value: SequenceInput,
+    *,
+    ambiguity_policy: DescriptorAmbiguityPolicy | str = DescriptorAmbiguityPolicy.ERROR,
+) -> CompositionResult:
+    """Count A/C/G/T; ignored ambiguity is excluded from the fraction denominator."""
+
+    sequence, sequence_id = sequence_and_id(value)
+    policy = coerce_ambiguity_policy(ambiguity_policy)
+    reject_ambiguity(sequence, policy)
+    counts = Counter(symbol for symbol in sequence.symbols if symbol in "ACGT")
+    denominator = sum(counts.values())
+    ordered_counts = {base: counts[base] for base in "ACGT"}
+    fractions = {
+        base: (ordered_counts[base] / denominator if denominator else 0.0) for base in "ACGT"
+    }
+    gaps = tuple(part for part in sequence.parts if isinstance(part, Gap))
+    return CompositionResult(
+        name="base_composition",
+        method="canonical_base_count",
+        sequence_id=sequence_id,
+        ambiguity_policy=policy,
+        cross_gaps=False,
+        gap_count=len(gaps),
+        unknown_gap_count=sum(gap.length is None for gap in gaps),
+        counts=FrozenDict(ordered_counts),
+        fractions=FrozenDict(fractions),
+        denominator=denominator,
+        ignored_ambiguity_count=(
+            sequence.ambiguity_count if policy is DescriptorAmbiguityPolicy.IGNORE else 0
+        ),
+    )
+
+
+def gc_at_content(
+    value: SequenceInput,
+    *,
+    ambiguity_policy: DescriptorAmbiguityPolicy | str = DescriptorAmbiguityPolicy.ERROR,
+) -> ContentResult:
+    """Calculate GC and AT fractions over the A/C/G/T denominator."""
+
+    composition = base_composition(value, ambiguity_policy=ambiguity_policy)
+    gc_count = cast(int, composition.counts["G"]) + cast(int, composition.counts["C"])
+    at_count = cast(int, composition.counts["A"]) + cast(int, composition.counts["T"])
+    denominator = composition.denominator
+    return ContentResult(
+        name="gc_at_content",
+        method="canonical_base_fraction",
+        sequence_id=composition.sequence_id,
+        ambiguity_policy=composition.ambiguity_policy,
+        cross_gaps=False,
+        gap_count=composition.gap_count,
+        unknown_gap_count=composition.unknown_gap_count,
+        gc_count=gc_count,
+        at_count=at_count,
+        gc_fraction=gc_count / denominator if denominator else None,
+        at_fraction=at_count / denominator if denominator else None,
+        denominator=denominator,
+        ignored_ambiguity_count=composition.ignored_ambiguity_count,
+    )
+
+
+def base_skew(
+    value: SequenceInput,
+    *,
+    ambiguity_policy: DescriptorAmbiguityPolicy | str = DescriptorAmbiguityPolicy.ERROR,
+) -> SkewResult:
+    """Calculate GC and AT skew; a zero formula denominator produces None."""
+
+    composition = base_composition(value, ambiguity_policy=ambiguity_policy)
+    a = cast(int, composition.counts["A"])
+    c = cast(int, composition.counts["C"])
+    g = cast(int, composition.counts["G"])
+    t = cast(int, composition.counts["T"])
+    gc_denominator = g + c
+    at_denominator = a + t
+    return SkewResult(
+        name="base_skew",
+        method="gc=(g-c)/(g+c);at=(a-t)/(a+t)",
+        sequence_id=composition.sequence_id,
+        ambiguity_policy=composition.ambiguity_policy,
+        cross_gaps=False,
+        gap_count=composition.gap_count,
+        unknown_gap_count=composition.unknown_gap_count,
+        gc_skew=(g - c) / gc_denominator if gc_denominator else None,
+        at_skew=(a - t) / at_denominator if at_denominator else None,
+        gc_denominator=gc_denominator,
+        at_denominator=at_denominator,
+        ignored_ambiguity_count=composition.ignored_ambiguity_count,
+    )
+
+
+def cpg_features(
+    value: SequenceInput,
+    *,
+    ambiguity_policy: DescriptorAmbiguityPolicy | str = DescriptorAmbiguityPolicy.ERROR,
+    cross_gaps: bool = False,
+) -> CpGResult:
+    """Calculate CpG statistics without crossing gaps or ambiguity by default.
+
+    Density is ``count(CG) / eligible adjacent canonical pairs``. Observed/expected
+    is ``count(CG) * canonical_base_count / (count(C) * count(G))``. Undefined
+    ratios are returned as ``None`` rather than NaN or infinity.
+    """
+
+    sequence, sequence_id = sequence_and_id(value)
+    policy = coerce_ambiguity_policy(ambiguity_policy)
+    reject_ambiguity(sequence, policy)
+    text_runs = tuple(
+        run
+        for fragment in fragments(sequence, cross_gaps=cross_gaps)
+        for run in canonical_runs(fragment)
+    )
+    cpg_count = sum(run.count("CG") for run in text_runs)
+    pair_denominator = sum(max(0, len(run) - 1) for run in text_runs)
+    canonical_length = sum(len(run) for run in text_runs)
+    c_count = sum(run.count("C") for run in text_runs)
+    g_count = sum(run.count("G") for run in text_runs)
+    gaps = tuple(part for part in sequence.parts if isinstance(part, Gap))
+    return CpGResult(
+        name="cpg",
+        method="adjacent_cg_and_length_normalized_oe",
+        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),
+        cpg_count=cpg_count,
+        density=cpg_count / pair_denominator if pair_denominator else None,
+        observed_expected=(
+            cpg_count * canonical_length / (c_count * g_count) if c_count and g_count else None
+        ),
+        adjacent_pair_denominator=pair_denominator,
+        expected_length_denominator=canonical_length,
+        c_count=c_count,
+        g_count=g_count,
+        ignored_ambiguity_count=(
+            sequence.ambiguity_count if policy is DescriptorAmbiguityPolicy.IGNORE else 0
+        ),
+        density_formula="count(CG)/eligible_adjacent_canonical_pairs",
+        observed_expected_formula="count(CG)*canonical_base_count/(count(C)*count(G))",
+    )
+
+
+__all__ = ["base_composition", "base_skew", "cpg_features", "gc_at_content", "length_features"]

dnakit/descriptors/codon.py

@@ -0,0 +1,195 @@
+"""Native standard-code codon statistics."""
+
+from __future__ import annotations
+
+from collections import Counter
+from dataclasses import dataclass
+
+from dnakit.core._json import FrozenDict
+from dnakit.core.gap import Gap
+from dnakit.core.sequence import DNASequence
+from dnakit.descriptors._shared import (
+    DescriptorAmbiguityPolicy,
+    SequenceInput,
+    coerce_ambiguity_policy,
+    reject_ambiguity,
+    sequence_and_id,
+    symbol_view,
+    validate_bool,
+)
+from dnakit.descriptors.results import CodonResult
+from dnakit.exceptions import ConfigurationError
+
+_STANDARD_STARTS = frozenset({"ATG"})
+_STANDARD_STOPS = frozenset({"TAA", "TAG", "TGA"})
+
+
+@dataclass(frozen=True)
+class _CodonAudit:
+    counts: Counter[str]
+    ignored_ambiguity: int
+    gap_interrupted: int
+    incomplete_bases: int
+    phase_unresolved: bool
+    unresolved_downstream_bases: int
+
+
+def _coordinate_codon_audit(sequence: DNASequence, frame: int) -> _CodonAudit:
+    slots: dict[int, dict[int, str]] = {}
+    known_gaps: list[tuple[int, int]] = []
+    coordinate: int | None = 0
+    unknown_gap_start: int | None = None
+    unresolved_downstream = 0
+    for part in sequence.parts:
+        if isinstance(part, str):
+            if coordinate is None:
+                unresolved_downstream += len(part)
+                continue
+            for symbol in part:
+                if coordinate >= frame:
+                    relative = coordinate - frame
+                    slots.setdefault(relative // 3, {})[relative % 3] = symbol
+                coordinate += 1
+        elif coordinate is not None:
+            if part.length is None:
+                unknown_gap_start = coordinate
+                coordinate = None
+            else:
+                known_gaps.append((coordinate, coordinate + part.length))
+                coordinate += part.length
+
+    counts: Counter[str] = Counter()
+    ignored_ambiguity = 0
+    interrupted = 0
+    incomplete = 0
+    for slot, symbols in slots.items():
+        codon_start = frame + slot * 3
+        codon_end = codon_start + 3
+        if len(symbols) == 3:
+            codon = "".join(symbols[position] for position in range(3))
+            if any(base not in "ACGT" for base in codon):
+                ignored_ambiguity += 1
+            else:
+                counts[codon] += 1
+            continue
+        overlaps_known_gap = any(
+            gap_start < codon_end and gap_end > codon_start for gap_start, gap_end in known_gaps
+        )
+        overlaps_unknown_gap = (
+            unknown_gap_start is not None and codon_start <= unknown_gap_start < codon_end
+        )
+        if overlaps_known_gap or overlaps_unknown_gap:
+            interrupted += 1
+        else:
+            incomplete += len(symbols)
+    return _CodonAudit(
+        counts,
+        ignored_ambiguity,
+        interrupted,
+        incomplete,
+        unknown_gap_start is not None,
+        unresolved_downstream,
+    )
+
+
+def _concatenated_codon_audit(sequence: DNASequence, frame: int) -> _CodonAudit:
+    view = symbol_view(sequence)
+    codon_segments = view.crossable_segment_ids
+    counts: Counter[str] = Counter()
+    ignored_ambiguity = 0
+    gap_interrupted = 0
+    complete_candidate_count = 0
+    for start in range(frame, len(view.text) - 2, 3):
+        complete_candidate_count += 1
+        segments = codon_segments[start : start + 3]
+        if len(set(segments)) != 1:
+            gap_interrupted += 1
+            continue
+        codon = view.text[start : start + 3]
+        if any(base not in "ACGT" for base in codon):
+            ignored_ambiguity += 1
+        else:
+            counts[codon] += 1
+    eligible_after_frame = max(0, len(view.text) - frame)
+    return _CodonAudit(
+        counts,
+        ignored_ambiguity,
+        gap_interrupted,
+        eligible_after_frame - complete_candidate_count * 3,
+        False,
+        0,
+    )
+
+
+def codon_statistics(
+    value: SequenceInput,
+    *,
+    frame: int = 0,
+    genetic_code: int = 1,
+    ambiguity_policy: DescriptorAmbiguityPolicy | str = DescriptorAmbiguityPolicy.ERROR,
+    cross_gaps: bool = False,
+) -> CodonResult:
+    """Count in-frame codons using NCBI standard genetic code table 1.
+
+    By default, ``frame`` is a zero-based offset in the full sequence coordinate
+    span: known Gap lengths advance phase, codons overlapping a Gap are omitted,
+    and an unknown-length Gap makes downstream phase unresolved. With
+    ``cross_gaps=True``, crossable Gaps are explicitly omitted and phase follows
+    concatenated symbol coordinates; a ``crossable=False`` Gap remains a hard
+    boundary. An ignored ambiguous codon is omitted without changing phase.
+    """
+
+    sequence, sequence_id = sequence_and_id(value)
+    policy = coerce_ambiguity_policy(ambiguity_policy)
+    reject_ambiguity(sequence, policy)
+    if isinstance(frame, bool) or not isinstance(frame, int) or frame not in {0, 1, 2}:
+        raise ConfigurationError(
+            "frame must be the zero-based offset 0, 1, or 2.",
+            context={"frame": frame},
+        )
+    if genetic_code != 1 or isinstance(genetic_code, bool):
+        raise ConfigurationError(
+            "MVP codon statistics currently support only genetic_code=1.",
+            context={"genetic_code": genetic_code},
+        )
+    validate_bool(cross_gaps, "cross_gaps")
+
+    audit = (
+        _concatenated_codon_audit(sequence, frame)
+        if cross_gaps
+        else _coordinate_codon_audit(sequence, frame)
+    )
+
+    ordered_counts = dict(sorted(audit.counts.items()))
+    codon_count = sum(ordered_counts.values())
+    frequencies = {codon: count / codon_count for codon, count in ordered_counts.items()}
+    start_count = sum(audit.counts[codon] for codon in _STANDARD_STARTS)
+    stop_count = sum(audit.counts[codon] for codon in _STANDARD_STOPS)
+    gaps = tuple(part for part in sequence.parts if isinstance(part, Gap))
+    return CodonResult(
+        name="codon",
+        method="in_frame_standard_genetic_code",
+        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),
+        frame=frame,
+        genetic_code=genetic_code,
+        counts=FrozenDict(ordered_counts),
+        frequencies=FrozenDict(frequencies),
+        codon_count=codon_count,
+        start_count=start_count,
+        stop_count=stop_count,
+        start_density=start_count / codon_count if codon_count else None,
+        stop_density=stop_count / codon_count if codon_count else None,
+        incomplete_base_count=audit.incomplete_bases,
+        ignored_ambiguity_codon_count=audit.ignored_ambiguity,
+        gap_interrupted_codon_count=audit.gap_interrupted,
+        phase_coordinate_system=("concatenated-symbol" if cross_gaps else "sequence-coordinate"),
+        phase_unresolved_after_gap=audit.phase_unresolved,
+        unresolved_downstream_base_count=audit.unresolved_downstream_bases,
+    )
+
+
+__all__ = ["codon_statistics"]

dnakit/descriptors/complexity.py

@@ -0,0 +1,201 @@
+"""Bounded, explicit sequence-complexity and exact-repeat descriptors."""
+
+from __future__ import annotations
+
+import math
+from collections import Counter
+
+from dnakit.core import Gap, Topology
+from dnakit.core._json import FrozenDict
+from dnakit.exceptions import ConfigurationError
+
+from ._shared import (
+    DescriptorAmbiguityPolicy,
+    SequenceInput,
+    canonical_runs,
+    coerce_ambiguity_policy,
+    fragments,
+    reject_ambiguity,
+    sequence_and_id,
+    validate_bool,
+    validate_positive_int,
+)
+from .results import ComplexityResult, ExactRepeatResult, RepeatRun
+
+
+def linguistic_complexity(
+    value: SequenceInput,
+    *,
+    max_word_size: int = 6,
+    ambiguity_policy: DescriptorAmbiguityPolicy | str = DescriptorAmbiguityPolicy.ERROR,
+    cross_gaps: bool = False,
+    max_observations: int = 10_000_000,
+) -> ComplexityResult:
+    """Compute observed/possible vocabulary ratios for k=1..max_word_size.
+
+    For each k, the denominator is ``min(4**k, number of k-mer positions)``.
+    The aggregate score is the product of per-k ratios, a common explicit
+    linguistic-complexity definition; no DUST implementation is claimed.
+    """
+
+    sequence, sequence_id = sequence_and_id(value)
+    if sequence.topology is Topology.CIRCULAR:
+        raise ConfigurationError(
+            "Linguistic complexity currently requires a linear sequence.",
+            code="COMPLEXITY_CIRCULAR_UNSUPPORTED",
+        )
+    policy = coerce_ambiguity_policy(ambiguity_policy)
+    reject_ambiguity(sequence, policy)
+    validate_positive_int(max_word_size, "max_word_size")
+    validate_positive_int(max_observations, "max_observations")
+    validate_bool(cross_gaps, "cross_gaps")
+    if max_word_size > 16:
+        raise ConfigurationError(
+            "max_word_size cannot exceed 16.", code="COMPLEXITY_WORD_SIZE_LIMIT"
+        )
+    by_k: dict[str, float] = {}
+    observed_by_k: dict[str, int] = {}
+    possible_by_k: dict[str, int] = {}
+    total_observations = 0
+    for k in range(1, max_word_size + 1):
+        words: set[str] = set()
+        positions = 0
+        for fragment in fragments(sequence, cross_gaps=cross_gaps):
+            for run in canonical_runs(fragment):
+                run_positions = max(0, len(run) - k + 1)
+                positions += run_positions
+                total_observations += run_positions
+                if total_observations > max_observations:
+                    raise ConfigurationError(
+                        "Complexity calculation exceeds max_observations.",
+                        code="COMPLEXITY_OBSERVATION_LIMIT",
+                    )
+                words.update(run[offset : offset + k] for offset in range(run_positions))
+        possible = min(4**k, positions)
+        ratio = len(words) / possible if possible else 0.0
+        by_k[str(k)] = ratio
+        observed_by_k[str(k)] = len(words)
+        possible_by_k[str(k)] = possible
+    nonempty = tuple(value for key, value in by_k.items() if possible_by_k[key] > 0)
+    score = math.prod(nonempty) if nonempty else 0.0
+    gaps = tuple(part for part in sequence.parts if isinstance(part, Gap))
+    return ComplexityResult(
+        name="linguistic_complexity",
+        method="vocabulary-observed-over-possible-product",
+        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),
+        score=score,
+        max_word_size=max_word_size,
+        by_k=FrozenDict(by_k),
+        observed_by_k=FrozenDict(observed_by_k),
+        possible_by_k=FrozenDict(possible_by_k),
+        observation_count=total_observations,
+        max_observations=max_observations,
+        formula="product_k(unique_kmers/min(4**k,valid_kmer_positions))",
+    )
+
+
+def exact_repeat_fraction(
+    value: SequenceInput,
+    *,
+    min_unit_length: int = 1,
+    max_unit_length: int = 20,
+    min_repeats: int = 2,
+    ambiguity_policy: DescriptorAmbiguityPolicy | str = DescriptorAmbiguityPolicy.ERROR,
+    cross_gaps: bool = False,
+    max_comparisons: int = 5_000_000,
+) -> ExactRepeatResult:
+    """Measure union coverage of maximal exact tandem-repeat runs."""
+
+    sequence, sequence_id = sequence_and_id(value)
+    if sequence.topology is Topology.CIRCULAR:
+        raise ConfigurationError(
+            "Exact tandem-repeat coverage currently requires a linear sequence.",
+            code="REPEAT_CIRCULAR_UNSUPPORTED",
+        )
+    policy = coerce_ambiguity_policy(ambiguity_policy)
+    reject_ambiguity(sequence, policy)
+    for name, item in (
+        ("min_unit_length", min_unit_length),
+        ("max_unit_length", max_unit_length),
+        ("min_repeats", min_repeats),
+        ("max_comparisons", max_comparisons),
+    ):
+        validate_positive_int(item, name)
+    validate_bool(cross_gaps, "cross_gaps")
+    if min_unit_length > max_unit_length or max_unit_length > 100 or min_repeats < 2:
+        raise ConfigurationError(
+            "Repeat bounds require 1 <= min_unit_length <= max_unit_length <= 100 and "
+            "min_repeats >= 2.",
+            code="INVALID_REPEAT_DESCRIPTOR_CONFIG",
+        )
+    runs: list[RepeatRun] = []
+    covered_positions: set[int] = set()
+    comparisons = 0
+    symbol_offset = 0
+    for fragment in fragments(sequence, cross_gaps=cross_gaps):
+        start = 0
+        while start < len(fragment):
+            found: tuple[str, int, int] | None = None
+            for unit_length in range(min_unit_length, max_unit_length + 1):
+                if start + unit_length * min_repeats > len(fragment):
+                    continue
+                unit = fragment[start : start + unit_length]
+                if any(symbol not in "ACGT" for symbol in unit):
+                    continue
+                count = 1
+                cursor = start + unit_length
+                while cursor + unit_length <= len(fragment):
+                    comparisons += 1
+                    if comparisons > max_comparisons:
+                        raise ConfigurationError(
+                            "Repeat calculation exceeds max_comparisons.",
+                            code="REPEAT_COMPARISON_LIMIT",
+                        )
+                    if fragment[cursor : cursor + unit_length] != unit:
+                        break
+                    count += 1
+                    cursor += unit_length
+                if count >= min_repeats:
+                    found = unit, count, cursor
+                    break
+            if found is None:
+                start += 1
+                continue
+            unit, count, end = found
+            absolute_start = symbol_offset + start
+            absolute_end = symbol_offset + end
+            runs.append(RepeatRun(unit, len(unit), count, absolute_start, absolute_end))
+            covered_positions.update(range(absolute_start, absolute_end))
+            start = end
+        symbol_offset += len(fragment)
+    denominator = sequence.canonical_base_count
+    repeat_count_by_unit = Counter(run.unit_length for run in runs)
+    gaps = tuple(part for part in sequence.parts if isinstance(part, Gap))
+    return ExactRepeatResult(
+        name="exact_repeat_fraction",
+        method="maximal-exact-tandem-repeat-union",
+        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),
+        repeat_fraction=len(covered_positions) / denominator if denominator else 0.0,
+        repeated_base_count=len(covered_positions),
+        denominator=denominator,
+        min_unit_length=min_unit_length,
+        max_unit_length=max_unit_length,
+        min_repeats=min_repeats,
+        runs=tuple(runs),
+        repeat_count_by_unit=FrozenDict(
+            {str(key): value for key, value in sorted(repeat_count_by_unit.items())}
+        ),
+        comparisons=comparisons,
+        max_comparisons=max_comparisons,
+    )
+
+
+__all__ = ["exact_repeat_fraction", "linguistic_complexity"]

dnakit/descriptors/entropy.py

@@ -0,0 +1,101 @@
+"""Native Shannon entropy descriptors."""
+
+from __future__ import annotations
+
+import math
+from collections import Counter
+from collections.abc import Iterable
+
+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,
+    validate_positive_int,
+)
+from dnakit.descriptors.results import EntropyResult
+from dnakit.exceptions import ConfigurationError
+
+
+def shannon_entropy(
+    value: SequenceInput,
+    *,
+    unit: str = "base",
+    k: int = 1,
+    log_base: float = 2.0,
+    ambiguity_policy: DescriptorAmbiguityPolicy | str = DescriptorAmbiguityPolicy.ERROR,
+    cross_gaps: bool = False,
+) -> EntropyResult:
+    """Calculate Shannon entropy for canonical bases or valid k-mers.
+
+    An empty observation distribution has entropy ``0.0``. The log base must be
+    finite, positive, and different from one.
+    """
+
+    sequence, sequence_id = sequence_and_id(value)
+    policy = coerce_ambiguity_policy(ambiguity_policy)
+    reject_ambiguity(sequence, policy)
+    if unit not in {"base", "kmer"}:
+        raise ConfigurationError(
+            "Entropy unit must be 'base' or 'kmer'.",
+            context={"unit": unit},
+        )
+    validate_positive_int(k, "k")
+    validate_bool(cross_gaps, "cross_gaps")
+    if (
+        isinstance(log_base, bool)
+        or not isinstance(log_base, (int, float))
+        or not math.isfinite(log_base)
+        or log_base <= 0
+        or log_base == 1
+    ):
+        raise ConfigurationError(
+            "log_base must be finite, positive, and different from one.",
+            context={"log_base": log_base},
+        )
+
+    observations: Iterable[str]
+    if unit == "base":
+        observations = (symbol for symbol in sequence.symbols if symbol in "ACGT")
+        resolved_k = 1
+    else:
+        observations = iter_kmers(
+            sequence,
+            k=k,
+            overlapping=True,
+            cross_gaps=cross_gaps,
+        )
+        resolved_k = k
+    counts = Counter(observations)
+    total = sum(counts.values())
+    entropy = (
+        -sum((count / total) * math.log(count / total, log_base) for count in counts.values())
+        if total
+        else 0.0
+    )
+    gaps = tuple(part for part in sequence.parts if isinstance(part, Gap))
+    return EntropyResult(
+        name="shannon_entropy",
+        method="shannon",
+        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),
+        entropy=entropy,
+        unit=unit,
+        k=resolved_k,
+        log_base=float(log_base),
+        observation_count=total,
+        category_count=len(counts),
+        ignored_ambiguity_count=(
+            sequence.ambiguity_count if policy is DescriptorAmbiguityPolicy.IGNORE else 0
+        ),
+    )
+
+
+__all__ = ["shannon_entropy"]