gside 0.1.1__py3-none-any.whl

gside/__init__.py

@@ -0,0 +1,15 @@
+"""gside — Genome Species IDentification Engine."""
+
+from __future__ import annotations
+
+try:
+    from importlib.metadata import PackageNotFoundError, version
+
+    try:
+        __version__ = version("gside")
+    except PackageNotFoundError:
+        __version__ = "0.1.0.dev"
+except Exception:  # pragma: no cover — extremely defensive fallback
+    __version__ = "0.1.0.dev"
+
+__all__ = ["__version__"]

gside/__main__.py

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

gside/analysis/ani_identifier.py

@@ -0,0 +1,184 @@
+"""ANI-based species identification (species-id plan A: panel / skani_gtdb / mash_refseq)."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from gside.config import SPECIES_DB_DIR
+from gside.engine.backends.skani import AniHit
+
+_DB_BY_MODE = {
+    "panel": "D2_ani",
+    "skani_gtdb": "D2_skani_gtdb",
+    "mash_refseq": "D3_mash",
+}
+
+_ANI_HIGH = 95.0
+_ANI_MEDIUM = 93.0
+_AF_MIN = 0.65
+_MASH_IDENTITY_HIGH = 0.97
+_TOP_N = 10
+
+
+@dataclass
+class AniIdResult:
+    method: str
+    database: dict[str, str]
+    result: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "analysis_type": "species_identification",
+            "method": self.method,
+            "database": self.database,
+            "result": self.result,
+        }
+
+
+def _hits_from_rows(rows: list[tuple[str, float, float]]) -> list[AniHit]:
+    return [AniHit(ref=r, ani=a, aligned_fraction=af) for r, a, af in rows]
+
+
+def _skani_search(query: str | Path, db: Path) -> list[AniHit]:
+    from gside.engine.backends.skani import SkaniBackend
+
+    return SkaniBackend().search(Path(query), db)
+
+
+def _mash_dist(query: str | Path, msh: Path) -> list[tuple[str, float]]:
+    from gside.config import which
+    from gside.engine._env import require_bin
+    from gside.engine.backends.kmer import MashBackend
+
+    mash = require_bin(
+        "mash",
+        hint="mash not found — install via pixi (conda) or point GSIDE_PIXI_BIN at a bin dir",
+        resolver=which,
+    )
+    # mash CLI is `dist <reference> <query>`: output column 0 carries the
+    # reference (sketch DB genome) IDs, so the sketch goes in the first slot.
+    # MashBackend.distance() places its first positional there; max_distance=1.0
+    # is mash's own default cutoff, i.e. no extra filtering vs. a bare `mash dist`.
+    results = MashBackend(binary=mash).distance(Path(msh), Path(query), max_distance=1.0)
+    return [(r.reference_id, 1.0 - r.distance) for r in results]
+
+
+def _mash_species(ref_id: str) -> str:
+    return ref_id
+
+
+def _load_taxa_map(db_dir: Path) -> dict[str, str]:
+    for candidate in ("metadata.tsv", "taxa_map.tsv"):
+        path = db_dir / candidate
+        if path.is_file():
+            mapping: dict[str, str] = {}
+            for ln in path.read_text(encoding="utf-8").splitlines()[1:]:
+                cols = ln.split("\t")
+                if len(cols) >= 2:
+                    mapping[cols[0].strip()] = cols[1].strip()
+            return mapping
+    return {}
+
+
+def _db_version(db_dir: Path, name: str) -> str:
+    manifest = db_dir.parent / "manifests" / f"{name}.json"
+    if manifest.is_file():
+        try:
+            checksum = json.loads(manifest.read_text()).get("checksum", "")
+            return checksum[:8] if checksum else "unknown"
+        except json.JSONDecodeError:
+            return "unknown"
+    return "unknown"
+
+
+def identify_by_ani(
+    contigs: str | Path,
+    mode: str,
+    db_dir: str | Path | None = None,
+) -> AniIdResult:
+    if mode not in _DB_BY_MODE:
+        raise ValueError(f"unsupported ANI mode {mode!r}; expected one of {sorted(_DB_BY_MODE)}")
+    db_name = _DB_BY_MODE[mode]
+    base = Path(db_dir) if db_dir else SPECIES_DB_DIR / db_name
+    taxa = _load_taxa_map(base)
+    database = {"name": db_name, "version": _db_version(base, db_name)}
+
+    if mode == "mash_refseq":
+        msh = base / "mash.msh"
+        if not msh.exists():
+            msh = base / "payload.bin"
+        if not msh.exists():
+            raise RuntimeError(
+                f"mash sketch DB not found in {base} (run: gside db setup --tier mash)"
+            )
+        mash_rows = _mash_dist(contigs, msh)
+        mash_top = sorted(mash_rows, key=lambda r: -r[1])[:_TOP_N]
+        best_ref, best_identity = mash_top[0] if mash_top else ("", 0.0)
+        species = taxa.get(best_ref, _mash_species(best_ref)) if best_ref else "Unknown"
+        confidence = "high" if best_identity >= _MASH_IDENTITY_HIGH else "low"
+        result = {
+            "species": species or "Unknown",
+            "confidence": confidence,
+            "identity": best_identity,
+            "top_hits": [{"genome": r, "identity": i} for r, i in mash_top],
+        }
+        if 0.90 <= best_identity < _MASH_IDENTITY_HIGH:
+            result["confidence"] = "medium"
+        return AniIdResult(method=mode, database=database, result=result)
+
+    skani_db = base / "panel.sketch" if (base / "panel.sketch").exists() else base
+    skani_hits = sorted(
+        _skani_search(contigs, skani_db), key=lambda h: (-h.ani, -h.aligned_fraction)
+    )
+    top = skani_hits[:_TOP_N]
+    best = top[0] if top else None
+
+    species, confidence = "Unknown", "low"
+    if best is not None:
+        if best.ani >= _ANI_HIGH and best.aligned_fraction >= _AF_MIN:
+            species, confidence = taxa.get(best.ref, best.ref), "high"
+        elif _ANI_MEDIUM <= best.ani < _ANI_HIGH and best.aligned_fraction >= _AF_MIN:
+            species, confidence = taxa.get(best.ref, best.ref), "medium"
+
+    result = {
+        "species": species,
+        "confidence": confidence,
+        "ani": best.ani if best else None,
+        "aligned_fraction": best.aligned_fraction if best else None,
+        "top_hits": [
+            {
+                "genome": h.ref,
+                "species": taxa.get(h.ref, h.ref),
+                "ani": h.ani,
+                "af": h.aligned_fraction,
+            }
+            for h in top
+        ],
+    }
+    return AniIdResult(method=mode, database=database, result=result)
+
+
+def main() -> None:
+    import argparse
+
+    parser = argparse.ArgumentParser(description="ANI species identifier")
+    parser.add_argument("contigs")
+    parser.add_argument("--mode", required=True, choices=sorted(_DB_BY_MODE))
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args()
+
+    res = identify_by_ani(args.contigs, args.mode)
+    if args.json:
+        print(json.dumps(res.to_dict(), ensure_ascii=False, indent=2))
+    else:
+        r = res.result
+        print(f"Species: {r['species']} ({r['confidence']}) via {res.method}")
+        for h in r.get("top_hits", [])[:5]:
+            print(f"  {h['genome']}: {h.get('ani', h.get('identity'))}")
+
+
+if __name__ == "__main__":
+    main()

gside/analysis/multigene_identifier.py

@@ -0,0 +1,218 @@
+"""Multi-gene species identifier using the expanded markers BLAST database.
+
+Replaces the single-gene species_identifier for routine use. Reads
+marker_rules.yaml for gene combination logic and scoring.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from gside.config import SPECIES_DB_DIR
+
+_MARKERS_FASTA = SPECIES_DB_DIR / "D1_marker" / "markers.fasta"
+_MARKER_RULES = SPECIES_DB_DIR / "D1_marker" / "marker_rules.yaml"
+
+_MIN_IDENTITY = 85.0
+_MIN_COVERAGE = 60.0
+_HIGH_CONF = 90.0
+
+
+@dataclass
+class MultiGeneResult:
+    species: str = "Unknown"
+    confidence: str = "low"
+    detected_markers: list[dict[str, Any]] = field(default_factory=list)
+    all_hits: list[dict[str, Any]] = field(default_factory=list)
+    matched_rule: str = ""
+    method: str = "multigene"
+    database_version: str = "unknown"
+    notes: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "species": self.species,
+            "confidence": self.confidence,
+            "method": self.method,
+            "database": {"name": "species_markers_v2", "version": self.database_version},
+            "detected_markers": self.detected_markers,
+            "matched_rule": self.matched_rule,
+            "notes": self.notes,
+            "interpretation": self._interpret(),
+        }
+
+    def _interpret(self) -> str:
+        if self.species == "Unknown":
+            return "No species-specific markers detected"
+        markers = [m["gene"] for m in self.detected_markers]
+        return f"Identified as {self.species} based on: {', '.join(markers)}"
+
+
+def _db_version() -> str:
+    try:
+        return hashlib.sha256(_MARKERS_FASTA.read_bytes()).hexdigest()[:8]
+    except OSError:
+        return "unknown"
+
+
+def _load_rules() -> list[dict[str, Any]]:
+    if not _MARKER_RULES.is_file():
+        return []
+    data = yaml.safe_load(_MARKER_RULES.read_text())
+    return list(data.get("rules", []))
+
+
+def _blast_contigs(contigs_fasta: str) -> list[dict[str, Any]]:
+    from gside.config import which
+    from gside.engine._env import require_bin
+    from gside.engine.backends.blast import BlastBackend
+
+    blastn = require_bin(
+        "blastn",
+        hint="blastn not found — install via pixi (conda) or point GSIDE_PIXI_BIN at a bin dir",
+        resolver=which,
+    )
+
+    db = str(SPECIES_DB_DIR / "D1_marker" / "markers_blastdb")
+    backend = BlastBackend(binary=blastn)
+    engine_hits = backend.find(
+        query=Path(contigs_fasta),
+        db_path=db,
+        evalue=1e-10,
+        word_size=11,
+    )
+    hits = []
+    for hit in engine_hits:
+        seqid = hit.subject_id
+        parts = seqid.split("~~~")
+        gene = parts[1].lower() if len(parts) >= 2 else seqid.lower()
+        hits.append(
+            {
+                "gene": gene,
+                "identity": hit.identity,
+                "coverage": round(hit.subject_coverage, 1),
+                "ref_len": hit.subject_length,
+                "seqid": seqid,
+            }
+        )
+    return hits
+
+
+def identify_multigene(contigs_fasta: str) -> MultiGeneResult:
+    raw_hits = _blast_contigs(contigs_fasta)
+    rules = _load_rules()
+
+    best_hits: dict[str, dict[str, Any]] = {}
+    for hit in raw_hits:
+        gene = hit["gene"]
+        if gene not in best_hits or hit["identity"] > best_hits[gene]["identity"]:
+            best_hits[gene] = hit
+
+    significant: dict[str, dict[str, Any]] = {}
+    for hit in raw_hits:
+        if hit["identity"] < _MIN_IDENTITY or hit["coverage"] < _MIN_COVERAGE:
+            continue
+        gene = hit["gene"]
+        if gene not in significant or hit["identity"] > significant[gene]["identity"]:
+            significant[gene] = hit
+
+    result = MultiGeneResult(database_version=_db_version())
+    result.all_hits = list(best_hits.values())
+
+    priority_species = set()
+    for rule in rules:
+        if rule.get("priority_over"):
+            for _target in rule["priority_over"]:
+                priority_species.add(rule["species"])
+
+    best_species = "Unknown"
+    best_conf = "low"
+    best_score = 0
+    best_rule = ""
+
+    for rule in rules:
+        genes = [g.lower() for g in rule.get("genes", [])]
+        min_hits = rule.get("min_hits", 1)
+        min_id = rule.get("min_identity", _HIGH_CONF)
+        exclude = [g.lower() for g in rule.get("exclude_genes", [])]
+
+        matched = []
+        for gene in genes:
+            if (
+                gene in significant
+                and significant[gene]["identity"] >= min_id
+                and gene not in exclude
+            ):
+                matched.append(gene)
+
+        excluded_present = [g for g in exclude if g in significant]
+
+        if len(matched) >= min_hits and not excluded_present:
+            score = len(matched)
+            avg_id = sum(significant[g]["identity"] for g in matched) / len(matched)
+            conf = "high" if avg_id >= _HIGH_CONF else "medium"
+
+            if score > best_score or (score == best_score and conf == "high"):
+                best_species = rule["species"]
+                best_conf = conf
+                best_score = score
+                best_rule = f"{'+'.join(matched)} ({len(matched)}/{min_hits} required)"
+
+    result.species = best_species
+    result.confidence = best_conf
+    result.matched_rule = best_rule
+
+    if significant:
+        result.detected_markers = [
+            {"gene": g, "identity": h["identity"], "coverage": h["coverage"]}
+            for g, h in sorted(significant.items(), key=lambda x: -x[1]["identity"])
+        ]
+
+    if best_species.startswith("Vibrio_cholerae"):
+        if "ctxa" in significant:
+            result.notes.append("ctxA detected - toxigenic Vibrio cholerae strain.")
+        else:
+            result.notes.append("ctxA not detected - non-toxigenic by this marker assay.")
+
+    if not significant and raw_hits:
+        near = [h for h in raw_hits if h["identity"] >= 75 and h["coverage"] >= 20]
+        if near:
+            result.notes.append(
+                f"Near-threshold hits detected (identity 75-85%): "
+                f"{', '.join(h['gene'] for h in near[:5])}. "
+                "Possible divergence or contamination; ANI recheck advised."
+            )
+
+    return result
+
+
+def main() -> None:
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Multi-gene species identifier")
+    parser.add_argument("contigs")
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args()
+
+    res = identify_multigene(args.contigs)
+    if args.json:
+        print(json.dumps(res.to_dict(), ensure_ascii=False, indent=2))
+    else:
+        d = res.to_dict()
+        print(f"Species: {d['species']} ({d['confidence']})")
+        print(f"Method: {d['method']}, Rule: {d['matched_rule']}")
+        for m in d.get("detected_markers", []):
+            print(f"  {m['gene']}: {m['identity']}% identity, {m['coverage']}% coverage")
+        for n in d.get("notes", []):
+            print(f"  NOTE: {n}")
+        print(d["interpretation"])
+
+
+if __name__ == "__main__":
+    main()

