pyseqalignment 0.1.0__py3-none-any.whl

pyseqalign/learning/base.py

@@ -0,0 +1,68 @@
+"""Base types and protocol for ILP learning backends.
+
+Defines the common interface that both Aleph and Popper backends implement.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+
+@dataclass
+class ILPTask:
+    """Specification of an ILP learning task.
+
+    An ILP task consists of background knowledge, positive/negative examples,
+    and a language bias that constrains the hypothesis space.
+
+    Attributes:
+        background: Prolog clauses providing background knowledge (facts & rules).
+        positive: Positive example facts (goals that should succeed).
+        negative: Negative example facts (goals that should fail).
+        bias: Language bias declarations (mode declarations for Aleph,
+            head_pred/body_pred for Popper).
+        settings: Additional ILP system settings as key-value pairs.
+        work_dir: Directory for intermediate files.  Created automatically
+            if not provided.
+    """
+
+    background: list[str] = field(default_factory=list)
+    positive: list[str] = field(default_factory=list)
+    negative: list[str] = field(default_factory=list)
+    bias: list[str] = field(default_factory=list)
+    settings: dict[str, str] = field(default_factory=dict)
+    work_dir: Path | None = None
+
+
+@dataclass
+class LearnedProgram:
+    """Result of an ILP learning run.
+
+    Attributes:
+        clauses: The learned Prolog clauses (rules).
+        score: Quality score assigned by the learner (interpretation depends
+            on the backend -- accuracy for Popper, coverage for Aleph).
+        stats: Backend-specific statistics (runtime, nodes explored, etc.).
+        raw_output: Full textual output from the ILP system.
+    """
+
+    clauses: list[str] = field(default_factory=list)
+    score: float = 0.0
+    stats: dict[str, object] = field(default_factory=dict)
+    raw_output: str = ""
+
+    @property
+    def program_text(self) -> str:
+        """Return the learned clauses as a single Prolog program string."""
+        return "\n".join(self.clauses)
+
+
+@runtime_checkable
+class ILPLearner(Protocol):
+    """Protocol that all ILP backends must implement."""
+
+    def learn(self, task: ILPTask) -> LearnedProgram:
+        """Run the ILP learner on the given task and return the result."""
+        ...

pyseqalign/learning/popper.py

@@ -0,0 +1,215 @@
+"""Popper ILP backend.
+
+Popper (Cropper & Morel, 2021) is a modern ILP system that learns from
+failures.  It combines answer set programming (ASP) with Prolog to search
+the hypothesis space efficiently.
+
+Popper is the **recommended** backend for new projects.  It can learn
+recursive and optimal programs, handles noise, and does not require
+metarules.
+
+Install Popper with::
+
+    pip install popper-ilp
+
+Or from the repository::
+
+    pip install git+https://github.com/logic-and-learning-lab/Popper@main
+
+Requires SWI-Prolog (>=9.2.0) and Clingo (>=5.6.2).
+"""
+
+from __future__ import annotations
+
+import importlib
+import tempfile
+from pathlib import Path
+
+from pyseqalign.learning.base import ILPTask, LearnedProgram
+
+
+class PopperLearner:
+    """Popper ILP backend.
+
+    Uses the Popper Python API to learn Prolog clauses from alignment
+    examples.
+
+    Args:
+        timeout: Maximum learning time in seconds (default 300).
+        max_literals: Maximum number of literals per clause (default 6).
+        max_vars: Maximum number of variables per clause (default 6).
+        noisy: Enable noise-tolerant learning (learns MDL programs).
+        eval_timeout: Timeout for evaluating each hypothesis in seconds.
+        extra_args: Additional keyword arguments passed to Popper's
+            ``Settings`` constructor.
+    """
+
+    def __init__(
+        self,
+        timeout: int = 300,
+        max_literals: int = 6,
+        max_vars: int = 6,
+        noisy: bool = False,
+        eval_timeout: int = 10,
+        **extra_args: object,
+    ) -> None:
+        self.timeout = timeout
+        self.max_literals = max_literals
+        self.max_vars = max_vars
+        self.noisy = noisy
+        self.eval_timeout = eval_timeout
+        self.extra_args = extra_args
+        self._check_available()
+
+    @staticmethod
+    def _check_available() -> None:
+        """Verify that Popper is installed."""
+        try:
+            importlib.import_module("popper")
+        except ImportError as exc:
+            raise ImportError(
+                "Popper is not installed. Install with:\n"
+                "  pip install popper-ilp\n"
+                "or:\n"
+                "  pip install git+https://github.com/logic-and-learning-lab/Popper@main"
+            ) from exc
+
+    def learn(self, task: ILPTask) -> LearnedProgram:
+        """Run Popper on the given task.
+
+        Writes the task to Popper's expected directory format, calls the
+        Popper learning loop, and returns the result.
+        """
+        from popper.loop import learn_solution
+        from popper.util import Settings
+
+        work_dir = task.work_dir or Path(tempfile.mkdtemp(prefix="pyseqalign_popper_"))
+        work_dir = Path(work_dir)
+        work_dir.mkdir(parents=True, exist_ok=True)
+
+        # Write Popper-format files.
+        self._write_popper_files(task, work_dir)
+
+        # Configure and run Popper.
+        settings = Settings(
+            kbpath=str(work_dir),
+            timeout=self.timeout,
+            eval_timeout=self.eval_timeout,
+            **self.extra_args,
+        )
+
+        prog, score, stats = learn_solution(settings)
+
+        # Format results.
+        clauses: list[str] = []
+        raw_output = ""
+        if prog is not None:
+            import io
+            buf = io.StringIO()
+            settings.print_prog_score(prog, score, file=buf)
+            raw_output = buf.getvalue()
+            clauses = [str(clause) for clause in prog]
+
+        return LearnedProgram(
+            clauses=clauses,
+            score=score if score is not None else 0.0,
+            stats=dict(stats) if stats else {},
+            raw_output=raw_output,
+        )
+
+    # ------------------------------------------------------------------
+    # File writing
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _write_popper_files(task: ILPTask, directory: Path) -> None:
+        """Write Popper-format input files to *directory*."""
+        # Background knowledge (bk.pl).
+        (directory / "bk.pl").write_text("\n".join(task.background) + "\n")
+
+        # Examples (exs.pl) -- Popper uses pos()/neg() wrappers.
+        exs_lines: list[str] = []
+        for p in task.positive:
+            fact = p.rstrip(".")
+            exs_lines.append(f"pos({fact}).")
+        for n in task.negative:
+            fact = n.rstrip(".")
+            exs_lines.append(f"neg({fact}).")
+        (directory / "exs.pl").write_text("\n".join(exs_lines) + "\n")
+
+        # Bias (bias.pl) -- Popper's hypothesis language spec.
+        (directory / "bias.pl").write_text("\n".join(task.bias) + "\n")
+
+
+class PopperFallbackLearner:
+    """Fallback Popper learner that calls Popper via subprocess.
+
+    Use this when you cannot import Popper directly (e.g., version
+    conflicts) but have the ``popper.py`` script available on PATH.
+
+    Args:
+        popper_cmd: Command to run Popper (default ``"python -m popper"``).
+        timeout: Maximum learning time in seconds.
+    """
+
+    def __init__(
+        self,
+        popper_cmd: str = "python -m popper",
+        timeout: int = 300,
+    ) -> None:
+        self.popper_cmd = popper_cmd
+        self.timeout = timeout
+
+    def learn(self, task: ILPTask) -> LearnedProgram:
+        """Run Popper via subprocess."""
+        import subprocess
+
+        work_dir = task.work_dir or Path(tempfile.mkdtemp(prefix="pyseqalign_popper_"))
+        work_dir = Path(work_dir)
+        work_dir.mkdir(parents=True, exist_ok=True)
+
+        PopperLearner._write_popper_files(task, work_dir)
+
+        try:
+            result = subprocess.run(
+                self.popper_cmd.split() + [str(work_dir)],
+                capture_output=True,
+                text=True,
+                timeout=self.timeout,
+            )
+            raw_output = result.stdout + result.stderr
+        except FileNotFoundError:
+            raise RuntimeError(
+                f"Popper not found via '{self.popper_cmd}'. "
+                "Install with: pip install popper-ilp"
+            )
+        except subprocess.TimeoutExpired:
+            return LearnedProgram(
+                raw_output=f"Popper timed out after {self.timeout}s",
+                stats={"timeout": True},
+            )
+
+        # Parse stdout for learned clauses.
+        clauses = self._parse_output(raw_output)
+        return LearnedProgram(
+            clauses=clauses,
+            raw_output=raw_output,
+        )
+
+    @staticmethod
+    def _parse_output(raw_output: str) -> list[str]:
+        """Extract clauses from Popper's stdout."""
+        clauses: list[str] = []
+        in_program = False
+        for line in raw_output.splitlines():
+            stripped = line.strip()
+            if stripped.startswith("% ") or stripped == "":
+                if in_program and stripped == "":
+                    in_program = False
+                continue
+            if ":-" in stripped or (stripped.endswith(".") and not stripped.startswith("%")):
+                # Looks like a Prolog clause.
+                if not stripped.startswith("pos(") and not stripped.startswith("neg("):
+                    clauses.append(stripped)
+                    in_program = True
+        return clauses

