seqforge 2026.7.1__py3-none-any.whl

seqforge/resolve/scoring.py

@@ -0,0 +1,373 @@
+"""Per-technology scoring: evidence matrix -> injective assignment -> cardinality-normalized score.
+
+For technology ``t`` with roles ``R_t`` (its reads) and files ``F``, cell ``M[r][f]`` is ``FORBIDDEN``
+if any ``requires(r)`` gate FAILs or any ``excludes(r)`` gate PASSes, else the normalized weighted
+``supports(r)`` sum in ``[0, 1]``. ``FORBIDDEN`` is an internal ``Cell(forbidden=True)`` flag, never a
+``±inf`` — serialized it is ``{"status": "forbidden"}`` so no infinity ever crosses the JSON boundary.
+
+``score(t) = raw / |R_t|  -  (λ / |R_t|)·|F \\ A*|`` is cardinality-normalized so a 2-role 10x and a
+6-role SPLiT-seq are comparable. The filename prior enters as a sub-threshold ``β``-scaled nudge that
+can only break an exact byte-tie.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from dataclasses import dataclass
+
+from ..io import OnlistNotAvailable, OnlistRegistry
+from ..kb.schema import OnlistHitRate, Read, SegmentLength, Spec
+from ..models.resolve import TechScore
+from .assign import AssignmentResult, best_assignment
+from .evaluators import Outcome, evaluate, onlist_admits_over_length, read_length_compatible
+from .window import WindowProbe
+
+_LAMBDA = 0.25  # penalty per unassigned (leftover) file, cardinality-normalized
+_BETA = 0.01  # filename-prior coefficient (<< min support weight -> tie-break only)
+_GLOBAL_COEF = 0.001  # tech-global supports (header_index) contribute a sub-threshold tie-break
+
+
+@dataclass(frozen=True)
+class Cell:
+    """One evidence-matrix cell: forbidden, or a finite support value in ``[0, 1]``."""
+
+    forbidden: bool
+    value: float
+    reason: str = ""
+
+    def to_json(self) -> dict[str, object]:
+        if self.forbidden:
+            return {"status": "forbidden", "reason": self.reason}
+        return {"status": "scored", "value": round(self.value, 4)}
+
+
+@dataclass(frozen=True)
+class TechEvaluation:
+    """The full scored verdict for one technology against the dataset's files."""
+
+    tech: str
+    roles: list[str]
+    file_shas: list[str]
+    matrix: dict[str, list[Cell]]
+    assignment: AssignmentResult
+    score: TechScore
+    rung: int
+    used_onlist: bool
+    equivalence_members: list[str]
+    barcode_role_ids: list[str]
+    unfillable_role_ids: list[str]
+    cdna_role_fillable: bool
+    #: A barcode role's onlist POSITIVELY hit — the whitelist actually identified barcodes in the data
+    #: (best hit clears the floor-anchored admission bar), not merely that an onlist was consulted. This
+    #: is the honest "this data IS barcoded" signal escalate uses so the barcodeless bulk fallback never
+    #: shadows a real single-cell library, WITHOUT hijacking genuine bulk (whose barcode window sits at
+    #: the whitelist floor, so this stays False even when a barcode read passes on over-length geometry).
+    barcode_onlist_hit: bool = False
+    #: A barcode role's onlist whitelist was REGISTERED and materializable — we had a list to check
+    #: against. Lets F1b (escalate) tell "checked, missed" (refuse) from "never checked" (abstain).
+    barcode_onlist_available: bool = False
+
+    @property
+    def valid(self) -> bool:
+        return self.score.status == "scored"
+
+    @property
+    def value(self) -> float:
+        return self.score.value if self.score.value is not None else float("-inf")
+
+    def role_assignment_shas(self) -> dict[str, str]:
+        """role_id -> file sha256 for the winning assignment (empty if forbidden)."""
+        return {self.roles[r]: self.file_shas[f] for r, f in self.assignment.mapping.items()}
+
+    def matrix_json(self) -> dict[str, dict[str, dict[str, object]]]:
+        """JSON-safe evidence matrix: ``{role: {file_sha: {status, ...}}}`` — no ``±inf``."""
+        out: dict[str, dict[str, dict[str, object]]] = {}
+        for role, cells in self.matrix.items():
+            out[role] = {self.file_shas[f]: cells[f].to_json() for f in range(len(cells))}
+        return out
+
+
+def filename_prior(read: Read, basename: str) -> float:
+    """1.0 if the file's name carries the read's conventional token (``_R1_`` -> ``R1``), else 0.0."""
+    if not read.file_hint:
+        return 0.0
+    token = read.file_hint.strip("_")
+    return 1.0 if token and token in basename else 0.0
+
+
+def _score_cell(
+    read: Read,
+    wp: WindowProbe,
+    spec: Spec,
+    registry: OnlistRegistry,
+    requires: list[object],
+    excludes: list[object],
+    supports: list[tuple[object, float]],
+) -> tuple[Cell, bool]:
+    used_onlist = False
+    if read_length_compatible(read, wp) == Outcome.FAIL:
+        reason = (
+            f"read-length incompatible (mode {wp.mode_length} vs {read.min_len}..{read.max_len})"
+        )
+        return Cell(forbidden=True, value=0.0, reason=reason), used_onlist
+    for t in requires:
+        ev = evaluate(t, read, wp, spec, registry)
+        used_onlist = used_onlist or ev.used_onlist
+        if ev.outcome == Outcome.FAIL:
+            # A `segment_length` FAIL in the over-length DEAD ZONE (canonical < mode < over_length_min)
+            # is not necessarily a wrong read: an R1 over-sequenced to e.g. 75 bp is a real barcode
+            # read whose CB/UMI still sit at the fixed offsets — over_length_min is deliberately high
+            # (100) so a 60-94 bp cDNA is not admitted on length alone. The WHITELIST is the
+            # disambiguator: a genuine cDNA of the same length misses it, a real barcode hits it. So if
+            # the barcode onlist hits, admit as over-length (rung 3); else keep the FAIL. This is the
+            # one place a rung-3 result overrides a rung-0-2 length gate, and it only ever ADMITS
+            # (#7 — GSE126954's over-sequenced SRX5411291, which the v2 length gate otherwise forbids).
+            if _over_length_admitted_by_onlist(t, read, wp, spec, registry, supports):
+                used_onlist = True
+                continue
+            return Cell(
+                forbidden=True, value=0.0, reason=f"requires FAIL: {ev.detail}"
+            ), used_onlist
+    for t in excludes:
+        ev = evaluate(t, read, wp, spec, registry)
+        used_onlist = used_onlist or ev.used_onlist
+        if ev.outcome == Outcome.PASS:
+            return Cell(
+                forbidden=True, value=0.0, reason=f"excludes matched: {ev.detail}"
+            ), used_onlist
+    total_w = sum(w for _, w in supports)
+    value = 0.0
+    if total_w > 0:
+        acc = 0.0
+        for when, weight in supports:
+            ev = evaluate(when, read, wp, spec, registry)
+            used_onlist = used_onlist or ev.used_onlist
+            acc += weight * ev.score
+        value = acc / total_w
+    return Cell(forbidden=False, value=value, reason="scored"), used_onlist
+
+
+def _over_length_admitted_by_onlist(
+    test: object,
+    read: Read,
+    wp: WindowProbe,
+    spec: Spec,
+    registry: OnlistRegistry,
+    supports: list[tuple[object, float]],
+) -> bool:
+    """Admit a barcode read over-sequenced into the length dead zone IFF its barcode prefix hits the
+    whitelist. Deliberately narrow and additive: it fires ONLY on a ``segment_length`` FAIL whose mode
+    is strictly between the canonical ``length`` and ``over_length_min`` (a read at/below the canonical
+    length, or already ``>= over_length_min``, does not reach here), and ONLY when an ``onlist_hit_rate``
+    support clears the FLOOR-ANCHORED admission bar (:func:`onlist_admits_over_length`) — a LOWER bar
+    than the support's own ``min`` PASS threshold, because admission asks "barcode or cDNA?" not
+    "confident barcode?", so it can admit a read whose exact hit rate sits below ``min`` yet far above
+    chance. A cDNA read of the same length hits the whitelist at its floor and stays forbidden, so
+    rung-0-2 separability between single-cell and cDNA-only chemistries is preserved.
+    """
+    if not isinstance(test, SegmentLength) or test.over_length_min is None:
+        return False
+    if not (test.length < wp.mode_length < test.over_length_min):
+        return False  # not the dead zone: canonical is exact-checked, >= over_length_min already PASSes
+    for when, _weight in supports:
+        # A FLOOR-ANCHORED bar, not the support `min`: admission asks "barcode or cDNA?", not
+        # "confident barcode?". Seqforge matches exactly (no 1MM correction), so a real over-sequenced
+        # barcode read with ordinary error hits below the 0.6 support gate yet far above chance -- the
+        # gate rejected SRX5411291 and it fell to bulk. See `onlist_admits_over_length`.
+        if isinstance(when, OnlistHitRate) and onlist_admits_over_length(
+            when, read, wp, spec, registry
+        ):
+            return True
+    return False
+
+
+def _clears_onlist_bar(
+    read: Read,
+    wp: WindowProbe,
+    supports: list[tuple[object, float]],
+    spec: Spec,
+    registry: OnlistRegistry,
+) -> bool:
+    """True iff some onlist support for this barcode ``read`` clears the floor-anchored admission bar on
+    ``wp`` — the file's barcode prefix hits the whitelist far above the ~1e-4..1e-3 random floor, i.e.
+    this read LOOKS barcoded. The predicate both the F1a seating constraint and ``barcode_onlist_hit``
+    are built from."""
+    return any(
+        isinstance(when, OnlistHitRate)
+        and onlist_admits_over_length(when, read, wp, spec, registry)
+        for when, _w in supports
+    )
+
+
+def _barcode_onlist_available(
+    spec: Spec,
+    registry: OnlistRegistry,
+    barcode_role_ids: list[str],
+    sup_by: dict[str, list[tuple[object, float]]],
+) -> bool:
+    """True iff at least one barcode role's onlist whitelist is REGISTERED and materializable — we had a
+    list to check against. When False the whitelist was never consulted, so a ``barcode_onlist_hit`` of
+    False means 'could not check', not 'barcode absent': F1b must abstain, not refuse."""
+    for rid in barcode_role_ids:
+        for when, _w in sup_by[rid]:
+            if not isinstance(when, OnlistHitRate):
+                continue
+            ref = spec.onlists.get(when.onlist)
+            if ref is None or not registry.has(ref.registry):
+                continue
+            try:
+                registry.packed(ref.registry)
+            except OnlistNotAvailable:
+                continue
+            return True
+    return False
+
+
+def _global_support(
+    global_supports: list[tuple[object, float]],
+    reads: list[Read],
+    wps: list[WindowProbe],
+    spec: Spec,
+    registry: OnlistRegistry,
+) -> float:
+    """Normalized score of read-less supports (e.g. ``header_index``), max over files."""
+    if not global_supports or not wps:
+        return 0.0
+    total_w = sum(w for _, w in global_supports)
+    if total_w <= 0:
+        return 0.0
+    acc = 0.0
+    for when, weight in global_supports:
+        best = max(evaluate(when, reads[0], wp, spec, registry).score for wp in wps)
+        acc += weight * best
+    return acc / total_w
+
+
+def build_tech_evaluation(
+    spec: Spec, wps: list[WindowProbe], registry: OnlistRegistry
+) -> TechEvaluation:
+    """Score one technology against the dataset's files (the evidence matrix + joint assignment)."""
+    reads_by_id = {r.id: r for r in spec.reads}
+    roles = [r.id for r in spec.reads]
+    n_files = len(wps)
+    file_shas = [wp.observation.file.sha256 for wp in wps]
+    barcode_role_ids = [r.id for r in spec.reads if any(el.type == "barcode" for el in r.elements)]
+
+    req_by: dict[str, list[object]] = defaultdict(list)
+    exc_by: dict[str, list[object]] = defaultdict(list)
+    sup_by: dict[str, list[tuple[object, float]]] = defaultdict(list)
+    global_sup: list[tuple[object, float]] = []
+    for t in spec.signature.requires:
+        rid = getattr(t, "read", None)
+        if rid is not None:
+            req_by[rid].append(t)
+    for t in spec.signature.excludes:
+        rid = getattr(t, "read", None)
+        if rid is not None:
+            exc_by[rid].append(t)
+    for s in spec.signature.supports:
+        rid = getattr(s.when, "read", None)
+        if rid is not None:
+            sup_by[rid].append((s.when, s.weight))
+        else:
+            global_sup.append((s.when, s.weight))
+
+    matrix: dict[str, list[Cell]] = {}
+    score_m: list[list[float]] = []
+    forbidden_m: list[list[bool]] = []
+    prior_m: list[list[float]] = []
+    used_onlist = False
+    for rid in roles:
+        read = reads_by_id[rid]
+        cells: list[Cell] = []
+        row_score: list[float] = []
+        row_forbid: list[bool] = []
+        row_prior: list[float] = []
+        for wp in wps:
+            cell, uo = _score_cell(read, wp, spec, registry, req_by[rid], exc_by[rid], sup_by[rid])
+            used_onlist = used_onlist or uo
+            cells.append(cell)
+            row_score.append(cell.value)
+            row_forbid.append(cell.forbidden)
+            row_prior.append(_BETA * filename_prior(read, wp.observation.file.basename))
+        matrix[rid] = cells
+        score_m.append(row_score)
+        forbidden_m.append(row_forbid)
+        prior_m.append(row_prior)
+
+    # F1a — a barcode role must be seated on a read that LOOKS barcoded. Per barcode role, which files
+    # clear the floor-anchored onlist bar (prefix hits the whitelist far above chance)? Computed once and
+    # reused for the seating constraint here and for the `barcode_onlist_hit` signal below.
+    barcode_clears: dict[str, list[bool]] = {
+        rid: [_clears_onlist_bar(reads_by_id[rid], wp, sup_by[rid], spec, registry) for wp in wps]
+        for rid in barcode_role_ids
+    }
+    # When some file clears, forbid seating the role on any file that does NOT — so sum-maximization
+    # cannot park the barcode role on a cDNA-length mate that merely out-scored the real barcode read on
+    # other supports. The swap it prevents: a real barcode read carrying ordinary sequencing error can
+    # score higher as cDNA than as its own barcode, and the true cDNA read of a low-diversity library
+    # scores low on both roles, so `(barcode->cDNA)+(cDNA->barcode)` beats the honest seat (PRJNA658829
+    # SRR12575567). A file that clears the bar is always a barcode — a real cDNA hits the whitelist at the
+    # ~1e-4..1e-3 random floor, far below the bar — so forcing a clearing read into barcode is never
+    # wrong. No file clearing => a no-op here; escalate's F1b then refuses rather than compose a barcode
+    # read that matches no whitelist.
+    for rid, clears in barcode_clears.items():
+        if not any(clears):
+            continue
+        ri = roles.index(rid)
+        for f in range(n_files):
+            if not clears[f] and not forbidden_m[ri][f]:
+                forbidden_m[ri][f] = True
+                matrix[rid][f] = Cell(
+                    forbidden=True,
+                    value=0.0,
+                    reason="barcode role: another read hits the onlist and this one does not",
+                )
+
+    assignment = best_assignment(len(roles), n_files, score_m, forbidden_m, prior_m)
+    global_bonus = _global_support(global_sup, list(reads_by_id.values()), wps, spec, registry)
+
+    # Did a barcode role's onlist actually hit (not just get consulted)? True iff some file cleared the
+    # floor-anchored admission bar above (reusing F1a's `barcode_clears`) — the "this data is barcoded"
+    # signal escalate uses to keep the barcodeless fallback from shadowing a real single-cell library,
+    # and to refuse (F1b) when a barcoded winner has no whitelist-hitting read. Genuine bulk sits at the
+    # whitelist floor and stays False even when its read passes over-length geometry.
+    barcode_onlist_hit = any(any(clears) for clears in barcode_clears.values())
+    barcode_onlist_available = _barcode_onlist_available(spec, registry, barcode_role_ids, sup_by)
+    unfillable_role_ids = [roles[i] for i in assignment.unfillable_roles]
+    cdna_role_fillable = any(
+        any(el.type in ("cdna", "gdna") for el in reads_by_id[rid].elements)
+        and any(not c.forbidden for c in matrix[rid])
+        for rid in roles
+    )
+
+    if assignment.valid:
+        raw_norm = assignment.raw / len(roles)
+        penalty = (_LAMBDA / len(roles)) * len(assignment.unassigned_files)
+        value = raw_norm - penalty + _GLOBAL_COEF * global_bonus
+        score = TechScore(technology=spec.identity.id, status="scored", value=round(value, 6))
+    else:
+        reason = (
+            f"unfillable role(s): {unfillable_role_ids}"
+            if unfillable_role_ids
+            else "no valid injective role assignment"
+        )
+        score = TechScore(technology=spec.identity.id, status="forbidden", reason=reason)
+
+    equivalence = [c.id for c in spec.confusable_with if c.relationship == "processing_equivalent"]
+    return TechEvaluation(
+        tech=spec.identity.id,
+        roles=roles,
+        file_shas=file_shas,
+        matrix=matrix,
+        assignment=assignment,
+        score=score,
+        rung=3 if used_onlist else 2,
+        used_onlist=used_onlist,
+        equivalence_members=equivalence,
+        barcode_role_ids=barcode_role_ids,
+        unfillable_role_ids=unfillable_role_ids,
+        cdna_role_fillable=cdna_role_fillable,
+        barcode_onlist_hit=barcode_onlist_hit,
+        barcode_onlist_available=barcode_onlist_available,
+    )