gside/analysis/sourmash_identifier.py

@@ -0,0 +1,125 @@
+"""sourmash gather-based species identification (species-id plan B)."""
+
+from __future__ import annotations
+
+import csv
+import json
+import subprocess
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from gside.config import SPECIES_DB_DIR
+
+_FUW_HIGH = 0.90
+_FUW_MEDIUM = 0.70
+_MIXTURE_MEMBER = 0.10
+
+
+@dataclass
+class SourmashIdResult:
+    method: str
+    database: dict[str, str]
+    result: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "analysis_type": "species_identification",
+            "method": self.method,
+            "database": self.database,
+            "result": self.result,
+        }
+
+
+def _run(cmd: list[str]) -> str:
+    result = subprocess.run(cmd, capture_output=True, text=True, timeout=3600)
+    if result.returncode != 0:
+        raise RuntimeError(f"{cmd[0]} failed: {result.stderr.strip()}")
+    return result.stdout
+
+
+def _gather_and_tax(contigs: str | Path, db_dir: Path) -> list[dict[str, Any]]:
+    db_zip = db_dir / "gtdb-reps-k31.zip"
+    lineages = db_dir / "lineages.csv"
+    if not db_zip.exists() or not lineages.exists():
+        raise RuntimeError(
+            f"sourmash GTDB database not found in {db_dir} (run: gside db setup --tier sourmash)"
+        )
+    with tempfile.TemporaryDirectory(prefix="gside-sourmash-") as tmp:
+        work = Path(tmp)
+        sig = work / "query.sig"
+        gather_csv = work / "gather.csv"
+        _run(["sourmash", "sketch", "dna", "-p", "k=31,scaled=1000", str(contigs), "-o", str(sig)])
+        try:
+            _run(["sourmash", "gather", str(sig), str(db_zip), "-o", str(gather_csv)])
+        except RuntimeError:
+            return []
+        rows = (
+            list(csv.DictReader(gather_csv.read_text().splitlines()))
+            if gather_csv.is_file()
+            else []
+        )
+    lineage_map = _lineage_map(lineages)
+    out: list[dict[str, Any]] = []
+    for row in rows:
+        name = row.get("name", "")
+        try:
+            fuw = float(row.get("f_unique_weighted", 0.0))
+        except ValueError:
+            fuw = 0.0
+        out.append({"lineage": lineage_map.get(name, name), "f_unique_weighted": fuw})
+    return out
+
+
+def _lineage_map(path: Path) -> dict[str, str]:
+    if not path.is_file():
+        return {}
+    mapping: dict[str, str] = {}
+    with path.open() as fh:
+        for row in csv.reader(fh):
+            if len(row) >= 2:
+                mapping[row[0]] = row[-1].split(";")[-1].strip()
+    return mapping
+
+
+def _db_version(db_dir: Path) -> str:
+    manifest = db_dir.parent / "manifests" / "D4_sourmash.json"
+    if manifest.is_file():
+        try:
+            checksum = json.loads(manifest.read_text()).get("checksum", "")
+            return checksum[:8] if checksum else "RS226"
+        except json.JSONDecodeError:
+            return "RS226"
+    return "RS226"
+
+
+def identify_by_sourmash(contigs: str | Path, db_dir: str | Path | None = None) -> SourmashIdResult:
+    base = Path(db_dir) if db_dir else SPECIES_DB_DIR / "D4_sourmash"
+    partition = _gather_and_tax(contigs, base)
+    database = {"name": "D4_sourmash", "version": _db_version(base)}
+
+    best_fuw = max((p["f_unique_weighted"] for p in partition), default=0.0)
+    flags: list[str] = []
+    strong_members = [p for p in partition if p["f_unique_weighted"] >= _MIXTURE_MEMBER]
+    if len(strong_members) >= 2:
+        flags.append("possible_mixture")
+
+    if best_fuw >= _FUW_HIGH and not flags:
+        species, confidence = partition[0]["lineage"], "high"
+    elif best_fuw >= _FUW_MEDIUM:
+        species, confidence = partition[0]["lineage"], "medium"
+    else:
+        species, confidence = "Mixed/Unknown", "low"
+
+    result = {
+        "species": species or "Mixed/Unknown",
+        "confidence": confidence,
+        "f_unique_weighted": best_fuw,
+        "gather_partition": [
+            {"lineage": p["lineage"], "f_unique_weighted": p["f_unique_weighted"]}
+            for p in partition
+        ],
+        "flags": flags,
+    }
+    return SourmashIdResult(method="sourmash", database=database, result=result)

