seqtree 0.4.0__tar.gz → 0.5.0__tar.gz

{seqtree-0.4.0 → seqtree-0.5.0}/CHANGELOG.md

@@ -3,6 +3,28 @@
 All notable changes to `seqtree`. Dates are release dates; the project is pre-1.0, so a **minor**
 bump may carry breaking changes.
 
+## [0.5.0] — 2026-07-16
+
+### Added
+
+- **`seqtree.distance` — plain Hamming and Levenshtein distances, in C++, without a dependency.**
+  The *unweighted* corner of the library: unit costs, no substitution matrix, no gap model, no
+  alphabet. When all you need is "how many edits apart are these two strings", you should not have
+  to build a `SubstitutionMatrix` or add `python-Levenshtein` / `rapidfuzz`. seqtree still needs
+  nothing at runtime.
+
+  | | |
+  |---|---|
+  | `distance.hamming(a, b)` | differing positions; **equal length only** (raises `ValueError` otherwise) |
+  | `distance.levenshtein(a, b)` | insertions + deletions + substitutions, each cost 1, `O(min(m,n))` memory |
+  | `distance.hamming_matrix(a, b, threads=0)` | dense `len(a) × len(b)` int32, GIL released, zero-copy numpy |
+  | `distance.levenshtein_matrix(a, b, threads=0)` | same, for mixed-length sequences |
+
+  Comparison is **case-sensitive**, byte for byte — the one place the library does not fold case,
+  since a generic string distance should report the difference it is asked about. For a *weighted*
+  alignment (a matrix, affine gaps, local mode) use `seqtree.pairwise` instead. Checked against
+  pure-Python oracles over random data in `tests/python/test_distance.py`.
+
 ## [0.4.0] — 2026-07-11
 
 ### Added

{seqtree-0.4.0 → seqtree-0.5.0}/CMakeLists.txt

@@ -29,6 +29,7 @@ add_library(seqtree_core STATIC
   src/searcher.cpp
   src/gapblock.cpp
   src/pairwise.cpp
+  src/distance.cpp
 )
 target_include_directories(seqtree_core PUBLIC include PRIVATE src)
 target_link_libraries(seqtree_core PUBLIC Threads::Threads)

{seqtree-0.4.0 → seqtree-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: seqtree
-Version: 0.4.0
+Version: 0.5.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>
@@ -89,6 +89,12 @@ Beyond search, seqtree ships:
   disagreements** — and **65–87× faster**, since there is no Python in the per-pair loop.
   `dist_matrix` gives `d = s(a,a) + s(b,b) − 2·s(a,b)` directly. BioPython is a *test-only*
   dependency; seqtree still needs nothing at runtime.
+- **Plain edit distances** — `seqtree.distance` is unweighted `hamming` and `levenshtein` (unit
+  costs, no matrix, no alphabet) for when you just need a number, not a scored alignment.
+  `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.
 - **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
@@ -181,6 +187,12 @@ score("AAA", "AAAAA", mat, gap_open=5, gap_extend=5)           # linear gaps: op
 aln = align("CASSLGQAYEQYF", "CASSPGQAYEQF", mat)              # + aligned strings and ops
 
 d = np.asarray(dist_matrix(v_genes, v_genes, mat, threads=0))  # s(a,a)+s(b,b)-2s(a,b), zero diagonal
+
+# plain edit distances -- unweighted Hamming / Levenshtein, no matrix, no dependency
+from seqtree.distance import hamming, levenshtein, hamming_matrix, levenshtein_matrix
+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
 ```
 
 ## Tests

{seqtree-0.4.0 → seqtree-0.5.0}/README.md

@@ -55,6 +55,12 @@ Beyond search, seqtree ships:
   disagreements** — and **65–87× faster**, since there is no Python in the per-pair loop.
   `dist_matrix` gives `d = s(a,a) + s(b,b) − 2·s(a,b)` directly. BioPython is a *test-only*
   dependency; seqtree still needs nothing at runtime.
+- **Plain edit distances** — `seqtree.distance` is unweighted `hamming` and `levenshtein` (unit
+  costs, no matrix, no alphabet) for when you just need a number, not a scored alignment.
+  `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.
 - **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
@@ -147,6 +153,12 @@ score("AAA", "AAAAA", mat, gap_open=5, gap_extend=5)           # linear gaps: op
 aln = align("CASSLGQAYEQYF", "CASSPGQAYEQF", mat)              # + aligned strings and ops
 
 d = np.asarray(dist_matrix(v_genes, v_genes, mat, threads=0))  # s(a,a)+s(b,b)-2s(a,b), zero diagonal
+
+# plain edit distances -- unweighted Hamming / Levenshtein, no matrix, no dependency
+from seqtree.distance import hamming, levenshtein, hamming_matrix, levenshtein_matrix
+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
 ```
 
 ## Tests

{seqtree-0.4.0 → seqtree-0.5.0}/include/seqtree/seqtree.hpp

@@ -221,4 +221,24 @@ std::vector<int32_t> gapblock_matrix(const std::vector<std::string>& queries,
                                      int32_t gap_extend, const std::vector<int32_t>& prior,
                                      uint32_t prior_width, int threads = 0);
 
+// ---------------------------------------------------------------------------------------
+// Plain string edit distances on raw characters, unit costs. Deliberately alphabet-agnostic:
+// no Codec, no substitution matrix, no gap model -- the distance you want when you just need a
+// number, not a scored alignment. Comparison is byte-for-byte and CASE-SENSITIVE; unlike the
+// search Codec, these do not fold case.
+//
+//   hamming     -- number of differing positions; defined only for EQUAL-length sequences and
+//                  throws std::invalid_argument otherwise;
+//   levenshtein -- classic insertion/deletion/substitution distance, each edit cost 1,
+//                  O(min(m,n)) memory.
+int hamming(std::string_view a, std::string_view b);
+int levenshtein(std::string_view a, std::string_view b);
+
+// Dense N*K distance matrices, row-major (row i is a[i] vs every b[k]). Parallel;
+// threads <= 0 => hardware_concurrency. hamming_matrix throws on any length-mismatched pair.
+std::vector<int32_t> hamming_matrix(const std::vector<std::string>& a,
+                                    const std::vector<std::string>& b, int threads = 0);
+std::vector<int32_t> levenshtein_matrix(const std::vector<std::string>& a,
+                                        const std::vector<std::string>& b, int threads = 0);
+
 }  // namespace seqtree