pyseqalign/learning/task_builder.py

@@ -0,0 +1,213 @@
+"""Helpers for constructing ILP tasks from alignment data.
+
+Converts alignment examples into the background knowledge, positive/negative
+examples, and bias declarations needed by ILP learners.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+
+from pyseqalign.learning.base import ILPTask
+
+
+def _seq_to_prolog_list(seq: Sequence[int]) -> str:
+    """Convert a Python integer list to a Prolog list string."""
+    return "[" + ",".join(str(x) for x in seq) + "]"
+
+
+class AlignmentTaskBuilder:
+    """Build ILP tasks from alignment training data.
+
+    This builder generates the Prolog facts and bias declarations required
+    to learn distance/scoring predicates or alignment classification rules
+    from labelled sequence pairs.
+
+    Example usage::
+
+        builder = AlignmentTaskBuilder()
+        builder.add_positive_pair([1, 2, 3], [1, 2, 4], label="similar")
+        builder.add_negative_pair([1, 2, 3], [10, 11, 12], label="similar")
+        builder.add_background_fact("amino_acid(1, a).")
+        task = builder.build()
+    """
+
+    def __init__(self) -> None:
+        self._positive: list[str] = []
+        self._negative: list[str] = []
+        self._background: list[str] = []
+        self._bias: list[str] = []
+        self._settings: dict[str, str] = {}
+        self._pair_id: int = 0
+
+    # ------------------------------------------------------------------
+    # Adding examples
+    # ------------------------------------------------------------------
+
+    def add_positive_pair(
+        self,
+        seq1: Sequence[int],
+        seq2: Sequence[int],
+        label: str = "similar",
+    ) -> AlignmentTaskBuilder:
+        """Add a positive example pair (sequences that *should* be related).
+
+        Args:
+            seq1: First sequence as integer IDs.
+            seq2: Second sequence as integer IDs.
+            label: Predicate name for the relation being learned.
+        """
+        self._pair_id += 1
+        pid = self._pair_id
+        s1 = _seq_to_prolog_list(seq1)
+        s2 = _seq_to_prolog_list(seq2)
+        self._positive.append(f"{label}(p{pid}).")
+        self._background.append(f"seq1(p{pid},{s1}).")
+        self._background.append(f"seq2(p{pid},{s2}).")
+        return self
+
+    def add_negative_pair(
+        self,
+        seq1: Sequence[int],
+        seq2: Sequence[int],
+        label: str = "similar",
+    ) -> AlignmentTaskBuilder:
+        """Add a negative example pair (sequences that should *not* be related)."""
+        self._pair_id += 1
+        pid = self._pair_id
+        s1 = _seq_to_prolog_list(seq1)
+        s2 = _seq_to_prolog_list(seq2)
+        self._negative.append(f"{label}(p{pid}).")
+        self._background.append(f"seq1(p{pid},{s1}).")
+        self._background.append(f"seq2(p{pid},{s2}).")
+        return self
+
+    def add_background_fact(self, fact: str) -> AlignmentTaskBuilder:
+        """Add a raw Prolog fact to the background knowledge."""
+        self._background.append(fact)
+        return self
+
+    def add_background_rule(self, rule: str) -> AlignmentTaskBuilder:
+        """Add a raw Prolog rule to the background knowledge."""
+        self._background.append(rule)
+        return self
+
+    # ------------------------------------------------------------------
+    # Bias / language declarations
+    # ------------------------------------------------------------------
+
+    def add_bias(self, declaration: str) -> AlignmentTaskBuilder:
+        """Add a raw bias declaration (mode, determination, head_pred, etc.)."""
+        self._bias.append(declaration)
+        return self
+
+    def set_setting(self, key: str, value: str) -> AlignmentTaskBuilder:
+        """Set an ILP system parameter."""
+        self._settings[key] = value
+        return self
+
+    def use_default_alignment_bias_aleph(
+        self, label: str = "similar"
+    ) -> AlignmentTaskBuilder:
+        """Add default Aleph mode/determination declarations for sequence alignment.
+
+        Sets up modes to learn rules about when two sequences are *label*.
+        """
+        self._bias.extend([
+            f":- modeh(1, {label}(+pair)).",
+            ":- modeb(*, seq1(+pair, -list)).",
+            ":- modeb(*, seq2(+pair, -list)).",
+            ":- modeb(*, member(-int, +list)).",
+            ":- modeb(1, length(+list, -int)).",
+            ":- modeb(1, sw_score(+pair, -float)).",
+            ":- modeb(1, nw_score(+pair, -float)).",
+            ":- modeb(1, score_above(+float, #float)).",
+            f":- determination({label}/1, seq1/2).",
+            f":- determination({label}/1, seq2/2).",
+            f":- determination({label}/1, member/2).",
+            f":- determination({label}/1, length/2).",
+            f":- determination({label}/1, sw_score/2).",
+            f":- determination({label}/1, nw_score/2).",
+            f":- determination({label}/1, score_above/2).",
+        ])
+        return self
+
+    def use_default_alignment_bias_popper(
+        self, label: str = "similar"
+    ) -> AlignmentTaskBuilder:
+        """Add default Popper bias declarations for sequence alignment."""
+        self._bias.extend([
+            f"head_pred({label},1).",
+            "body_pred(seq1,2).",
+            "body_pred(seq2,2).",
+            "body_pred(member,2).",
+            "body_pred(length,2).",
+            "body_pred(sw_score,2).",
+            "body_pred(nw_score,2).",
+            "body_pred(score_above,2).",
+            "max_body(6).",
+            "max_vars(6).",
+        ])
+        return self
+
+    # ------------------------------------------------------------------
+    # Build
+    # ------------------------------------------------------------------
+
+    def build(self, work_dir: Path | None = None) -> ILPTask:
+        """Construct the ILP task from the accumulated data."""
+        return ILPTask(
+            background=list(self._background),
+            positive=list(self._positive),
+            negative=list(self._negative),
+            bias=list(self._bias),
+            settings=dict(self._settings),
+            work_dir=work_dir,
+        )
+
+    def write_files(self, directory: Path, name: str = "alignment") -> ILPTask:
+        """Write .b, .f, .n, and bias files to *directory* and return the task.
+
+        This produces files in the format expected by both Aleph and Popper.
+
+        Args:
+            directory: Target directory (created if it doesn't exist).
+            name: Base filename (without extension).
+        """
+        directory = Path(directory)
+        directory.mkdir(parents=True, exist_ok=True)
+
+        task = self.build(work_dir=directory)
+
+        # Background knowledge
+        bk_path = directory / f"{name}.b"
+        bk_lines = list(task.bias) + [""] + list(task.background)
+        if task.settings:
+            for k, v in task.settings.items():
+                bk_lines.insert(0, f":- set({k},{v}).")
+        bk_path.write_text("\n".join(bk_lines) + "\n")
+
+        # Positive examples
+        (directory / f"{name}.f").write_text("\n".join(task.positive) + "\n")
+
+        # Negative examples
+        (directory / f"{name}.n").write_text("\n".join(task.negative) + "\n")
+
+        # Popper-style separate bias file (also useful for Aleph via .b)
+        (directory / "bias.pl").write_text("\n".join(task.bias) + "\n")
+
+        # Popper exs.pl (combines pos/neg)
+        popper_exs = []
+        for p in task.positive:
+            fact = p.rstrip(".")
+            popper_exs.append(f"pos({fact}).")
+        for n in task.negative:
+            fact = n.rstrip(".")
+            popper_exs.append(f"neg({fact}).")
+        (directory / "exs.pl").write_text("\n".join(popper_exs) + "\n")
+
+        # Popper bk.pl (background only, no bias)
+        (directory / "bk.pl").write_text("\n".join(task.background) + "\n")
+
+        return task

pyseqalign/prolog/__init__.py

@@ -0,0 +1,5 @@
+"""Prolog engine integration for custom distance functions."""
+
+from pyseqalign.prolog.engine import PrologEngine
+
+__all__ = ["PrologEngine"]

pyseqalign/prolog/engine.py

@@ -0,0 +1,102 @@
+"""SWI-Prolog engine wrapper for computing distance/scoring via Prolog predicates.
+
+This replaces the legacy YAP Prolog bindings (yapBind.c) with SWI-Prolog
+via the ``janus_swi`` package (the modern Python↔SWI-Prolog bridge).
+The engine implements the ``ScoringFunction`` protocol so it can be passed
+directly to ``SmithWaterman`` or ``NeedlemanWunsch``.
+
+Requires the ``prolog`` optional dependency::
+
+    pip install pyseqalign[prolog]
+"""
+
+from __future__ import annotations
+
+import importlib
+from pathlib import Path
+
+
+class PrologEngine:
+    """SWI-Prolog based scoring function using Janus.
+
+    Args:
+        dist_mode: ``"sym"`` for similarity mode (1 - distance) or
+            ``"dist"`` for raw distance.  Matches the legacy ``dist/7``
+            predicate convention.
+        distance_type: Name of the distance type predicate (default
+            ``"atomDistance"``).
+        distance_method: Distance method identifier (default ``"nc"`` for
+            Nienhuys-Cheng).
+        iteration: Iteration parameter passed to ``dist/7`` (default ``0``).
+        gap_default: Default score returned for gap characters.
+    """
+
+    def __init__(
+        self,
+        dist_mode: str = "sym",
+        distance_type: str = "atomDistance",
+        distance_method: str = "nc",
+        iteration: int = 0,
+        gap_default: float = -8.0,
+    ) -> None:
+        self.dist_mode = dist_mode
+        self.distance_type = distance_type
+        self.distance_method = distance_method
+        self.iteration = iteration
+        self.gap_default = gap_default
+
+        # Lazy import so the package works without janus_swi installed.
+        try:
+            self._janus = importlib.import_module("janus_swi")
+        except ImportError as exc:
+            raise ImportError(
+                "janus_swi is required for Prolog support. "
+                "Install with: pip install pyseqalign[prolog]"
+            ) from exc
+
+    def consult(self, path: str | Path) -> None:
+        """Load a Prolog file into the engine."""
+        self._janus.consult(str(path))
+
+    def assert_fact(self, term: str) -> None:
+        """Assert a Prolog fact."""
+        self._janus.query_once(f"assert({term})")
+
+    def retract_fact(self, term: str) -> None:
+        """Retract a Prolog fact."""
+        self._janus.query_once(f"retract({term})")
+
+    def call(self, goal: str) -> list[dict]:
+        """Execute a Prolog goal and return all solution bindings."""
+        return list(self._janus.query(goal))
+
+    def call_once(self, goal: str) -> dict:
+        """Execute a Prolog goal and return the first solution."""
+        return self._janus.query_once(goal)
+
+    def score(self, a: int, b: int) -> float:
+        """Compute the score between element IDs *a* and *b* via Prolog.
+
+        Calls the ``dist/7`` predicate:
+        ``dist(Mode, Type, Method, Iteration, A, B, D)``
+        and returns the bound value of ``D``.
+        """
+        if a == 0 or b == 0:
+            return self.gap_default
+
+        query = (
+            f"dist({self.dist_mode},{self.distance_type},"
+            f"{self.distance_method},{self.iteration},{a},{b},D)"
+        )
+        result = self._janus.query_once(query)
+        if result["truth"]:
+            return float(result["D"])
+        return -100.0
+
+    def consult_knowledge_base(self) -> None:
+        """Load the bundled Prolog knowledge base files (amino acids, BLOSUM50, distances)."""
+        kb_dir = Path(__file__).parent / "knowledge"
+        for pl_file in ["amino_acids.pl", "distances.pl", "blosum50.pl"]:
+            path = kb_dir / pl_file
+            if path.exists():
+                self.consult(path)

pyseqalign/prolog/knowledge/amino_acids.pl

@@ -0,0 +1,53 @@
+example(0,'-').
+example(1,'a').
+example(2,'r').
+example(3,'n').
+example(4,'d').
+example(5,'c').
+example(6,'q').
+example(7,'e').
+example(8,'g').
+example(9,'h').
+example(10,'i').
+example(11,'l').
+example(12,'k').
+example(13,'m').
+example(14,'f').
+example(15,'p').
+example(16,'s').
+example(17,'t').
+example(18,'w').
+example(19,'y').
+example(20,'v').
+
+getExampleIDs([],[]).
+getExampleIDs([Haa|Taa],[Hid|Tid]) :-
+	example(Hid,Haa),
+	getExampleIDs(Taa,Tid).
+
+
+%MAPFQSNKDL
+%A = [m,a,p,f,q,s,n,k,d,l],
+%S1 = [13,1,15,14,6,16,3,12,4,11] ?
+%A = ['m', 'a', 'p', 'f', 'q', 's', 'n', 'k', 'd', 'l'], getExampleIDs(A,S1).
+sequence(1,[13,1,15,14,6,16,3,12,4,11]).
+
+% MLAPFEKTAAARSII
+%getExampleIDs(['m', 'l', 'a', 'p', 'f', 'e', 'k', 't', 'a', 'a', 'a', 'r', 's', 'i', 'i'],Seq2).
+sequence(2,[13,11,1,15,14,7,12,17,1,1,1,2,16,10,10]).
+
+%getExampleIDs(['h', 'e', 'a', 'g', 'a', 'w', 'g', 'h', 'e', 'e'],Seq3)
+sequence(3,[9,7,1,8,1,18,8,9,7,7]).
+%getExampleIDs(['p', 'a', 'w', 'h', 'e', 'a', 'e'],Seq4)
+sequence(4,[15,1,18,9,7,1,7]).
+
+ppAAList([]) :- nl.
+ppAAList([H|T]) :-
+	format("~w",[H]),
+	ppAAList(T).
+
+convertToString(TheIndexList) :-
+	getExampleIDs(TheAAList,TheIndexList),
+	ppAAList(TheAAList).
+
+