gside/analysis/species_canon.py

@@ -0,0 +1,53 @@
+"""物种判决规范化 —— 共享单一实现（评审 A5：消除同 PR 内 ≥4 份拷贝）。
+
+- ``canonical_from_verdict(verdict, ipah)``：管线 verdict → 规范物种名。
+  not_ 前缀按 ipaH 分流（Shigella/E. coli）；供 nli_reflector / validate
+  类消费者使用。
+- ``collapse_binomial(verdict)``：二名形/别名 → verify_species 期望的 token。
+  not_ 前缀原样保留（维持 Layer 2 报错信息可读）；供 deterministic_verifier
+  使用。
+- 规范名常量：各模块的文本提取表 / gold 前缀表的值必须引用这些常量，
+  新增病原只改本模块一处。
+"""
+
+from __future__ import annotations
+
+SALMONELLA = "Salmonella"
+ECOLI = "E. coli"
+SHIGELLA = "Shigella"
+VPARA = "V. parahaemolyticus"
+UNKNOWN = "unknown"
+
+# 子串 → 规范名（顺序敏感：物种专名先于属名缩写）
+_VERDICT_NEEDLES: tuple[tuple[str, str], ...] = (
+    ("Salmonella", SALMONELLA),
+    ("parahaemolyticus", VPARA),
+    ("Shigella", SHIGELLA),
+    ("E. coli", ECOLI),
+    ("E.coli", ECOLI),
+    ("DEC", ECOLI),
+)
+
+
+def canonical_from_verdict(verdict: str, ipah: str = "") -> str:
+    """verdict → 规范物种名；not_X 按 ipaH 分流（阳性→Shigella，否则 E. coli）。"""
+    v = verdict.strip()
+    if not v:
+        return UNKNOWN
+    if v.startswith("not_"):
+        return SHIGELLA if "positive" in ipah.lower() else ECOLI
+    for needle, canonical in _VERDICT_NEEDLES:
+        if needle in v:
+            return canonical
+    return UNKNOWN
+
+
+def collapse_binomial(verdict: str) -> str:
+    """二名形/别名 → verify_species 期望 token；not_ 前缀原样保留。"""
+    v = verdict.strip()
+    if v.startswith("not_"):
+        return v
+    for needle, canonical in _VERDICT_NEEDLES:
+        if needle in v:
+            return canonical
+    return v