pyseqalignment 0.1.3__tar.gz → 0.1.4__tar.gz

{pyseqalignment-0.1.3/src/pyseqalignment.egg-info → pyseqalignment-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyseqalignment
-Version: 0.1.3
+Version: 0.1.4
 Summary: pySeqAlign -- sequence alignment with Prolog-style distance functions and ILP learning
 Author-email: Andreas Karwath <a.karwath@bham.ac.uk>
 License-Expression: MIT
@@ -56,7 +56,9 @@ pySeqAlign provides Smith-Waterman (local) and Needleman-Wunsch (global) sequenc
 ## Features
 
 - **Smith-Waterman** local alignment with k-best non-overlapping results
-- **Needleman-Wunsch** global alignment
+- **Needleman-Wunsch** global alignment (linear and **affine** gap costs)
+- **Multiple sequence alignment** -- progressive MSA over a neighbor-joining guide tree, parameterised by any scoring function (`pyseqalign.msa`)
+- **Relational sequence logos** -- information-content logos of aligned logical atoms, with per-column least-general generalisation, after Karwath & Kersting (ILP 2006) (`pyseqalign.logo`)
 - **Prolog-based distance functions** via SWI-Prolog integration (optional)
 - **Substitution matrices** -- BLOSUM (50, 60, 62, 70, 80, 90, 100) and PAM (50, 150, 200, 250) bundled; any NCBI-format matrix loadable from file or downloaded at runtime
 - **Nienhuys-Cheng distance** for recursive structural comparison of logical atoms
@@ -309,6 +311,33 @@ For reference, other notable systems in the field include:
 - [Metagol](https://github.com/metagol/metagol) -- Meta-Interpretive Learning
 - [DeepStochLog](https://github.com/ML-KULeuven/deepstochlog) -- Neural-symbolic ILP combining logic and neural networks
 
+## Multiple alignment & relational logos
+
+pySeqAlign can align *and* summarise sequences of structured logical atoms,
+reproducing Karwath & Kersting, *Relational Sequence Alignments and Logos*
+(ILP 2006) — with no learning involved:
+
+```python
+from pyseqalign.msa import progressive_msa
+from pyseqalign.logo import relational_logo
+from pyseqalign.scoring.distance import AtomDistance
+
+# atoms as structured tuples: id -> (predicate, *args); 0 = gap
+atom_store = {1: ('h', 'a', 'r', 'm'), 2: ('h', 'a', 'r', 'l'), 3: ('s', 'p', 'm')}
+seqs = {'d1': [1, 2, 3], 'd2': [1, 3, 2], 'd3': [2, 3]}
+
+scoring = AtomDistance(atom_store=atom_store, gap_score=-0.5)   # Nienhuys-Cheng
+msa = progressive_msa(seqs, scoring, gap_open=-1.0, gap_extend=-0.1)
+rows = list(msa.aligned_sequences.values())
+
+relational_logo(rows, atom_store, 'logo.png', title='example fold')
+```
+
+`progressive_msa` accepts **any** scoring function, so a reward matrix learned
+by [pyREAL](https://github.com/athro/pyREAL)'s boosting can drive the alignment
+in place of the fixed distance. Runnable reproductions of the paper's SCOP and
+balloon logos are in [`examples/`](examples/).
+
 ## Fast C++ aligner (optional)
 
 The pure-Python aligners are fine for typical use. For heavy workloads (e.g.

{pyseqalignment-0.1.3 → pyseqalignment-0.1.4}/README.md

@@ -18,7 +18,9 @@ pySeqAlign provides Smith-Waterman (local) and Needleman-Wunsch (global) sequenc
 ## Features
 
 - **Smith-Waterman** local alignment with k-best non-overlapping results
-- **Needleman-Wunsch** global alignment
+- **Needleman-Wunsch** global alignment (linear and **affine** gap costs)
+- **Multiple sequence alignment** -- progressive MSA over a neighbor-joining guide tree, parameterised by any scoring function (`pyseqalign.msa`)
+- **Relational sequence logos** -- information-content logos of aligned logical atoms, with per-column least-general generalisation, after Karwath & Kersting (ILP 2006) (`pyseqalign.logo`)
 - **Prolog-based distance functions** via SWI-Prolog integration (optional)
 - **Substitution matrices** -- BLOSUM (50, 60, 62, 70, 80, 90, 100) and PAM (50, 150, 200, 250) bundled; any NCBI-format matrix loadable from file or downloaded at runtime
 - **Nienhuys-Cheng distance** for recursive structural comparison of logical atoms
@@ -271,6 +273,33 @@ For reference, other notable systems in the field include:
 - [Metagol](https://github.com/metagol/metagol) -- Meta-Interpretive Learning
 - [DeepStochLog](https://github.com/ML-KULeuven/deepstochlog) -- Neural-symbolic ILP combining logic and neural networks
 
+## Multiple alignment & relational logos
+
+pySeqAlign can align *and* summarise sequences of structured logical atoms,
+reproducing Karwath & Kersting, *Relational Sequence Alignments and Logos*
+(ILP 2006) — with no learning involved:
+
+```python
+from pyseqalign.msa import progressive_msa
+from pyseqalign.logo import relational_logo
+from pyseqalign.scoring.distance import AtomDistance
+
+# atoms as structured tuples: id -> (predicate, *args); 0 = gap
+atom_store = {1: ('h', 'a', 'r', 'm'), 2: ('h', 'a', 'r', 'l'), 3: ('s', 'p', 'm')}
+seqs = {'d1': [1, 2, 3], 'd2': [1, 3, 2], 'd3': [2, 3]}
+
+scoring = AtomDistance(atom_store=atom_store, gap_score=-0.5)   # Nienhuys-Cheng
+msa = progressive_msa(seqs, scoring, gap_open=-1.0, gap_extend=-0.1)
+rows = list(msa.aligned_sequences.values())
+
+relational_logo(rows, atom_store, 'logo.png', title='example fold')
+```
+
+`progressive_msa` accepts **any** scoring function, so a reward matrix learned
+by [pyREAL](https://github.com/athro/pyREAL)'s boosting can drive the alignment
+in place of the fixed distance. Runnable reproductions of the paper's SCOP and
+balloon logos are in [`examples/`](examples/).
+
 ## Fast C++ aligner (optional)
 
 The pure-Python aligners are fine for typical use. For heavy workloads (e.g.

{pyseqalignment-0.1.3 → pyseqalignment-0.1.4}/pyproject.toml

@@ -8,7 +8,7 @@ build-backend = "setuptools.build_meta"
 # PyPI distribution name (the import package is `pyseqalign`; the name
 # `pyseqalign` was blocked by PyPI's similarity guard vs. an existing project).
 name = "pyseqalignment"
-version = "0.1.3"
+version = "0.1.4"
 description = "pySeqAlign -- sequence alignment with Prolog-style distance functions and ILP learning"
 readme = "README.md"
 license = "MIT"
@@ -80,6 +80,11 @@ line-length = 100
 
 [tool.ruff.lint]
 select = ["E", "F", "W", "I", "N", "UP"]
+ignore = [
+    "N803",  # uppercase argument names (matrix math convention: M, Ix, Iy)
+    "N806",  # uppercase local variables in functions (same reason)
+    "E741",  # ambiguous variable name 'l' (used in tree (m, l, r) unpacking)
+]
 
 [tool.mypy]
 python_version = "3.10"

{pyseqalignment-0.1.3 → pyseqalignment-0.1.4}/src/pyseqalign/__init__.py

@@ -1,14 +1,21 @@
 """pySeqAlign -- Sequence alignment with Prolog-style distance functions and ILP learning."""
 
-from pyseqalign.core.alignment import AlignmentResult, LocalAlignmentResult
+from pyseqalign.core.alignment import (
+    AffineAlignmentResult,
+    AlignmentResult,
+    LocalAlignmentResult,
+)
 from pyseqalign.core.needleman_wunsch import NeedlemanWunsch
+from pyseqalign.core.nw_affine import NeedlemanWunschAffine
 from pyseqalign.core.smith_waterman import SmithWaterman
 
-__version__ = "0.1.3"
+__version__ = "0.1.4"
 
 __all__ = [
     "SmithWaterman",
     "NeedlemanWunsch",
+    "NeedlemanWunschAffine",
     "AlignmentResult",
+    "AffineAlignmentResult",
     "LocalAlignmentResult",
 ]

{pyseqalignment-0.1.3 → pyseqalignment-0.1.4}/src/pyseqalign/core/__init__.py

@@ -1,12 +1,19 @@
 """Core alignment algorithms."""
 
-from pyseqalign.core.alignment import AlignmentResult, LocalAlignmentResult
+from pyseqalign.core.alignment import (
+    AffineAlignmentResult,
+    AlignmentResult,
+    LocalAlignmentResult,
+)
 from pyseqalign.core.needleman_wunsch import NeedlemanWunsch
+from pyseqalign.core.nw_affine import NeedlemanWunschAffine
 from pyseqalign.core.smith_waterman import SmithWaterman
 
 __all__ = [
     "SmithWaterman",
     "NeedlemanWunsch",
+    "NeedlemanWunschAffine",
     "AlignmentResult",
+    "AffineAlignmentResult",
     "LocalAlignmentResult",
 ]

{pyseqalignment-0.1.3 → pyseqalignment-0.1.4}/src/pyseqalign/core/alignment.py

@@ -22,6 +22,19 @@ class AlignmentResult:
     length: int
 
 
+@dataclass
+class AffineAlignmentResult(AlignmentResult):
+    """Extended result from affine-gap alignment.
+
+    Attributes:
+        gap_opens: Number of gap-open events in both sequences combined.
+        gap_extensions: Number of gap-extension events.
+    """
+
+    gap_opens: int = 0
+    gap_extensions: int = 0
+
+
 @dataclass
 class LocalAlignmentResult:
     """Result of a single local (Smith-Waterman) alignment.

pyseqalignment-0.1.4/src/pyseqalign/core/nw_affine.py

@@ -0,0 +1,202 @@
+"""Needleman-Wunsch global alignment with affine gap penalties.
+
+Translated from the legacy C++ AlignerAffine::_align() implementation.
+Uses three DP matrices (M, Ix, Iy) to distinguish gap-open from gap-extend.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from pyseqalign.core.alignment import AffineAlignmentResult
+from pyseqalign.scoring.protocols import ScoringFunction
+
+# Matrix indices.
+_M = 0  # match/mismatch
+_IX = 1  # gap in target (consuming query element)
+_IY = 2  # gap in query (consuming target element)
+
+
+class NeedlemanWunschAffine:
+    """Needleman-Wunsch with affine gap penalties.
+
+    Recurrences (similarity mode):
+      M[i][j]  = score(q[i], t[j]) + max(M[i-1][j-1], Ix[i-1][j-1], Iy[i-1][j-1])
+      Ix[i][j] = max(M[i-1][j] + gap_open, Ix[i-1][j] + gap_extend, Iy[i-1][j] + gap_open)
+      Iy[i][j] = max(M[i][j-1] + gap_open, Iy[i][j-1] + gap_extend, Ix[i][j-1] + gap_open)
+
+    Args:
+        scoring: Scoring function (element ID 0 = gap).
+        gap_open: Cost for opening a new gap (should be negative for penalties).
+        gap_extend: Cost for extending an existing gap (should be negative,
+            typically less severe than gap_open).
+    """
+
+    def __init__(
+        self,
+        scoring: ScoringFunction,
+        gap_open: float = -2.5,
+        gap_extend: float = -0.25,
+    ) -> None:
+        self.scoring = scoring
+        self.gap_open = gap_open
+        self.gap_extend = gap_extend
+
+    def align(self, seq1: list[int], seq2: list[int]) -> AffineAlignmentResult:
+        """Compute the optimal global alignment with affine gap penalties.
+
+        Args:
+            seq1: Query sequence (list of integer element IDs).
+            seq2: Target sequence.
+
+        Returns:
+            An ``AffineAlignmentResult`` with aligned sequences and gap statistics.
+        """
+        n = len(seq1)
+        m = len(seq2)
+
+        NEG_INF = -np.inf
+
+        # F[k, i, j] for k in {M=0, Ix=1, Iy=2}
+        F = np.full((3, n + 1, m + 1), NEG_INF, dtype=np.float64)
+        # Traceback: B[k, i, j, :] = (from_k, from_i, from_j)
+        B = np.full((3, n + 1, m + 1, 3), -1, dtype=np.int32)
+
+        F[_M, 0, 0] = 0.0
+
+        d = self.gap_open
+        e = self.gap_extend
+
+        # --- Border initialization: gaps along query (Ix column) ---
+        for i0 in range(n):
+            i = i0 + 1
+            if i > 1:
+                F[_IX, i, 0] = F[_IX, i - 1, 0] + e
+            else:
+                F[_IX, i, 0] = d
+            B[_IX, i, 0] = [_IX, i - 1, 0]
+            # M and Iy are -inf along this border (already set).
+
+        # --- Border initialization: gaps along target (Iy row) ---
+        for j0 in range(m):
+            j = j0 + 1
+            if j > 1:
+                F[_IY, 0, j] = F[_IY, 0, j - 1] + e
+            else:
+                F[_IY, 0, j] = d
+            B[_IY, 0, j] = [_IY, 0, j - 1]
+            # M and Ix are -inf along this border (already set).
+
+        # --- Main DP fill ---
+        for i0 in range(n):
+            i = i0 + 1
+            for j0 in range(m):
+                j = j0 + 1
+
+                # Match/mismatch: diagonal transition.
+                s = self.scoring.score(seq1[i - 1], seq2[j - 1])
+                candidates_m = (
+                    F[_M, i - 1, j - 1] + s,
+                    F[_IX, i - 1, j - 1] + s,
+                    F[_IY, i - 1, j - 1] + s,
+                )
+                best_k = _argmax3(candidates_m)
+                F[_M, i, j] = candidates_m[best_k]
+                B[_M, i, j] = [best_k, i - 1, j - 1]
+
+                # Ix: gap in target (consume query[i], skip target).
+                candidates_ix = (
+                    F[_M, i - 1, j] + d,  # new gap
+                    F[_IX, i - 1, j] + e,  # extend gap
+                    F[_IY, i - 1, j] + d,  # new gap
+                )
+                best_k = _argmax3(candidates_ix)
+                F[_IX, i, j] = candidates_ix[best_k]
+                B[_IX, i, j] = [best_k, i - 1, j]
+
+                # Iy: gap in query (skip query, consume target[j]).
+                candidates_iy = (
+                    F[_M, i, j - 1] + d,  # new gap
+                    F[_IY, i, j - 1] + e,  # extend gap
+                    F[_IX, i, j - 1] + d,  # new gap
+                )
+                best_k = _argmax3(candidates_iy)
+                F[_IY, i, j] = candidates_iy[best_k]
+                B[_IY, i, j] = [best_k, i, j - 1]
+
+        # --- Find best endpoint ---
+        end_scores = (F[_M, n, m], F[_IX, n, m], F[_IY, n, m])
+        best_end = _argmax3(end_scores)
+        score = end_scores[best_end]
+
+        # --- Traceback ---
+        align1, align2, gap_opens, gap_extensions = self._traceback(B, seq1, seq2, best_end, n, m)
+
+        return AffineAlignmentResult(
+            query=align1,
+            target=align2,
+            score=float(score),
+            length=len(align1),
+            gap_opens=gap_opens,
+            gap_extensions=gap_extensions,
+        )
+
+    @staticmethod
+    def _traceback(
+        B: np.ndarray,
+        seq1: list[int],
+        seq2: list[int],
+        start_k: int,
+        start_i: int,
+        start_j: int,
+    ) -> tuple[list[int], list[int], int, int]:
+        """Walk the traceback matrix to produce aligned sequences."""
+        align1: list[int] = []
+        align2: list[int] = []
+        gap_opens = 0
+        gap_extensions = 0
+
+        k, i, j = start_k, start_i, start_j
+        prev_k = -1
+
+        while i > 0 or j > 0:
+            from_k, from_i, from_j = int(B[k, i, j, 0]), int(B[k, i, j, 1]), int(B[k, i, j, 2])
+
+            if from_i < 0 or from_j < 0:
+                # Reached uninitialised border — shouldn't happen.
+                break
+
+            if k == _M:
+                # Diagonal: match/mismatch.
+                align1.append(seq1[i - 1])
+                align2.append(seq2[j - 1])
+            elif k == _IX:
+                # Gap in target.
+                align1.append(seq1[i - 1])
+                align2.append(0)
+                if prev_k != _IX:
+                    gap_opens += 1
+                else:
+                    gap_extensions += 1
+            else:  # _IY
+                # Gap in query.
+                align1.append(0)
+                align2.append(seq2[j - 1])
+                if prev_k != _IY:
+                    gap_opens += 1
+                else:
+                    gap_extensions += 1
+
+            prev_k = k
+            k, i, j = from_k, from_i, from_j
+
+        align1.reverse()
+        align2.reverse()
+        return align1, align2, gap_opens, gap_extensions
+
+
+def _argmax3(vals: tuple[float, float, float]) -> int:
+    """Return index of maximum among exactly three values."""
+    if vals[0] >= vals[1]:
+        return 0 if vals[0] >= vals[2] else 2
+    return 1 if vals[1] >= vals[2] else 2

pyseqalignment-0.1.4/src/pyseqalign/logo/__init__.py

@@ -0,0 +1,17 @@
+"""Relational sequence logos — position-specific profiles of logical atoms."""
+
+from pyseqalign.logo.probability import FreqDist, LidstoneProbDist, MLEProbDist
+from pyseqalign.logo.profile import PositionProfile, RelationalProfile
+from pyseqalign.logo.render import column_ic, lgg_atoms, relational_logo, term_str
+
+__all__ = [
+    'FreqDist',
+    'MLEProbDist',
+    'LidstoneProbDist',
+    'PositionProfile',
+    'RelationalProfile',
+    'relational_logo',
+    'column_ic',
+    'lgg_atoms',
+    'term_str',
+]

pyseqalignment-0.1.4/src/pyseqalign/logo/probability.py

@@ -0,0 +1,192 @@
+"""Frequency and probability distributions for relational sequence logos.
+
+Simplified, modern-Python reimplementation of the NLTK-derived legacy
+``Probability.py``.  Only the distributions needed for logo construction
+are included: :class:`FreqDist`, :class:`MLEProbDist` (maximum-likelihood),
+and :class:`LidstoneProbDist` (smoothed).
+"""
+
+from __future__ import annotations
+
+import builtins as _builtins
+import math
+from collections.abc import Hashable, Iterator
+from typing import Any
+
+_builtin_max = _builtins.max
+
+
+class FreqDist:
+    """A frequency distribution over hashable samples.
+
+    Counts how many times each outcome has been observed.
+
+    >>> fd = FreqDist()
+    >>> fd.inc("a"); fd.inc("a"); fd.inc("b")
+    >>> fd.count("a")
+    2
+    >>> fd.freq("a")  # doctest: +ELLIPSIS
+    0.666...
+    """
+
+    __slots__ = ('_counts', '_total', '_max_cache')
+
+    def __init__(self) -> None:
+        self._counts: dict[Any, int] = {}
+        self._total: int = 0
+        self._max_cache: Any | None = None
+
+    # -- Mutation -----------------------------------------------------------
+
+    def inc(self, sample: Hashable, count: int = 1) -> None:
+        """Increment the count for *sample* by *count*."""
+        if count == 0:
+            return
+        self._counts[sample] = self._counts.get(sample, 0) + count
+        self._total += count
+        self._max_cache = None
+
+    # -- Queries ------------------------------------------------------------
+
+    @property
+    def total(self) -> int:
+        """Total number of recorded outcomes (``N``)."""
+        return self._total
+
+    @property
+    def num_bins(self) -> int:
+        """Number of distinct samples with count > 0 (``B``)."""
+        return len(self._counts)
+
+    def count(self, sample: Hashable) -> int:
+        """Return the count for *sample* (0 if unseen)."""
+        return self._counts.get(sample, 0)
+
+    def freq(self, sample: Hashable) -> float:
+        """Return the relative frequency ``count(sample) / N``."""
+        if self._total == 0:
+            return 0.0
+        return self._counts.get(sample, 0) / self._total
+
+    def samples(self) -> list[Any]:
+        """Return all samples with count > 0."""
+        return list(self._counts.keys())
+
+    def max(self) -> Any | None:
+        """Return the sample with the highest count (arbitrary tie-break)."""
+        if self._max_cache is None:
+            if not self._counts:
+                return None
+            self._max_cache = _builtin_max(self._counts, key=self._counts.__getitem__)
+        return self._max_cache
+
+    def sorted_samples(self) -> list[Any]:
+        """Return samples sorted by descending count."""
+        return sorted(self._counts, key=self._counts.__getitem__, reverse=True)
+
+    # -- Container protocol -------------------------------------------------
+
+    def __contains__(self, sample: object) -> bool:
+        return sample in self._counts
+
+    def __len__(self) -> int:
+        return self.num_bins
+
+    def __iter__(self) -> Iterator[Any]:
+        return iter(self._counts)
+
+    # -- Representation -----------------------------------------------------
+
+    def __repr__(self) -> str:
+        return f'<FreqDist with {self._total} outcomes, {self.num_bins} bins>'
+
+    def __str__(self) -> str:
+        items = ', '.join(
+            f'{s!r}: {c}' for s, c in sorted(self._counts.items(), key=lambda kv: -kv[1])
+        )
+        return f'<FreqDist: {items}>'
+
+
+class MLEProbDist:
+    """Maximum-likelihood probability distribution from a :class:`FreqDist`.
+
+    ``P(sample) = count(sample) / N``
+    """
+
+    __slots__ = ('_freqdist',)
+
+    def __init__(self, freqdist: FreqDist) -> None:
+        if freqdist.total == 0:
+            raise ValueError('Cannot build MLE distribution from empty FreqDist.')
+        self._freqdist = freqdist
+
+    @property
+    def freqdist(self) -> FreqDist:
+        return self._freqdist
+
+    def prob(self, sample: Hashable) -> float:
+        return self._freqdist.freq(sample)
+
+    def logprob(self, sample: Hashable) -> float:
+        p = self.prob(sample)
+        return math.log(p) if p > 0 else float('-inf')
+
+    def max(self) -> Any | None:
+        return self._freqdist.max()
+
+    def samples(self) -> list[Any]:
+        return self._freqdist.samples()
+
+    def __repr__(self) -> str:
+        return f'<MLEProbDist based on {self._freqdist.total} outcomes>'
+
+
+class LidstoneProbDist:
+    """Lidstone-smoothed probability distribution.
+
+    ``P(sample) = (count(sample) + gamma) / (N + B * gamma)``
+
+    With ``gamma = 1`` this is Laplace smoothing; ``gamma = 0.5`` gives the
+    Expected Likelihood Estimate (ELE).
+    """
+
+    __slots__ = ('_freqdist', '_gamma', '_bins', '_N')
+
+    def __init__(
+        self,
+        freqdist: FreqDist,
+        gamma: float = 1.0,
+        bins: int | None = None,
+    ) -> None:
+        if bins is not None and bins < freqdist.num_bins:
+            raise ValueError(f'bins ({bins}) must be >= FreqDist.num_bins ({freqdist.num_bins})')
+        if bins is None:
+            bins = freqdist.num_bins
+        if bins == 0:
+            raise ValueError('Lidstone distribution must have at least one bin.')
+
+        self._freqdist = freqdist
+        self._gamma = float(gamma)
+        self._bins = bins
+        self._N = freqdist.total
+
+    @property
+    def freqdist(self) -> FreqDist:
+        return self._freqdist
+
+    def prob(self, sample: Hashable) -> float:
+        c = self._freqdist.count(sample)
+        return (c + self._gamma) / (self._N + self._bins * self._gamma)
+
+    def logprob(self, sample: Hashable) -> float:
+        p = self.prob(sample)
+        return math.log(p) if p > 0 else float('-inf')
+
+    def max(self) -> Any | None:
+        return self._freqdist.max()
+
+    def samples(self) -> list[Any]:
+        return self._freqdist.samples()
+
+    def __repr__(self) -> str:
+        return f'<LidstoneProbDist gamma={self._gamma} based on {self._N} outcomes>'