seqforge/resolve/window.py

@@ -0,0 +1,206 @@
+"""``WindowProbe`` — the bounded, role-conditioned view the resolver scores against (§3.1).
+
+The structural :class:`Observation` is deliberately role-free and carries no raw sequences, but the
+resolver needs role-conditioned answers — distinct-ratio and onlist hit-rate over *arbitrary*
+``[start, end)`` windows a candidate technology proposes. ``WindowProbe`` pairs the Observation with
+the same bounded, in-memory sample that produced it (from :func:`probe.probe_sample`) and answers
+those window queries. It never re-reads the file: the sample is already within the budget.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from ..io import HitResult, Orientation, PackedOnlist, onlist_hit_rate
+from ..io.onlist import pack_barcode, revcomp
+from ..kb.schema import Read
+from ..models.observation import CycleComposition, Observation
+
+_IUPAC = {
+    "A": "A", "C": "C", "G": "G", "T": "T",
+    "R": "AG", "Y": "CT", "S": "GC", "W": "AT", "K": "GT", "M": "AC",
+    "B": "CGT", "D": "AGT", "H": "ACT", "V": "ACG", "N": "ACGT",
+}  # fmt: skip
+
+
+@dataclass(frozen=True)
+class WindowProbe:
+    """An Observation plus its bounded sampled sequences, queryable over arbitrary windows.
+
+    Most windows are a fixed ``[start, end)`` column. **Anchored** (floating) elements are not — their
+    per-read position is recovered by :func:`seqforge.kb.anchor.resolve_windows`, and the
+    ``anchored_*`` methods answer distinct-ratio / onlist-hit over those per-read frames instead. The
+    full per-read frame is resolved once and memoized (``_frame_cache``, keyed by the ``Read`` object)
+    so scoring three cell-label blocks on one read does not realign it three times.
+    """
+
+    observation: Observation
+    seqs: list[str]
+    #: read object identity -> per-sampled-read resolved element windows (``None`` where the frame was
+    #: not found). Mutated in place; the frozen dataclass forbids rebinding the attribute, not filling
+    #: the dict. ``compare=False`` so two probes with equal seqs stay equal regardless of what was cached.
+    _frame_cache: dict[int, list[dict[str, tuple[int, int]] | None]] = field(
+        default_factory=dict, compare=False, repr=False
+    )
+
+    @property
+    def n_sampled(self) -> int:
+        return len(self.seqs)
+
+    def _frames(self, read: Read) -> list[dict[str, tuple[int, int]] | None]:
+        """Per-read resolved element windows for an anchored layout, memoized per ``Read``."""
+        key = id(read)
+        cached = self._frame_cache.get(key)
+        if cached is None:
+            from ..kb.anchor import resolve_windows
+
+            cached = [resolve_windows(s, read) for s in self.seqs]
+            self._frame_cache[key] = cached
+        return cached
+
+    def anchored_windows(self, read: Read, element_name: str) -> list[tuple[int, int] | None]:
+        """The per-read ``[start, end)`` of one floating element (``None`` where the frame was lost)."""
+        return [f.get(element_name) if f is not None else None for f in self._frames(read)]
+
+    def anchored_distinct_ratio(self, read: Read, element_name: str) -> float | None:
+        """``distinct/total`` of a floating element's per-read slices; ``None`` if no frame resolved."""
+        windows = self.anchored_windows(read, element_name)
+        slices = [
+            self.seqs[i][s:e] for i, w in enumerate(windows) if w is not None for s, e in (w,)
+        ]
+        slices = [s for s in slices if s]
+        if not slices:
+            return None
+        return len(set(slices)) / len(slices)
+
+    def anchored_onlist_hit(
+        self,
+        read: Read,
+        element_name: str,
+        onlist: PackedOnlist,
+        orientation: Orientation = "either",
+    ) -> HitResult:
+        """Whitelist hit-rate of a floating element, sliced per read at its resolved frame.
+
+        The anchored twin of :func:`~seqforge.io.onlist.onlist_hit_rate`: no offset scan (the frame IS
+        the offset), forward and/or reverse-complement per ``orientation``. ``n_tested`` counts reads
+        whose frame resolved to a window of the onlist's width; a lost frame simply does not contribute.
+        """
+        windows = self.anchored_windows(read, element_name)
+        strands = (
+            ["forward"]
+            if orientation == "forward"
+            else ["revcomp"]
+            if orientation == "revcomp"
+            else ["forward", "revcomp"]
+        )
+        best = HitResult(
+            hit_rate=0.0, orientation="forward", offset=0, n_tested=0, floor=onlist.floor
+        )
+        for strand in strands:
+            tested = 0
+            hits = 0
+            for i, w in enumerate(windows):
+                if w is None:
+                    continue
+                sub = self.seqs[i][w[0] : w[1]]
+                if len(sub) != onlist.width:
+                    continue
+                tested += 1
+                code = pack_barcode(revcomp(sub) if strand == "revcomp" else sub)
+                if code is not None and onlist.contains(code):
+                    hits += 1
+            if tested and hits / tested > best.hit_rate:
+                best = HitResult(
+                    hit_rate=hits / tested,
+                    orientation=strand,  # type: ignore[arg-type]
+                    offset=0,
+                    n_tested=tested,
+                    floor=onlist.floor,
+                )
+        return best
+
+    @property
+    def mode_length(self) -> int:
+        return self.observation.read_length.mode
+
+    def distinct_ratio(self, start: int, end: int) -> float | None:
+        """``distinct/total`` over ``[start, end)`` (role-conditioned; a supports signal, never a gate)."""
+        window = [s[start:end] for s in self.seqs if len(s) >= end]
+        if not window:
+            return None
+        return len(set(window)) / len(window)
+
+    def composition_window(self, start: int, end: int | None) -> list[CycleComposition]:
+        """Per-cycle composition over cycles ``[start, end)`` (``end=None`` => to the longest read)."""
+        comps = self.observation.per_cycle_composition
+        stop = len(comps) if end is None else min(end, len(comps))
+        return [c for c in comps[start:stop]]
+
+    def onlist_hit(
+        self, start: int, onlist: PackedOnlist, orientation: Orientation = "either"
+    ) -> HitResult:
+        """Best whitelist hit anchored at ``start`` (width from the onlist), fwd + revcomp + offset scan."""
+        return onlist_hit_rate(self.seqs, start, onlist, orientation=orientation)
+
+    def motif_rate(
+        self,
+        motif: str,
+        *,
+        where: str = "anywhere",
+        search_start: int | None = None,
+        search_end: int | None = None,
+        max_mismatch: int = 1,
+    ) -> float | None:
+        """Fraction of reads matching an IUPAC ``motif`` (<= ``max_mismatch``) in the search window."""
+        m = len(motif)
+        if m == 0:
+            return None
+        tested = 0
+        matched = 0
+        for seq in self.seqs:
+            if len(seq) < m:
+                continue
+            tested += 1
+            if self._read_has_motif(seq, motif, where, search_start, search_end, max_mismatch):
+                matched += 1
+        if tested == 0:
+            return None
+        return matched / tested
+
+    @staticmethod
+    def _read_has_motif(
+        seq: str,
+        motif: str,
+        where: str,
+        search_start: int | None,
+        search_end: int | None,
+        max_mismatch: int,
+    ) -> bool:
+        m = len(motif)
+        if where == "read_start":
+            starts = [0]
+        elif where == "read_end":
+            starts = [len(seq) - m]
+        elif where == "window":
+            lo = search_start or 0
+            hi = search_end if search_end is not None else len(seq) - m
+            starts = list(range(lo, hi + 1))
+        else:  # anywhere
+            starts = list(range(0, len(seq) - m + 1))
+        for pos in starts:
+            if pos < 0 or pos + m > len(seq):
+                continue
+            if _motif_matches(seq[pos : pos + m], motif, max_mismatch):
+                return True
+        return False
+
+
+def _motif_matches(window: str, motif: str, max_mismatch: int) -> bool:
+    mism = 0
+    for base, code in zip(window, motif, strict=True):
+        if base not in _IUPAC.get(code, code):
+            mism += 1
+            if mism > max_mismatch:
+                return False
+    return True