seqtree 0.6.0__tar.gz → 0.7.0__tar.gz

{seqtree-0.6.0 → seqtree-0.7.0}/CHANGELOG.md

@@ -3,6 +3,63 @@
 All notable changes to `seqtree`. Dates are release dates; the project is pre-1.0, so a **minor**
 bump may carry breaking changes.
 
+## [0.7.0] — 2026-08-16
+
+### Added
+
+- **`seqtree.distance` now enumerates a Hamming ball, not just scores one.**
+  `neighbourhood(seq, r=1, alphabet=None, include_self=True, shell=False)` lists the members of
+  the closed ball (`19·L + 1` at `r = 1` over the 20 standard residues);
+  `neighbourhood_union(seqs, ...)` takes the union over many centres, emitting each distinct
+  sequence **once**; `union_size(seqs, ...)` returns the cardinality without building or sorting
+  the result list. `shell=True` returns the sphere at exactly `r` from the *nearest* centre —
+  a per-shell quantity has to be estimated per shell.
+
+  Substitution only, fixed length: Hamming distance is undefined across lengths (`hamming`
+  already raises), and indels are `gapblock`'s problem. Deduplication happens during a
+  multi-source breadth-first walk, so the `Σ 19·L_i` multiset is never materialised — which is
+  the point, since near-duplicate centres overlap heavily. For 200 length-14 junctions all within
+  distance 1 of a common centre, the per-sequence balls double-count **41.7%** (53,400 → 31,122);
+  at spread 2, 4.5%; at spread ≥ 3, nothing.
+
+  Pure Python, measured before being written in C++: 300 junctions of length 14 at `r = 1` is
+  80,100 distinct sequences in **23 ms** on one M3 core (11 ms for `union_size`). `r = 2` over
+  the same input is 9.9 M sequences, 6.8 s and ~1.8 GB.
+
+  `alphabet=None` defaults to the 20 standard amino acids — `amino_acids()` **minus** the
+  ambiguity codes `B`/`Z`/`X` and the stop `*`, which that function does include.
+
+  Shells **partition** the closed ball exactly: shells `0..r` are pairwise disjoint, their union
+  is the ball, and every member sits at distance exactly `d` from its *nearest* centre. A
+  per-shell quantity therefore sums back to the per-ball one. Pinned by a test that checks the
+  distance with the C++ `hamming`, not with the generator's own bookkeeping.
+
+  `neighbourhood_union` and `union_size` **raise `TypeError` on a single string** rather than
+  iterating it. A `str` is iterable, so `union_size("CASSLGQYF")` would otherwise take the
+  sequence's 8 distinct *characters* as the centres and answer `20` instead of `172` — a
+  plausible integer, no error, no way to notice. Pass `["CASSLGQYF"]`, or call `neighbourhood`.
+
+- **`seqtree.__version__`.** Read from the installed distribution metadata, so `pyproject.toml`'s
+  `project.version` is the single source and a release that bumps it cannot leave a stale literal
+  behind. Asserted against the distribution metadata *and* against `pyproject.toml` by a test.
+
+### Fixed
+
+- **The documentation build stamped every page `0.6.1` while the package was `0.7.0`.**
+  `docs/conf.py` hand-copied the version into `release`/`version` and the 0.7.0 bump touched only
+  `pyproject.toml`. Both now read `seqtree.__version__`, which the docs job already installs.
+
+## [0.6.1] — 2026-07-30
+
+### Fixed
+
+- **`gapblock_matrix`'s out-of-alphabet error named only the bad symbol**, not which sequence it
+  came from (`"symbol '_' is not in the alphabet"`) — unhelpful when a single malformed row (e.g.
+  a `junction_aa` containing a legacy out-of-frame marker) is buried in a batch of hundreds of
+  thousands. The message now names the side, index, and offending string:
+  `"queries[42] ('CASSIRS_YEQYF'): symbol '_' is not in the alphabet"`. No change to which symbols
+  are accepted (still the standard 20 + B/Z/X/* for `alphabet="aa"`).
+
 ## [0.6.0] — 2026-07-17
 
 ### Fixed

{seqtree-0.6.0 → seqtree-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: seqtree
-Version: 0.6.0
+Version: 0.7.0
 Summary: Fast fuzzy search over biological sequences (C++ core, Python bindings)
 Keywords: sequence-search,fuzzy-matching,CDR3,immunology,bioinformatics,trie
 Author-Email: ISALGO laboratory <mikhail.shugay@gmail.com>
@@ -94,7 +94,11 @@ Beyond search, seqtree ships:
   `hamming_matrix` / `levenshtein_matrix` score a whole set against a whole set in one GIL-released
   C++ call (`numpy.asarray` wraps the result with no copy) — no `python-Levenshtein` or `rapidfuzz`
   dependency needed. Hamming requires equal lengths (it raises otherwise); comparison is
-  case-sensitive.
+  case-sensitive. The same module *enumerates* a Hamming ball as well as scoring one:
+  `neighbourhood(seq, r)` lists its `19·L + 1` members, and `neighbourhood_union(seqs, r)` takes
+  the union over many centres with each distinct sequence emitted **once** — deduplicated during
+  the walk, so the `Σ 19·L_i` multiset never exists. For a tight specificity group that is a 41.7%
+  saving, not a rounding correction.
 - **Island profiles** — `IslandProfile.fit` builds a position weight matrix over a set of
   frame-aligned junctions (an *island*) and scores a query column by column against the island
   consensus, as a non-negative penalty that flows through `threshold_for_evalue` unchanged. At a
@@ -114,8 +118,11 @@ needs a C++17 compiler and CMake (pulled in automatically by the build).
 
 ## Build from source
 
+Needs [uv](https://docs.astral.sh/uv/) (`brew install uv`); `setup.sh` uses it for the venv and
+the editable install.
+
 ```fish
-bash setup.sh            # repo-local .venv + editable install
+bash setup.sh            # uv-managed .venv + editable install
 bash setup.sh --tests    # + pytest
 bash setup.sh --bench     # + benchmark deps (huggingface_hub, psutil)
 ```
@@ -193,6 +200,13 @@ from seqtree.distance import hamming, levenshtein, hamming_matrix, levenshtein_m
 hamming("CASSLGQYF", "CASSPGQYF")                             # 1  (equal length only)
 levenshtein("kitten", "sitting")                             # 3
 h = np.asarray(hamming_matrix(umis, umis, threads=0))        # (len, len) int32, zero-copy
+
+# enumerate the ball, deduplicated across centres (substitution only, fixed length)
+from seqtree.distance import neighbourhood, neighbourhood_union, union_size
+neighbourhood("CASSLGQYF")                                   # 172 = 19*9 + 1
+union_size(junctions)                                        # size the job before running it
+for variant in neighbourhood_union(junctions, r=1):          # each distinct sequence once
+    ...
 ```
 
 ## Tests

{seqtree-0.6.0 → seqtree-0.7.0}/README.md

@@ -60,7 +60,11 @@ Beyond search, seqtree ships:
   `hamming_matrix` / `levenshtein_matrix` score a whole set against a whole set in one GIL-released
   C++ call (`numpy.asarray` wraps the result with no copy) — no `python-Levenshtein` or `rapidfuzz`
   dependency needed. Hamming requires equal lengths (it raises otherwise); comparison is
-  case-sensitive.
+  case-sensitive. The same module *enumerates* a Hamming ball as well as scoring one:
+  `neighbourhood(seq, r)` lists its `19·L + 1` members, and `neighbourhood_union(seqs, r)` takes
+  the union over many centres with each distinct sequence emitted **once** — deduplicated during
+  the walk, so the `Σ 19·L_i` multiset never exists. For a tight specificity group that is a 41.7%
+  saving, not a rounding correction.
 - **Island profiles** — `IslandProfile.fit` builds a position weight matrix over a set of
   frame-aligned junctions (an *island*) and scores a query column by column against the island
   consensus, as a non-negative penalty that flows through `threshold_for_evalue` unchanged. At a
@@ -80,8 +84,11 @@ needs a C++17 compiler and CMake (pulled in automatically by the build).
 
 ## Build from source
 
+Needs [uv](https://docs.astral.sh/uv/) (`brew install uv`); `setup.sh` uses it for the venv and
+the editable install.
+
 ```fish
-bash setup.sh            # repo-local .venv + editable install
+bash setup.sh            # uv-managed .venv + editable install
 bash setup.sh --tests    # + pytest
 bash setup.sh --bench     # + benchmark deps (huggingface_hub, psutil)
 ```
@@ -159,6 +166,13 @@ from seqtree.distance import hamming, levenshtein, hamming_matrix, levenshtein_m
 hamming("CASSLGQYF", "CASSPGQYF")                             # 1  (equal length only)
 levenshtein("kitten", "sitting")                             # 3
 h = np.asarray(hamming_matrix(umis, umis, threads=0))        # (len, len) int32, zero-copy
+
+# enumerate the ball, deduplicated across centres (substitution only, fixed length)
+from seqtree.distance import neighbourhood, neighbourhood_union, union_size
+neighbourhood("CASSLGQYF")                                   # 172 = 19*9 + 1
+union_size(junctions)                                        # size the job before running it
+for variant in neighbourhood_union(junctions, r=1):          # each distinct sequence once
+    ...
 ```
 
 ## Tests

{seqtree-0.6.0 → seqtree-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "scikit_build_core.build"
 
 [project]
 name = "seqtree"
-version = "0.6.0"
+version = "0.7.0"
 description = "Fast fuzzy search over biological sequences (C++ core, Python bindings)"
 readme = "README.md"
 requires-python = ">=3.10"

{seqtree-0.6.0 → seqtree-0.7.0}/python/seqtree/__init__.py

@@ -9,6 +9,8 @@ it ignores the per-type caps). Payload-agnostic: results are
 For anchored loops (CDR3 / junction), :mod:`seqtree.gapblock` restricts the alignment
 to one contiguous indel and picks its position with a gap prior.
 """
+from importlib.metadata import version as _distribution_version
+
 from ._core import (
     Index,
     SearchParams,
@@ -32,6 +34,11 @@ from .gapblock import (
 from .seeds import SeedIndex, core_kmers
 from .pmhc import PMHCStore, find_mimics
 
+#: Read from the installed distribution metadata, so ``pyproject.toml``'s ``project.version``
+#: is the single source. A hand-copied literal here would silently drift from the version
+#: actually published to PyPI.
+__version__ = _distribution_version("seqtree")
+
 __all__ = [
     "distance",
     "gapblock",

seqtree-0.7.0/python/seqtree/distance.py

@@ -0,0 +1,282 @@
+"""Plain string edit distances: Hamming and Levenshtein, in C++, without a dependency.
+
+These are the *unweighted* distances -- unit costs, no substitution matrix, no gap model, no
+alphabet. That is the whole point: when all you need is "how many edits apart are these two
+strings", you should not have to build an :class:`~seqtree.SubstitutionMatrix` or reach for
+``python-Levenshtein`` / ``rapidfuzz``. seqtree still needs nothing at runtime.
+
+* :func:`hamming` -- number of differing positions; defined only for **equal-length** sequences,
+  and raises :class:`ValueError` otherwise;
+* :func:`levenshtein` -- the classic insertion / deletion / substitution edit distance, each edit
+  costing 1;
+* :func:`hamming_matrix` / :func:`levenshtein_matrix` -- every ``a`` against every ``b`` in one
+  GIL-released, multi-threaded C++ call, returned as a zero-copy :class:`~seqtree.ScoreMatrix`.
+
+The same module also *enumerates* a Hamming ball rather than scoring a pair you already hold:
+
+* :func:`neighbourhood` -- every sequence within ``r`` substitutions of one centre;
+* :func:`neighbourhood_union` -- the same over **many** centres, each distinct sequence emitted
+  once. Deduplication happens during generation, never as a pass over the ``sum(19*L_i)``
+  multiset;
+* :func:`union_size` -- the cardinality alone, for sizing a job before running it.
+
+Comparison is **case-sensitive**, byte for byte -- unlike the search engines, which fold case.
+For a *weighted* alignment (a substitution matrix, affine gaps, local mode), use
+:mod:`seqtree.pairwise` instead.
+
+Example:
+    >>> from seqtree.distance import hamming, levenshtein, union_size
+    >>> hamming("CASSLGQYF", "CASSPGQYF")
+    1
+    >>> levenshtein("kitten", "sitting")
+    3
+    >>> union_size(["CASSLGQYF", "CASSPGQYF"])      # 2 * 172 balls, 20 sequences shared
+    324
+"""
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+
+from ._core import ScoreMatrix
+from ._core import amino_acids as _amino_acids
+from ._core import hamming as _hamming
+from ._core import hamming_matrix as _hamming_matrix
+from ._core import levenshtein as _levenshtein
+from ._core import levenshtein_matrix as _levenshtein_matrix
+
+__all__ = ["hamming", "levenshtein", "hamming_matrix", "levenshtein_matrix",
+           "neighbourhood", "neighbourhood_union", "union_size"]
+
+#: The 20 standard residues: :func:`~seqtree.amino_acids` minus the ambiguity codes ``B``/``Z``/
+#: ``X`` and the stop ``*``, none of which is a substitution anybody means.
+_STANDARD_AA = "".join(c for c in _amino_acids() if c not in "BZX*")
+
+
+def hamming(a: str, b: str) -> int:
+    """Number of positions at which ``a`` and ``b`` differ.
+
+    Args:
+        a: First sequence.
+        b: Second sequence, of the **same length** as ``a``.
+
+    Returns:
+        The count of differing positions (0 when identical).
+
+    Raises:
+        ValueError: If ``a`` and ``b`` have different lengths -- Hamming distance is undefined
+            for unequal lengths; use :func:`levenshtein` for that.
+
+    Example:
+        >>> hamming("AAAA", "AAAA")
+        0
+        >>> hamming("AAAA", "ATAT")
+        2
+    """
+    return _hamming(a, b)
+
+
+def levenshtein(a: str, b: str) -> int:
+    """Edit distance: fewest single-character insert / delete / substitute steps from ``a`` to ``b``.
+
+    Args:
+        a: First sequence.
+        b: Second sequence; may be any length.
+
+    Returns:
+        The edit distance (0 when identical, ``max(len(a), len(b))`` at most).
+
+    Example:
+        >>> levenshtein("flaw", "lawn")
+        2
+        >>> levenshtein("CASSLGQAYEQYF", "CASSPGQAYEQF")
+        2
+    """
+    return _levenshtein(a, b)
+
+
+def hamming_matrix(a: Sequence[str], b: Sequence[str], threads: int = 0) -> ScoreMatrix:
+    """Hamming distance of every ``a`` against every ``b``, in parallel C++.
+
+    Args:
+        a: Query sequences (the rows).
+        b: Reference sequences (the columns).
+        threads: Worker threads; ``0`` uses all cores.
+
+    Returns:
+        A :class:`~seqtree.ScoreMatrix` of shape ``(len(a), len(b))`` of int32 distances.
+        ``numpy.asarray`` wraps it without copying.
+
+    Raises:
+        ValueError: If any ``(a[i], b[k])`` pair has mismatched lengths.
+
+    Example:
+        >>> import numpy as np
+        >>> d = np.asarray(hamming_matrix(["AAAA", "AAAT"], ["AAAA", "TTTT"]))
+        >>> d.tolist()
+        [[0, 4], [1, 3]]
+    """
+    return _hamming_matrix(list(a), list(b), threads=threads)
+
+
+def levenshtein_matrix(a: Sequence[str], b: Sequence[str], threads: int = 0) -> ScoreMatrix:
+    """Levenshtein distance of every ``a`` against every ``b``, in parallel C++.
+
+    Unlike :func:`hamming_matrix`, sequences may differ in length freely.
+
+    Args:
+        a: Query sequences (the rows).
+        b: Reference sequences (the columns).
+        threads: Worker threads; ``0`` uses all cores.
+
+    Returns:
+        A :class:`~seqtree.ScoreMatrix` of shape ``(len(a), len(b))`` of int32 distances,
+        zero-copy through ``numpy.asarray``.
+    """
+    return _levenshtein_matrix(list(a), list(b), threads=threads)
+
+
+def _shells(seqs: Iterable[str], r: int, alphabet: str | None,
+            include_self: bool, shell: bool) -> list[set[str]]:
+    """The selected shells of the union, as sets: shell ``r`` alone, or shells ``0..r``.
+
+    Multi-source breadth-first walk with one shared ``seen`` set, so a sequence lands in the
+    shell of its *nearest* centre and is generated at most once -- the ``sum(19*L_i)`` multiset
+    is never materialised. Substitution only, so centres of different lengths never meet.
+    """
+    if r < 0:
+        raise ValueError(f"radius must be non-negative, got r={r}")
+    if isinstance(seqs, str):
+        # A str is iterable, so set(seqs) would silently take its CHARACTERS as the centres:
+        # union_size("CASSLGQYF") would answer 20 instead of 172 -- a plausible number, no error.
+        raise TypeError(f"seqs must be a collection of sequences, not one string; "
+                        f"pass [{seqs!r}] or call neighbourhood({seqs!r})")
+    alpha = _STANDARD_AA if alphabet is None else alphabet
+    frontier = set(seqs)
+    seen = set(frontier)
+    levels = [frontier]
+    for _ in range(r):
+        nxt: set[str] = set()
+        for s in frontier:
+            for i, c in enumerate(s):
+                head, tail = s[:i], s[i + 1:]
+                for a in alpha:
+                    if a != c:
+                        t = head + a + tail
+                        if t not in seen:
+                            seen.add(t)
+                            nxt.add(t)
+        levels.append(nxt)
+        frontier = nxt
+    if not include_self:
+        levels[0] = set()       # the centres are exactly the r = 0 shell
+    return [levels[r]] if shell else levels
+
+
+def neighbourhood_union(seqs: Iterable[str], r: int = 1, alphabet: str | None = None,
+                        include_self: bool = True, shell: bool = False) -> list[str]:
+    """Every sequence within ``r`` substitutions of **any** of ``seqs``, each listed once.
+
+    This is the union of the per-sequence Hamming balls, not their concatenation. Near-duplicate
+    centres -- co-specific TCR junctions, an error family around one UMI -- have balls that
+    overlap heavily, so the difference is the dominant term rather than a correction. The
+    dedup happens as the ball is walked, so the ``sum(19*L_i)`` multiset never exists.
+
+    Args:
+        seqs: The centres. Duplicates and mixed lengths are fine; substitution-only means
+            balls of different lengths cannot overlap.
+        r: Radius in substitutions.
+        alphabet: Substituting alphabet; ``None`` is the 20 standard amino acids. Characters of
+            ``seqs`` outside it are still substitutable, so a centre containing ``X`` has
+            ``|alphabet|`` neighbours at that position rather than ``|alphabet| - 1``.
+        include_self: Keep the centres themselves. ``False`` drops **every** centre, including
+            one that happens to be a neighbour of another -- the ``r = 0`` shell of a union is
+            exactly ``set(seqs)``.
+        shell: Return only the members at distance exactly ``r`` from the *nearest* centre,
+            instead of the whole closed ball.
+
+    Returns:
+        The distinct members, ordered by distance and sorted within each shell (so the centres
+        come first). Empty input gives ``[]``.
+
+    Raises:
+        ValueError: If ``r`` is negative.
+        TypeError: If ``seqs`` is a single string -- its characters would otherwise become the
+            centres, silently. Use :func:`neighbourhood` for one sequence.
+
+    Example:
+        >>> neighbourhood_union(["AA", "AC"], 1, alphabet="AC")
+        ['AA', 'AC', 'CA', 'CC']
+        >>> a = neighbourhood("CASSLGQYF")
+        >>> b = neighbourhood("CASSPGQYF")                  # one substitution away
+        >>> len(a) + len(b), len(neighbourhood_union(["CASSLGQYF", "CASSPGQYF"]))
+        (344, 324)
+    """
+    return [s for level in _shells(seqs, r, alphabet, include_self, shell) for s in sorted(level)]
+
+
+def neighbourhood(seq: str, r: int = 1, alphabet: str | None = None,
+                  include_self: bool = True, shell: bool = False) -> list[str]:
+    """Every sequence within ``r`` substitutions of ``seq``: its closed Hamming ball.
+
+    Substitution only, so every member has ``len(seq)`` characters -- Hamming distance is
+    undefined across lengths (see :func:`hamming`), and an indel is a different question. Over a
+    ``k``-letter alphabet the ball holds ``sum((k-1)^d * C(L, d) for d in 0..r)`` sequences;
+    at ``r = 1`` that is ``19*L + 1``.
+
+    Args:
+        seq: The centre.
+        r: Radius in substitutions.
+        alphabet: Substituting alphabet; ``None`` is the 20 standard amino acids.
+        include_self: Keep ``seq`` itself (the ``d = 0`` member).
+        shell: Return only the members at distance exactly ``r``, instead of the closed ball.
+            The cognacy-retention profile is estimated per shell, not per ball.
+
+    Returns:
+        The distinct members, ordered by distance and sorted within each shell, so ``seq``
+        itself comes first when ``include_self``.
+
+    Raises:
+        ValueError: If ``r`` is negative.
+
+    Example:
+        >>> len(neighbourhood("CASSLGQYF"))                 # 19 * 9 + 1
+        172
+        >>> len(neighbourhood("CASSLGQYF", include_self=False))
+        171
+        >>> neighbourhood("A", 1, alphabet="ACGT")
+        ['A', 'C', 'G', 'T']
+        >>> len(neighbourhood("CASSLGQYF", 2, shell=True))   # 19^2 * C(9, 2)
+        12996
+    """
+    return neighbourhood_union([seq], r, alphabet, include_self, shell)
+
+
+def union_size(seqs: Iterable[str], r: int = 1, alphabet: str | None = None,
+               include_self: bool = True, shell: bool = False) -> int:
+    """How many distinct sequences :func:`neighbourhood_union` would return.
+
+    Same walk, but the result list is never built or sorted -- use it to size a job (an OLGA
+    ``P_gen`` pass over the union, say) before committing to it. The dedup set is still held,
+    so this bounds the output, not the peak memory.
+
+    Args:
+        seqs: The centres.
+        r: Radius in substitutions.
+        alphabet: Substituting alphabet; ``None`` is the 20 standard amino acids.
+        include_self: Count the centres themselves.
+        shell: Count only distance-exactly-``r`` members.
+
+    Returns:
+        ``len(neighbourhood_union(seqs, r, alphabet, include_self, shell))``.
+
+    Raises:
+        ValueError: If ``r`` is negative.
+        TypeError: If ``seqs`` is a single string, as for :func:`neighbourhood_union`.
+
+    Example:
+        >>> union_size(["CASSLGQYF", "CASSPGQYF"])          # 344 with double-counting
+        324
+        >>> union_size(["CASSLGQYF", "CASSLGQYF"])          # a repeat adds nothing
+        172
+    """
+    return sum(len(level) for level in _shells(seqs, r, alphabet, include_self, shell))

{seqtree-0.6.0 → seqtree-0.7.0}/skills/seqtree/SKILL.md

@@ -111,6 +111,31 @@ dist_matrix(queries, refs, ...)  -> ScoreMatrix        # d = s(a,a)+s(b,b)-2s(a,
   `similarity()` (signed log-odds, for these aligners). The Gram transform is lossy -- it zeroes
   the diagonal -- so a similarity cannot be recovered from a penalty.
 
+## Plain distances and Hamming balls — `seqtree.distance`
+
+```python
+hamming(a, b) -> int                 # equal length only; RAISES otherwise. Case-SENSITIVE.
+levenshtein(a, b) -> int
+hamming_matrix(a, b, threads=0) / levenshtein_matrix(...) -> ScoreMatrix   # GIL released
+
+neighbourhood(seq, r=1, alphabet=None, include_self=True, shell=False) -> list[str]
+neighbourhood_union(seqs, r=1, ...) -> list[str]      # dedup DURING the walk
+union_size(seqs, r=1, ...) -> int                     # size the job first
+```
+
+Enumeration is **substitution only, fixed length** — no indels, because Hamming is undefined
+across lengths and `P_gen` is length-conditioned. `alphabet=None` is the 20 standard residues,
+which is `amino_acids()` **minus** `B`/`Z`/`X`/`*` — passing `amino_acids()` itself gives 23·L
+neighbours, not 19·L. `shell=True` is the sphere at exactly `r` from the *nearest* centre;
+`include_self=False` drops the whole `r = 0` shell, i.e. every centre.
+
+**Take the union, never the sum of the balls.** 200 length-14 junctions drawn within distance `d`
+of a common centre, `r = 1`: at `d = 1` the per-sequence balls double-count **41.7%**
+(53,400 → 31,122), at `d = 2` 4.5%, at `d ≥ 3` nothing. 300 junctions of length 14 at `r = 1` is
+80,100 distinct sequences in **23 ms** on one M3 core (`union_size` 11 ms), so this is pure
+Python and does not need the C++ core. `r = 2` over the same 300 is 9.9 M sequences, 6.8 s,
+~1.8 GB — there the dedup is what keeps it to one copy.
+
 ## Gap-block alignment — `seqtree.gapblock`
 
 A V(D)J junction's length variation is **one** contiguous indel event, so restrict alignment to
@@ -237,7 +262,7 @@ Count it in the control.
 4. OLGA generates from `P_gen`, which is **not** the post-selection background `P_0`. Do not use
    an OLGA sample as the null for an operational cutoff.
 5. Rebuild after pulling: a stale `_core.so` has silently shadowed new Python-visible C++ methods
-   more than once (`pip install -e .`).
+   more than once (`bash setup.sh`, or `uv pip install -e .`).
 
 ## Layering
 

{seqtree-0.6.0 → seqtree-0.7.0}/src/gapblock.cpp

@@ -9,13 +9,13 @@
 namespace seqtree {
 namespace {
 
-std::vector<uint8_t> encode(const Codec& c, const std::string& s) {
+std::vector<uint8_t> encode(const Codec& c, const std::string& s, const char* label, size_t idx) {
     std::vector<uint8_t> out(s.size());
     for (size_t i = 0; i < s.size(); ++i) {
         uint8_t v = c.encode(s[i]);
         if (v == Codec::kInvalid)
-            throw std::invalid_argument(std::string("symbol '") + s[i] +
-                                        "' is not in the alphabet");
+            throw std::invalid_argument(label + std::string("[") + std::to_string(idx) + "] ('" + s +
+                                        "'): symbol '" + s[i] + "' is not in the alphabet");
         out[i] = v;
     }
     return out;
@@ -85,11 +85,11 @@ std::vector<int32_t> gapblock_matrix(const std::vector<std::string>& queries,
     std::vector<std::vector<uint8_t>> qc(N), rc(K);
     uint32_t longest = 0;
     for (size_t i = 0; i < N; ++i) {
-        qc[i] = encode(codec, queries[i]);
+        qc[i] = encode(codec, queries[i], "queries", i);
         longest = std::max<uint32_t>(longest, uint32_t(qc[i].size()));
     }
     for (size_t k = 0; k < K; ++k) {
-        rc[k] = encode(codec, refs[k]);
+        rc[k] = encode(codec, refs[k], "refs", k);
         longest = std::max<uint32_t>(longest, uint32_t(rc[k].size()));
     }
 

seqtree-0.6.0/python/seqtree/distance.py

@@ -1,119 +0,0 @@
-"""Plain string edit distances: Hamming and Levenshtein, in C++, without a dependency.
-
-These are the *unweighted* distances -- unit costs, no substitution matrix, no gap model, no
-alphabet. That is the whole point: when all you need is "how many edits apart are these two
-strings", you should not have to build an :class:`~seqtree.SubstitutionMatrix` or reach for
-``python-Levenshtein`` / ``rapidfuzz``. seqtree still needs nothing at runtime.
-
-* :func:`hamming` -- number of differing positions; defined only for **equal-length** sequences,
-  and raises :class:`ValueError` otherwise;
-* :func:`levenshtein` -- the classic insertion / deletion / substitution edit distance, each edit
-  costing 1;
-* :func:`hamming_matrix` / :func:`levenshtein_matrix` -- every ``a`` against every ``b`` in one
-  GIL-released, multi-threaded C++ call, returned as a zero-copy :class:`~seqtree.ScoreMatrix`.
-
-Comparison is **case-sensitive**, byte for byte -- unlike the search engines, which fold case.
-For a *weighted* alignment (a substitution matrix, affine gaps, local mode), use
-:mod:`seqtree.pairwise` instead.
-
-Example:
-    >>> from seqtree.distance import hamming, levenshtein
-    >>> hamming("CASSLGQYF", "CASSPGQYF")
-    1
-    >>> levenshtein("kitten", "sitting")
-    3
-"""
-from __future__ import annotations
-
-from collections.abc import Sequence
-
-from ._core import ScoreMatrix
-from ._core import hamming as _hamming
-from ._core import hamming_matrix as _hamming_matrix
-from ._core import levenshtein as _levenshtein
-from ._core import levenshtein_matrix as _levenshtein_matrix
-
-__all__ = ["hamming", "levenshtein", "hamming_matrix", "levenshtein_matrix"]
-
-
-def hamming(a: str, b: str) -> int:
-    """Number of positions at which ``a`` and ``b`` differ.
-
-    Args:
-        a: First sequence.
-        b: Second sequence, of the **same length** as ``a``.
-
-    Returns:
-        The count of differing positions (0 when identical).
-
-    Raises:
-        ValueError: If ``a`` and ``b`` have different lengths -- Hamming distance is undefined
-            for unequal lengths; use :func:`levenshtein` for that.
-
-    Example:
-        >>> hamming("AAAA", "AAAA")
-        0
-        >>> hamming("AAAA", "ATAT")
-        2
-    """
-    return _hamming(a, b)
-
-
-def levenshtein(a: str, b: str) -> int:
-    """Edit distance: fewest single-character insert / delete / substitute steps from ``a`` to ``b``.
-
-    Args:
-        a: First sequence.
-        b: Second sequence; may be any length.
-
-    Returns:
-        The edit distance (0 when identical, ``max(len(a), len(b))`` at most).
-
-    Example:
-        >>> levenshtein("flaw", "lawn")
-        2
-        >>> levenshtein("CASSLGQAYEQYF", "CASSPGQAYEQF")
-        2
-    """
-    return _levenshtein(a, b)
-
-
-def hamming_matrix(a: Sequence[str], b: Sequence[str], threads: int = 0) -> ScoreMatrix:
-    """Hamming distance of every ``a`` against every ``b``, in parallel C++.
-
-    Args:
-        a: Query sequences (the rows).
-        b: Reference sequences (the columns).
-        threads: Worker threads; ``0`` uses all cores.
-
-    Returns:
-        A :class:`~seqtree.ScoreMatrix` of shape ``(len(a), len(b))`` of int32 distances.
-        ``numpy.asarray`` wraps it without copying.
-
-    Raises:
-        ValueError: If any ``(a[i], b[k])`` pair has mismatched lengths.
-
-    Example:
-        >>> import numpy as np
-        >>> d = np.asarray(hamming_matrix(["AAAA", "AAAT"], ["AAAA", "TTTT"]))
-        >>> d.tolist()
-        [[0, 4], [1, 3]]
-    """
-    return _hamming_matrix(list(a), list(b), threads=threads)
-
-
-def levenshtein_matrix(a: Sequence[str], b: Sequence[str], threads: int = 0) -> ScoreMatrix:
-    """Levenshtein distance of every ``a`` against every ``b``, in parallel C++.
-
-    Unlike :func:`hamming_matrix`, sequences may differ in length freely.
-
-    Args:
-        a: Query sequences (the rows).
-        b: Reference sequences (the columns).
-        threads: Worker threads; ``0`` uses all cores.
-
-    Returns:
-        A :class:`~seqtree.ScoreMatrix` of shape ``(len(a), len(b))`` of int32 distances,
-        zero-copy through ``numpy.asarray``.
-    """
-    return _levenshtein_matrix(list(a), list(b), threads=threads)