gmlst 0.1.0__py3-none-any.whl

gmlst/__init__.py

@@ -0,0 +1,3 @@
+"""gmlst – Fast MLST, cgMLST/wgMLST typing via multiple alignment backends."""
+
+__version__ = "0.1.0"

gmlst/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for ``python -m gmlst``."""
+
+from gmlst.cli import main
+
+if __name__ == "__main__":
+    main()

gmlst/aligners/__init__.py

@@ -0,0 +1,44 @@
+"""Alignment backend registry."""
+
+from gmlst.aligners.base import Aligner, AlignmentResult, AlleleMatch
+from gmlst.aligners.blastn import BlastnAligner
+from gmlst.aligners.kma import KmaAligner
+from gmlst.aligners.minimap2 import Minimap2Aligner
+from gmlst.aligners.nucmer import NucmerAligner
+
+_REGISTRY: dict[str, type[Aligner]] = {
+    "blastn": BlastnAligner,
+    "kma": KmaAligner,
+    "minimap2": Minimap2Aligner,
+    "nucmer": NucmerAligner,
+}
+
+AVAILABLE_BACKENDS: list[str] = list(_REGISTRY.keys())
+
+
+def get_aligner(name: str, **kwargs) -> Aligner:
+    """Return an instantiated aligner by backend name.
+
+    Parameters
+    ----------
+    name:
+        Backend name (blastn, kma, minimap2, nucmer).
+    **kwargs:
+        Additional arguments passed to aligner constructor.
+        For blastn: threads (int, default=1)
+    """
+    name = name.lower()
+    if name not in _REGISTRY:
+        raise ValueError(
+            f"Unknown backend '{name}'. Available: {', '.join(AVAILABLE_BACKENDS)}"
+        )
+    return _REGISTRY[name](**kwargs)
+
+
+__all__ = [
+    "Aligner",
+    "AlleleMatch",
+    "AlignmentResult",
+    "AVAILABLE_BACKENDS",
+    "get_aligner",
+]

gmlst/aligners/base.py

@@ -0,0 +1,181 @@
+"""Core types and Aligner Protocol shared by all backends."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal, Protocol, runtime_checkable
+
+# ---------------------------------------------------------------------------
+# Data classes
+# ---------------------------------------------------------------------------
+
+CallType = Literal["exact", "closest", "novel", "partial", "missing"]
+
+
+@dataclass
+class AlleleMatch:
+    """Normalised alignment hit for one allele against one locus.
+
+    All backends must convert their native output into this structure so that
+    downstream calling logic is backend-agnostic.
+    """
+
+    locus: str
+    """Gene name, e.g. ``"abcZ"``."""
+
+    allele_id: str
+    """Allele number as a string, e.g. ``"42"``."""
+
+    identity: float
+    """Percent identity (0–100)."""
+
+    coverage: float
+    """Fraction of the allele sequence covered by the alignment (0.0–1.0)."""
+
+    strand: str = "+"
+    """Alignment strand: ``"+"`` or ``"-"``."""
+
+    score: float = 0.0
+    """Backend-specific score, normalised to 0–100 where possible."""
+
+    depth: float | None = None
+    """Mean read depth across the allele (FASTQ inputs only)."""
+
+    alignment_length: int = 0
+    """Length of the alignment block in bases."""
+
+    sequence: str | None = None
+    """Extracted sequence for novel alleles (optional)."""
+    copy_count: int = 1
+    """Approximate number of distinct genomic occurrences for this allele."""
+    query_contig: str | None = None
+    """Contig/chromosome identifier for FASTA assembly mappings."""
+    query_contig_length: int | None = None
+    """Contig/chromosome length when available."""
+    query_start: int | None = None
+    """0-based start coordinate on the query contig/chromosome."""
+    query_end: int | None = None
+    """0-based end coordinate on the query contig/chromosome."""
+    allele_length: int | None = None
+    """Allele/template full length when available."""
+    allele_start: int | None = None
+    """0-based aligned start on allele/template."""
+    allele_end: int | None = None
+    """0-based aligned end on allele/template."""
+    """Length of the alignment block in bases."""
+
+    @property
+    def call_type(self) -> CallType:
+        """Classify this match using tseemann-compatible thresholds."""
+        if self.identity == 100.0 and self.coverage >= 1.0:
+            return "exact"
+        if self.identity >= 95.0 and self.coverage >= 0.95:
+            return "closest"
+        if self.coverage >= 0.95:
+            # Good coverage but low identity → likely a novel allele
+            return "novel"
+        if self.coverage > 0.0:
+            return "partial"
+        return "missing"
+
+    @property
+    def is_exact(self) -> bool:
+        return self.identity == 100.0 and self.coverage >= 1.0
+
+
+@dataclass
+class AlignmentResult:
+    """All allele matches produced by one backend for one sample."""
+
+    sample_id: str
+    matches: list[AlleleMatch] = field(default_factory=list)
+    failed_loci: list[str] = field(default_factory=list)
+    backend: str = ""
+    runtime_seconds: float = 0.0
+    _matches_by_locus: dict[str, list[AlleleMatch]] | None = field(
+        default=None,
+        init=False,
+        repr=False,
+    )
+
+    def matches_for(self, locus: str) -> list[AlleleMatch]:
+        """Return all hits for a single locus, sorted best-first."""
+        if self._matches_by_locus is None:
+            grouped: dict[str, list[AlleleMatch]] = defaultdict(list)
+            for match in self.matches:
+                grouped[match.locus].append(match)
+            for hits in grouped.values():
+                hits.sort(
+                    key=lambda m: (m.identity, m.coverage, m.depth or 0.0),
+                    reverse=True,
+                )
+            self._matches_by_locus = dict(grouped)
+        return self._matches_by_locus.get(locus, [])
+
+
+# ---------------------------------------------------------------------------
+# Aligner Protocol
+# ---------------------------------------------------------------------------
+
+
+@runtime_checkable
+class Aligner(Protocol):
+    """Interface every alignment backend must satisfy.
+
+    Backends are stateless; per-run state lives in ``index_dir``.
+    """
+
+    @property
+    def name(self) -> str:
+        """Short identifier, e.g. ``"blastn"``."""
+        ...
+
+    @property
+    def supports_fastq(self) -> bool:
+        """Whether this backend can handle raw FASTQ reads."""
+        ...
+
+    def check_dependencies(self) -> None:
+        """Raise ``RuntimeError`` if required external tools are missing."""
+        ...
+
+    def index(self, allele_fastas: list[Path], index_dir: Path) -> Path:
+        """Build a backend-specific index from allele FASTA files.
+
+        Parameters
+        ----------
+        allele_fastas:
+            One FASTA file per locus (e.g. ``arcC.tfa``).
+        index_dir:
+            Directory in which to write index artifacts.
+
+        Returns
+        -------
+        Path
+            The index path (file or directory) to pass back to :meth:`align`.
+        """
+        ...
+
+    def align(
+        self,
+        sample: Path | tuple[Path, Path],
+        index_path: Path,
+        loci: list[str],
+        input_type: Literal["fasta", "fastq"],
+    ) -> AlignmentResult:
+        """Run alignment and return normalised results.
+
+        Parameters
+        ----------
+        sample:
+            Path to query file, or paired FASTQ paths ``(R1, R2)``.
+        index_path:
+            Path returned by :meth:`index`.
+        loci:
+            Gene names expected in the scheme (used to detect missing loci).
+        input_type:
+            ``"fasta"`` for assembled genomes, ``"fastq"`` for raw reads.
+        """
+        ...