{seqtree-0.4.0 → seqtree-0.5.0}/pyproject.toml

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

{seqtree-0.4.0 → seqtree-0.5.0}/python/seqtree/__init__.py

@@ -24,7 +24,7 @@ from ._core import (
 )
 from .control import load_control
 from .evalue import evalues, thetas_from_scores, threshold_for_evalue
-from . import gapblock, layout, pairwise, pmhc, seeds
+from . import distance, gapblock, layout, pairwise, pmhc, seeds
 from .gapblock import (
     GapBlockIndex, IslandProfile, ScoreMatrix, central_prior, embed_in_frame, frame_prior,
     gapblock_score, positions_prior, profile_prior, score_matrix,
@@ -33,6 +33,7 @@ from .seeds import SeedIndex, core_kmers
 from .pmhc import PMHCStore, find_mimics
 
 __all__ = [
+    "distance",
     "gapblock",
     "layout",
     "pairwise",

seqtree-0.5.0/python/seqtree/distance.py

@@ -0,0 +1,119 @@
+"""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)

{seqtree-0.4.0 → seqtree-0.5.0}/src/_bindings.cpp

@@ -575,6 +575,45 @@ PYBIND11_MODULE(_core, m) {
           "`prior` is the gap prior flattened to [m][d][i]; see seqtree.gapblock.score_matrix, "
           "which builds it for you.");
 
+    m.def("hamming", &hamming, py::arg("a"), py::arg("b"),
+          "Hamming distance: the number of positions at which two EQUAL-length sequences differ. "
+          "Raises ValueError on a length mismatch. Case-sensitive, byte-for-byte.");
+
+    m.def("levenshtein", &levenshtein, py::arg("a"), py::arg("b"),
+          "Levenshtein (edit) distance: the minimum number of single-character insertions, "
+          "deletions, and substitutions to turn `a` into `b`, each cost 1. Case-sensitive.");
+
+    m.def(
+        "hamming_matrix",
+        [](const std::vector<std::string>& a, const std::vector<std::string>& b, int threads) {
+            ScoreMatrix out;
+            out.rows = a.size();
+            out.cols = b.size();
+            {
+                py::gil_scoped_release release;
+                out.data = hamming_matrix(a, b, threads);
+            }
+            return out;
+        },
+        py::arg("a"), py::arg("b"), py::arg("threads") = 0,
+        "Dense (len(a), len(b)) int32 Hamming-distance matrix, GIL released. Raises ValueError "
+        "if any pair has mismatched lengths.");
+
+    m.def(
+        "levenshtein_matrix",
+        [](const std::vector<std::string>& a, const std::vector<std::string>& b, int threads) {
+            ScoreMatrix out;
+            out.rows = a.size();
+            out.cols = b.size();
+            {
+                py::gil_scoped_release release;
+                out.data = levenshtein_matrix(a, b, threads);
+            }
+            return out;
+        },
+        py::arg("a"), py::arg("b"), py::arg("threads") = 0,
+        "Dense (len(a), len(b)) int32 Levenshtein-distance matrix, GIL released.");
+
     py::class_<Candidate>(m, "Candidate",
                           "A seed-and-gather hit: peptide_id, shared_kmers (distinct query k-mers "
                           "that hit it), best_score. Iterable as (peptide_id, shared_kmers, best_score).")

seqtree-0.5.0/src/distance.cpp

@@ -0,0 +1,111 @@
+// Plain string edit distances -- Hamming and Levenshtein -- on raw characters, with unit
+// costs. Deliberately alphabet-agnostic: no Codec, no substitution matrix, no gap model. This
+// is the distance you want when you just need a number, not a scored alignment. Everything
+// else in this library scores against a matrix; these two do not, so they live apart from
+// pairwise.cpp even though the threading plumbing is the same.
+//
+// Comparison is byte-for-byte and case-sensitive -- it does NOT fold case the way the search
+// Codec does, because these are generic string distances, not sequence-search primitives.
+
+#include "seqtree/seqtree.hpp"
+
+#include <algorithm>
+#include <atomic>
+#include <cstdint>
+#include <mutex>
+#include <stdexcept>
+#include <string>
+#include <thread>
+#include <vector>
+
+namespace seqtree {
+namespace {
+
+// Shared driver for both N*K matrices. `pair` is the scalar distance applied to every cell;
+// it may throw (Hamming does, on a length mismatch), so the worker catches and the exception
+// is rethrown after the join -- an exception escaping a std::thread entry calls std::terminate
+// and would take the interpreter down with an uncatchable SIGABRT. Same plumbing as
+// pairwise.cpp / Index::search_batch.
+template <class Pair>
+std::vector<int32_t> matrix_impl(const std::vector<std::string>& a,
+                                 const std::vector<std::string>& b, int threads, Pair pair) {
+    const size_t N = a.size(), K = b.size();
+    std::vector<int32_t> out(N * K);
+    if (N == 0 || K == 0) return out;
+
+    unsigned nt =
+        threads > 0 ? unsigned(threads) : std::max(1u, std::thread::hardware_concurrency());
+    nt = std::min<unsigned>(nt, std::max<size_t>(1, N));
+
+    std::atomic<size_t> next{0};
+    std::exception_ptr err;
+    std::mutex emu;
+
+    auto worker = [&] {
+        for (;;) {
+            const size_t i = next.fetch_add(1);
+            if (i >= N) break;
+            try {
+                int32_t* row = out.data() + i * K;
+                for (size_t k = 0; k < K; ++k) row[k] = pair(a[i], b[k]);
+            } catch (...) {
+                std::lock_guard<std::mutex> lk(emu);
+                if (!err) err = std::current_exception();
+                return;
+            }
+        }
+    };
+
+    std::vector<std::thread> pool;
+    for (unsigned t = 0; t < nt; ++t) pool.emplace_back(worker);
+    for (auto& th : pool) th.join();
+    if (err) std::rethrow_exception(err);
+    return out;
+}
+
+}  // namespace
+
+int hamming(std::string_view a, std::string_view b) {
+    if (a.size() != b.size())
+        throw std::invalid_argument("seqtree: hamming distance is only defined for equal-length "
+                                    "sequences (got " + std::to_string(a.size()) + " and " +
+                                    std::to_string(b.size()) + ")");
+    int d = 0;
+    for (size_t i = 0; i < a.size(); ++i) d += (a[i] != b[i]);
+    return d;
+}
+
+int levenshtein(std::string_view a, std::string_view b) {
+    // Keep the inner row over the shorter sequence: O(min(m,n)) memory. Two rows, no traceback.
+    if (b.size() > a.size()) std::swap(a, b);
+    const size_t m = a.size(), n = b.size();
+    if (n == 0) return int(m);
+
+    std::vector<int> prev(n + 1), cur(n + 1);
+    for (size_t j = 0; j <= n; ++j) prev[j] = int(j);
+    for (size_t i = 1; i <= m; ++i) {
+        cur[0] = int(i);
+        for (size_t j = 1; j <= n; ++j) {
+            const int cost = (a[i - 1] == b[j - 1]) ? 0 : 1;
+            cur[j] = std::min({prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + cost});
+        }
+        prev.swap(cur);
+    }
+    return prev[n];
+}
+
+std::vector<int32_t> hamming_matrix(const std::vector<std::string>& a,
+                                    const std::vector<std::string>& b, int threads) {
+    return matrix_impl(a, b, threads, [](std::string_view x, std::string_view y) {
+        return hamming(x, y);
+    });
+}
+
+std::vector<int32_t> levenshtein_matrix(const std::vector<std::string>& a,
+                                        const std::vector<std::string>& b, int threads) {
+    return matrix_impl(a, b, threads, [](std::string_view x, std::string_view y) {
+        return levenshtein(x, y);
+    });
+}
+
+}  // namespace seqtree