gmlst/aligners/blastn.py

@@ -0,0 +1,287 @@
+"""BLASTN alignment backend.
+
+Strategy
+--------
+FASTA input (assembled genome):
+    Query  = allele sequences (all loci concatenated)
+    Subject = genome contigs  → makeblastdb on genome
+    This matches tseemann/mlst behaviour exactly.
+
+FASTQ input:
+    Not supported — BLASTN cannot handle raw reads.
+    Use minimap2 or kma backends instead.
+
+Output format
+-------------
+We use BLAST tabular output format 6 with the following fields::
+
+    qseqid sseqid pident length qlen slen qstart qend sstart send evalue bitscore
+
+The query sequence id encodes locus and allele, e.g. ``arcC_1``.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from pathlib import Path
+from typing import Literal
+
+from gmlst.aligners.base import AlignmentResult, AlleleMatch
+from gmlst.utils import require_tool, run_cmd, temp_dir
+
+logger = logging.getLogger("gmlst.aligners.blastn")
+
+# Tabular fields we request from BLAST
+_OUTFMT = (
+    "6 qseqid sseqid pident length qlen qstart qend sstart send evalue bitscore sseq"
+)
+
+
+class BlastnAligner:
+    """MLST aligner using NCBI BLASTN."""
+
+    def __init__(
+        self, threads: int = 1, count_same_copy: bool = False, **kwargs
+    ) -> None:
+        self.threads = threads
+        self.count_same_copy = count_same_copy
+
+    @property
+    def name(self) -> str:
+        return "blastn"
+
+    @property
+    def supports_fastq(self) -> bool:
+        return False
+
+    def check_dependencies(self) -> None:
+        require_tool("blastn")
+        require_tool("makeblastdb")
+
+    # ------------------------------------------------------------------
+    # Indexing
+    # ------------------------------------------------------------------
+
+    def index(self, allele_fastas: list[Path], index_dir: Path) -> Path:
+        """Concatenate all allele FASTAs and build a BLAST nucleotide database.
+
+        Returns
+        -------
+        Path
+            The BLAST database prefix (e.g. ``index_dir / "alleles"``).
+        """
+        require_tool("makeblastdb")
+        index_dir.mkdir(parents=True, exist_ok=True)
+
+        # Merged FASTA path
+        merged = index_dir / "alleles.fasta"
+        with merged.open("wb") as out:
+            for fasta in sorted(allele_fastas):
+                with fasta.open("rb") as f:
+                    import shutil
+
+                    shutil.copyfileobj(f, out)
+        merged = index_dir / "alleles.fasta"
+        with merged.open("w") as out:
+            for fasta in sorted(allele_fastas):
+                out.write(fasta.read_text())
+
+        db_prefix = index_dir / "alleles"
+
+        # Build BLAST db only if stale
+        nhr = db_prefix.with_suffix(".nhr")
+        if not nhr.exists() or nhr.stat().st_mtime < merged.stat().st_mtime:
+            logger.info("Building BLAST database at %s …", db_prefix)
+            run_cmd(
+                [
+                    "makeblastdb",
+                    "-in",
+                    str(merged),
+                    "-dbtype",
+                    "nucl",
+                    "-out",
+                    str(db_prefix),
+                    "-title",
+                    "gmlst_alleles",
+                ]
+            )
+        return db_prefix
+
+    # ------------------------------------------------------------------
+    # Alignment
+    # ------------------------------------------------------------------
+
+    def align(
+        self,
+        sample: Path,
+        index_path: Path,
+        loci: list[str],
+        input_type: Literal["fasta", "fastq"],
+    ) -> AlignmentResult:
+        """Run BLASTN: allele sequences → assembled genome.
+
+        For FASTA inputs the allele DB is used as **query** and the genome
+        as **subject** (``-db`` flag points to the allele index, genome is
+        passed with ``-query``).
+
+        Wait — tseemann does it the other way: genome is the db, alleles are
+        queries.  We follow the same convention for compatibility:
+
+            blastn -query alleles.fasta -db genome -outfmt 6 …
+
+        This avoids building a db per sample (samples are queries would need
+        per-sample dbs).  Instead we build one allele db and query each
+        sample against it.
+
+        Actually the most efficient approach for assembled genomes is:
+            -query <allele_fasta>  -subject <genome>  (no db needed per run)
+        Or build a db from the genome once per sample (tseemann does this).
+
+        We use ``-query <alleles> -subject <genome>`` for simplicity — no
+        per-sample database build required.
+        """
+        if input_type == "fastq":
+            raise ValueError(
+                "BlastnAligner does not support FASTQ input. "
+                "Use minimap2 or kma backend."
+            )
+
+        sample_id = sample.stem.split(".")[0]
+        t0 = time.perf_counter()
+
+        # The index_path is the allele db prefix; we query alleles against genome
+        alleles_fasta = index_path.parent / "alleles.fasta"
+
+        with temp_dir("gmlst_blastn_") as tmp:
+            out_file = tmp / "hits.tsv"
+            run_cmd(
+                [
+                    "blastn",
+                    "-query",
+                    str(alleles_fasta),
+                    "-subject",
+                    str(sample),
+                    "-outfmt",
+                    _OUTFMT,
+                    "-out",
+                    str(out_file),
+                    "-perc_identity",
+                    "80",
+                    "-dust",
+                    "no",
+                    "-num_threads",
+                    str(self.threads),
+                ],
+            )
+            matches = _parse_blast_output(
+                out_file,
+                loci,
+                count_same_copy=self.count_same_copy,
+            )
+
+        runtime = time.perf_counter() - t0
+        called_loci = {m.locus for m in matches}
+        failed = [loc for loc in loci if loc not in called_loci]
+
+        return AlignmentResult(
+            sample_id=sample_id,
+            matches=matches,
+            failed_loci=failed,
+            backend=self.name,
+            runtime_seconds=runtime,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Output parsing
+# ---------------------------------------------------------------------------
+
+
+def _parse_blast_output(
+    path: Path,
+    loci: list[str],
+    *,
+    count_same_copy: bool = False,
+) -> list[AlleleMatch]:
+    """Parse BLAST tabular output and return :class:`AlleleMatch` objects.
+
+    Fields (format 6 custom)::
+
+        qseqid sseqid pident length qlen qstart qend sstart send evalue bitscore
+
+    The query id encodes locus and allele as ``<locus>_<allele_id>``.
+    We take the **best hit per (locus, allele_id)** pair — highest identity,
+    then longest alignment.
+    """
+    loci_set = set(loci)
+    # best[(locus, allele_id)] = AlleleMatch
+    best: dict[tuple[str, str], AlleleMatch] = {}
+    copies: dict[tuple[str, str], set[tuple[str, str, str]]] = {}
+
+    if not path.exists():
+        return []
+
+    with path.open() as fh:
+        for line in fh:
+            line = line.strip()
+            if not line or line.startswith("#"):
+                continue
+            parts = line.split("\t")
+            if len(parts) < 11:
+                continue
+
+            qseqid = parts[0]
+            pident = float(parts[2])
+            aln_len = int(parts[3])
+            qlen = int(parts[4])
+
+            # Parse locus + allele from query id (e.g. "arcC_1")
+            locus, allele_id = _split_allele_id(qseqid)
+            if locus not in loci_set:
+                continue
+
+            coverage = aln_len / qlen if qlen > 0 else 0.0
+            key = (locus, allele_id)
+            if count_same_copy:
+                sseqid = parts[1]
+                sstart = parts[7]
+                send = parts[8]
+                start, end = (sstart, send) if sstart <= send else (send, sstart)
+                copies.setdefault(key, set()).add((sseqid, start, end))
+
+            existing = best.get(key)
+            if existing is None or (
+                pident > existing.identity
+                or (pident == existing.identity and coverage > existing.coverage)
+            ):
+                # Extract subject sequence if available (for novel alleles)
+                sequence = parts[11] if len(parts) > 11 else None
+
+                best[key] = AlleleMatch(
+                    locus=locus,
+                    allele_id=allele_id,
+                    identity=pident,
+                    coverage=coverage,
+                    alignment_length=aln_len,
+                    score=float(parts[10]),  # bitscore
+                    sequence=sequence,
+                )
+
+    if count_same_copy:
+        for key, match in best.items():
+            match.copy_count = max(1, len(copies.get(key, set())))
+
+    return list(best.values())
+
+
+def _split_allele_id(qseqid: str) -> tuple[str, str]:
+    """Split ``arcC_1`` → ``("arcC", "1")``.
+
+    Handles both ``_`` and ``-`` separators.
+    """
+    for sep in ("_", "-"):
+        if sep in qseqid:
+            locus, allele_id = qseqid.rsplit(sep, 1)
+            return locus, allele_id
+    return qseqid, "1"

gmlst/aligners/kma.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+import gzip
+import shutil
+import subprocess
+import time
+from pathlib import Path
+from typing import Literal
+
+from gmlst.aligners.base import AlignmentResult, AlleleMatch
+from gmlst.readers.sample import SampleInput
+from gmlst.utils import temp_dir
+
+
+class KmaAligner:
+    def __init__(self, threads: int = 1, **kwargs) -> None:
+        self.threads = threads
+        self.fastq_mem_mode = bool(kwargs.get("fastq_mem_mode", False))
+
+    @property
+    def name(self) -> str:
+        return "kma"
+
+    @property
+    def supports_fastq(self) -> bool:
+        return True
+
+    def check_dependencies(self) -> None:
+        if shutil.which("kma") is None:
+            raise RuntimeError(
+                "kma backend requires KMA binary. Install by source build: "
+                "git clone https://github.com/genomicepidemiology/kma.git "
+                "&& cd kma && make"
+            )
+
+    def index(self, allele_fastas: list[Path], index_dir: Path) -> Path:
+        index_dir.mkdir(parents=True, exist_ok=True)
+        merged = index_dir / "alleles.fasta"
+        db_prefix = index_dir / "kma_db"
+
+        with merged.open("w") as out:
+            for fasta in sorted(allele_fastas):
+                opener = gzip.open if fasta.suffix == ".gz" else open
+                with opener(fasta, "rt") as fh:  # type: ignore[call-overload]
+                    out.write(fh.read())
+
+        subprocess.run(
+            [
+                "kma",
+                "index",
+                "-i",
+                str(merged),
+                "-o",
+                str(db_prefix),
+            ],
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+        return index_dir
+
+    def align(
+        self,
+        sample: Path | tuple[Path, Path],
+        index_path: Path,
+        loci: list[str],
+        input_type: Literal["fasta", "fastq"],
+    ) -> AlignmentResult:
+        sample_path = sample[0] if isinstance(sample, tuple) else sample
+        sample_id = SampleInput.from_path(sample_path).sample_id
+        t0 = time.perf_counter()
+
+        db_prefix = index_path / "kma_db"
+        with temp_dir("gmlst_kma_") as tmp_dir:
+            out_prefix = tmp_dir / "kma_out"
+            cmd = [
+                "kma",
+                "-o",
+                str(out_prefix),
+                "-t_db",
+                str(db_prefix),
+                "-t",
+                str(max(1, self.threads)),
+            ]
+            if isinstance(sample, tuple):
+                cmd.extend(["-ipe", str(sample[0]), str(sample[1])])
+            else:
+                cmd.extend(["-i", str(sample)])
+            if input_type == "fasta":
+                cmd.append("-asm")
+            else:
+                cmd.append("-ill")
+                if self.fastq_mem_mode:
+                    cmd.append("-mem_mode")
+            subprocess.run(cmd, check=True, capture_output=True, text=True)
+
+            res_file = out_prefix.with_suffix(".res")
+            matches = _parse_kma_res(res_file, loci, input_type)
+
+        runtime = time.perf_counter() - t0
+        called_loci = {m.locus for m in matches}
+        failed = [loc for loc in loci if loc not in called_loci]
+        return AlignmentResult(
+            sample_id=sample_id,
+            matches=matches,
+            failed_loci=failed,
+            backend=self.name,
+            runtime_seconds=runtime,
+        )
+
+
+def _parse_kma_res(
+    path: Path,
+    loci: list[str],
+    input_type: Literal["fasta", "fastq"],
+) -> list[AlleleMatch]:
+    loci_set = set(loci)
+    results: list[AlleleMatch] = []
+    with path.open() as fh:
+        header: dict[str, int] | None = None
+        for line in fh:
+            line = line.rstrip("\n")
+            if not line:
+                continue
+            if line.startswith("#"):
+                cols = line.lstrip("#").split("\t")
+                header = {name: idx for idx, name in enumerate(cols)}
+                continue
+            if header is None:
+                continue
+
+            cols = line.split("\t")
+            template = cols[header.get("Template", 0)]
+            locus, allele_id = _split_template(template)
+            if locus not in loci_set:
+                continue
+
+            identity = float(cols[header.get("Template_Identity", 4)])
+            coverage = float(cols[header.get("Template_Coverage", 5)]) / 100.0
+            score = float(cols[header.get("Score", 1)])
+            raw_depth = float(cols[header.get("Depth", 8)])
+            depth = raw_depth if input_type == "fastq" else None
+            template_len = int(float(cols[header.get("Template_length", 3)]))
+
+            results.append(
+                AlleleMatch(
+                    locus=locus,
+                    allele_id=allele_id,
+                    identity=identity,
+                    coverage=coverage,
+                    score=score,
+                    depth=depth,
+                    alignment_length=template_len,
+                )
+            )
+
+    return results
+
+
+def _split_template(template: str) -> tuple[str, str]:
+    if "_" in template:
+        return tuple(template.rsplit("_", 1))  # type: ignore[return-value]
+    if "-" in template:
+        return tuple(template.rsplit("-", 1))  # type: ignore[return-value]
+    return (template, "")