gapit 0.2.2__py3-none-any.whl

gapit/screening_reads.py

@@ -0,0 +1,255 @@
+"""The minimap2 screening use-cases (SPEC.md §10): ``--r1``/``--r2`` reads and
+positional assemblies via ``--aligner minimap2``.
+
+Split from screening.py so each use-case module stays under the 250 pure-LOC
+ceiling; screening.py keeps the blastn contig pipeline and shared helpers.
+"""
+
+from datetime import UTC, datetime
+from pathlib import Path
+
+import typer
+
+from gapit import config
+from gapit.errors import ensure_input_file, usage_fail
+from gapit.formats.json import render_reads2_json, render_reads_json
+from gapit.formats.md import render_reads2_markdown, render_reads_markdown
+from gapit.reads import (
+    ReadFileKind,
+    ReadsParams,
+    ReadTypeEnum,
+    detect_read_kind,
+    screen_reads,
+)
+from gapit.screening import AlignerEnum, OutputFormat, find_database
+
+
+def _pair_read_lanes(r1: list[Path], r2: list[Path] | None) -> list[tuple[Path, Path | None]]:
+    """Pair per-lane --r1/--r2 file lists (r2 None = single-end)."""
+    if r2 is not None and len(r2) != len(r1):
+        usage_fail(f"--r2 has {len(r2)} files but --r1 has {len(r1)} (lanes must pair up)")
+    if r2 is None:
+        return [(path, None) for path in r1]
+    return list(zip(r1, r2, strict=True))
+
+
+def _resolve_read_preset(
+    lanes: list[tuple[Path, Path | None]], read_type: ReadTypeEnum | None, quiet: bool
+) -> ReadTypeEnum:
+    """Detect every input's kind from content and resolve the minimap2 preset:
+    assembly FASTA forces map-ont (one stderr note unless quiet/explicit),
+    FASTQ keeps sr unless a preset was given. Mixed kinds and FASTA paired-end
+    are usage errors."""
+    r1_kinds = {detect_read_kind(r1_path) for r1_path, _ in lanes}
+    if len(r1_kinds) > 1:
+        usage_fail("mixed FASTA and FASTQ inputs")
+    r2_kinds = {detect_read_kind(r2_path) for _, r2_path in lanes if r2_path is not None}
+    if r2_kinds and ReadFileKind.fasta in r1_kinds | r2_kinds:
+        usage_fail("paired-end requires FASTQ")
+    if ReadFileKind.fasta not in r1_kinds:
+        return read_type if read_type is not None else ReadTypeEnum.sr
+    if read_type is not None and read_type is not ReadTypeEnum.map_ont:
+        usage_fail("assembly FASTA requires map-ont")
+    if read_type is None and not quiet:
+        typer.echo("assembly FASTA detected; using map-ont", err=True)
+    return ReadTypeEnum.map_ont
+
+
+def _reject_blastn_thresholds(minid: float, mincov: float, mode: str) -> None:
+    """--minid/--mincov are blastn-only; every minimap2 entry point rejects
+    them instead of silently ignoring them (reads thresholds have their own
+    flags). ``mode`` names the invocation in the frozen message."""
+    if minid != 80.0 or mincov != 80.0:
+        usage_fail(
+            f"--minid/--mincov apply to blastn only; use --min-identity/--min-breadth with {mode}"
+        )
+
+
+def _validate_reads_usage(
+    output_format: OutputFormat | None,
+    min_breadth: float,
+    min_identity: float,
+    min_mapq: int,
+    threads: int,
+) -> None:
+    """Usage gates shared by both minimap2 entry points, in the frozen order
+    (format first, then thresholds), before any file is touched."""
+    if output_format is OutputFormat.tsv or output_format is OutputFormat.csv:
+        usage_fail("--format tsv|csv is not available in reads mode (use json or md)")
+    if not 0.0 <= min_breadth <= 100.0:
+        usage_fail(f"--min-breadth must be in [0, 100]: got {min_breadth}")
+    if not 0.0 <= min_identity <= 100.0:
+        usage_fail(f"--min-identity must be in [0, 100]: got {min_identity}")
+    if min_mapq < 0:
+        usage_fail(f"--min-mapq must be >= 0: got {min_mapq}")
+    if threads < 1:
+        usage_fail(f"--threads must be >= 1: got {threads}")
+
+
+def _screen_lanes(
+    lanes: list[tuple[Path, Path | None]],
+    db_name: str,
+    datadir: Path | None,
+    read_type: ReadTypeEnum | None,
+    min_breadth: float,
+    min_identity: float,
+    min_mapq: int,
+    threads: int,
+    output_format: OutputFormat | None,
+    quiet: bool,
+    debug: bool,
+) -> str:
+    """Minimap2 engine core shared by both entry points: preset resolution,
+    screening, rendering; json is the default format (SPEC.md §10). Either
+    reads/2 threshold on selects the gapit.reads/2 document; both off keep
+    gapit.reads/1 byte-identical. Returns the rendered output for the caller
+    to echo."""
+    resolved = _resolve_read_preset(lanes, read_type, quiet)
+    database = find_database(config.resolve_datadir(datadir), db_name)
+    read_files = [r1_path for r1_path, _ in lanes] + [
+        r2_path for _, r2_path in lanes if r2_path is not None
+    ]
+    read_list = ", ".join(str(path) for path in read_files)
+    if not quiet:
+        typer.echo(f"Screening reads: {read_list}", err=True)
+    report = screen_reads(
+        lanes,
+        database,
+        read_type=resolved.value,
+        min_breadth=min_breadth,
+        threads=threads,
+        debug=debug,
+        min_identity=min_identity,
+        min_mapq=min_mapq,
+    )
+    present = sum(1 for gene in report.genes if gene.present)
+    if not quiet:
+        typer.echo(f"Detected {present} present genes in {read_list}", err=True)
+    params = ReadsParams(
+        db=db_name,
+        read_type=resolved.value,
+        min_breadth=min_breadth,
+        threads=threads,
+        min_identity=min_identity,
+        min_mapq=min_mapq,
+    )
+    now = datetime.now(UTC)
+    reads2 = min_identity > 0.0 or min_mapq > 0
+    if reads2:
+        output = (
+            render_reads2_markdown([report], params, now=now)
+            if output_format is OutputFormat.md
+            else render_reads2_json([report], params, now=now)
+        )
+    else:
+        output = (
+            render_reads_markdown([report], params, now=now)
+            if output_format is OutputFormat.md
+            else render_reads_json([report], params, now=now)
+        )
+    return output
+
+
+def run_screen_reads(
+    r1: list[Path],
+    r2: list[Path] | None,
+    db_name: str,
+    datadir: Path | None,
+    read_type: ReadTypeEnum | None,
+    min_breadth: float,
+    min_identity: float,
+    min_mapq: int,
+    threads: int,
+    output_format: OutputFormat | None,
+    quiet: bool,
+    debug: bool = False,
+    aligner: AlignerEnum | None = None,
+    minid: float = 80.0,
+    mincov: float = 80.0,
+) -> str:
+    """Screen FASTQ reads or assembly FASTA given as already-split per-lane
+    --r1/--r2 file lists (the CLI owns the comma-splitting; MCP passes arrays
+    natively, so commas in filenames survive). Per-lane minimap2, sample-level
+    union; json is the default format (SPEC.md §10). A nonzero
+    --min-identity/--min-mapq turns on gapit.reads/2 alignment filtering.
+    Returns the rendered output."""
+    if aligner is AlignerEnum.blastn:
+        usage_fail("--aligner blastn is not available for --r1/--r2 reads input")
+    _validate_reads_usage(output_format, min_breadth, min_identity, min_mapq, threads)
+    _reject_blastn_thresholds(minid, mincov, "--r1/--r2")
+    lanes = _pair_read_lanes(r1, r2)
+    for path in [r1_path for r1_path, _ in lanes] + [
+        r2_path for _, r2_path in lanes if r2_path is not None
+    ]:
+        ensure_input_file(path, "reads file")
+    return _screen_lanes(
+        lanes,
+        db_name,
+        datadir,
+        read_type,
+        min_breadth,
+        min_identity,
+        min_mapq,
+        threads,
+        output_format,
+        quiet,
+        debug,
+    )
+
+
+def run_screen_assemblies(
+    files: list[Path] | None,
+    fofn: Path | None,
+    db_name: str,
+    datadir: Path | None,
+    read_type: ReadTypeEnum | None,
+    min_breadth: float,
+    min_identity: float,
+    min_mapq: int,
+    threads: int,
+    jobs: int,
+    noheader: bool,
+    nopath: bool,
+    output_format: OutputFormat | None,
+    quiet: bool,
+    debug: bool = False,
+    minid: float = 80.0,
+    mincov: float = 80.0,
+) -> str:
+    """Screen positional assembly FASTA file(s) with the minimap2 engine
+    (--aligner minimap2): every input must be FASTA(.gz) content — FASTQ
+    content is a usage error, undetectable content keeps the typed input
+    error. Preset resolution and output follow the reads contract (SPEC §10);
+    the blastn-engine-only flags --fofn/--jobs/--noheader/--nopath and the
+    blastn thresholds --minid/--mincov are rejected here instead of silently
+    ignored. A nonzero --min-identity/--min-mapq turns on gapit.reads/2
+    filtering. Returns the rendered output."""
+    _validate_reads_usage(output_format, min_breadth, min_identity, min_mapq, threads)
+    if fofn is not None:
+        usage_fail("--fofn is not available with --aligner minimap2")
+    if jobs != 1:
+        usage_fail("--jobs is not available with --aligner minimap2")
+    if noheader:
+        usage_fail("--noheader is not available with --aligner minimap2")
+    if nopath:
+        usage_fail("--nopath is not available with --aligner minimap2")
+    _reject_blastn_thresholds(minid, mincov, "--aligner minimap2")
+    if not files:
+        usage_fail("no input files given (positional FILEs)")
+    for path in files:
+        ensure_input_file(path)
+        if detect_read_kind(path) is not ReadFileKind.fasta:
+            usage_fail("minimap2 engine requires FASTA assemblies")
+    return _screen_lanes(
+        [(path, None) for path in files],
+        db_name,
+        datadir,
+        read_type,
+        min_breadth,
+        min_identity,
+        min_mapq,
+        threads,
+        output_format,
+        quiet,
+        debug,
+    )

gapit/seqconvert.py

@@ -0,0 +1,203 @@
+"""Native input normalization: FASTA/FASTQ/GenBank/EMBL (.gz/.bz2) → FASTA lines.
+
+Replaces the external ``any2fasta -q -u <file>`` stage of the screening
+pipeline (blast.py). Semantics extracted from any2fasta 0.8.1 (Perl,
+bioconda; ``.pixi/envs/default/bin/any2fasta``) invoked with ``-q -u`` only —
+no ``-n`` (N-purification), ``-l``, ``-g`` (VERSION), or ``-s`` (description
+stripping). Perl line references below are that file.
+
+- Detection (L89-99, L136-153): first line of the decompressed stream, in
+  order GENBANK ``^LOCUS\\h``, EMBL ``^ID\\h``, FASTA ``^>\\S``, FASTQ
+  ``^@\\S`` (``\\h`` = space/tab; ``\\S`` = non-whitespace after the marker).
+  Empty input dies with "The input appears to be empty" (L131-133); an
+  unrecognized first line dies with "Unfamilar format with first line: ..."
+  (L153 — typo theirs, kept for message parity with the retired binary).
+- purify_dna (L164-170): with ``-u`` only uc() — sequences uppercased, nothing
+  else touched. purify_id (L174-181) is a no-op without ``-s``: headers pass
+  through verbatim.
+- FASTA (L185-200): header lines printed verbatim; sequence lines uppercased;
+  blank/whitespace-only lines skipped entirely (L189).
+- FASTQ (L204-215): strict 4-line stride. Header = the ``@`` line minus its
+  leading ``@``, verbatim (id + description); sequence = uc() of line 2;
+  ``+``/quality lines dropped. A trailing lone ``@`` header emits nothing
+  (loop guard ``$i < $#lines``, L208).
+- GenBank (L255-296): id = first token after ``LOCUS\\s+`` (L285-287).
+  DEFINITION is never read — records carry no description. VERSION overrides
+  the id only under ``-g`` (L290-292; unused). ORIGIN data lines: drop the
+  first 10 columns (coordinate prefix, L279), then strip whitespace (L280) —
+  digits past column 10 are kept. Records flush at ``//`` (L264-269); a
+  record never terminated by ``//`` is dropped.
+- EMBL (L300-339): id = text after ``ID\\s+`` up to the first ``;`` (L330-331,
+  not trimmed). DE is never read. SQ data lines: strip all whitespace AND
+  digits (L325). Flush at ``//``.
+
+Deliberate divergences, invisible to BLAST: sequence is re-wrapped at 60
+columns (the Perl reuses input wrapping) and input is read with universal
+newlines (the Perl preserves ``\\r``). Parsed records — id, description,
+uppercased sequence — are identical, so the blastn query is unchanged and
+abricate parity is unaffected. gapit owns no any2fasta dependency; the
+differential suite runs the real binary from the parity env's PATH, where
+abricate provides it transitively (tests/test_seqconvert_differential.py).
+"""
+
+import re
+from collections.abc import Iterator
+from enum import Enum
+from pathlib import Path
+from typing import IO
+
+from gapit.errors import InputError
+from gapit.fasta import open_text
+
+_WRAP = 60
+
+
+class SeqFormat(Enum):
+    """Input formats detected from the first decompressed line."""
+
+    fasta = "fasta"
+    fastq = "fastq"
+    genbank = "genbank"
+    embl = "embl"
+
+
+def _tagged(line: str, tag: str) -> bool:
+    """``^tag\\h`` — tag at column 1 followed by one space or tab."""
+    return line.startswith(tag) and line[len(tag) : len(tag) + 1] in (" ", "\t")
+
+
+def detect_format(path: Path) -> SeqFormat:
+    """Content-sniff the first decompressed line (reads.py detect_read_kind style)."""
+    try:
+        with open_text(path) as handle:
+            first = handle.readline()
+    except (OSError, UnicodeDecodeError, EOFError) as exc:
+        raise InputError(
+            f"could not read input: {exc}",
+            code="INVALID_INPUT",
+            context={"file": str(path)},
+        ) from exc
+    if not first:
+        raise InputError(
+            "The input appears to be empty",
+            code="INVALID_INPUT",
+            context={"file": str(path)},
+        )
+    line = first.rstrip("\r\n")
+    if _tagged(line, "LOCUS"):
+        return SeqFormat.genbank
+    if _tagged(line, "ID"):
+        return SeqFormat.embl
+    if len(line) > 1 and line[0] == ">" and not line[1].isspace():
+        return SeqFormat.fasta
+    if len(line) > 1 and line[0] == "@" and not line[1].isspace():
+        return SeqFormat.fastq
+    raise InputError(
+        f"Unfamilar format with first line: {line}",
+        code="INVALID_INPUT",
+        context={"file": str(path)},
+    )
+
+
+def _iter_fasta(handle: IO[str]) -> Iterator[tuple[str, str]]:
+    """(header, sequence) pairs; headers verbatim, blank lines skipped."""
+    header: str | None = None
+    chunks: list[str] = []
+    for raw in handle:
+        line = raw.rstrip("\n")
+        if not line.strip():
+            continue
+        if line.startswith(">"):
+            if header is not None:
+                yield (header, "".join(chunks).upper())
+            header, chunks = line[1:], []
+        else:
+            chunks.append(line)
+    if header is not None:
+        yield (header, "".join(chunks).upper())
+
+
+def _iter_fastq(handle: IO[str]) -> Iterator[tuple[str, str]]:
+    """Stride-4 records; a trailing lone '@' header emits nothing (perl guard)."""
+    lines = iter(handle)
+    for header_line in lines:
+        sequence_line = next(lines, None)
+        if sequence_line is None:
+            return
+        yield (header_line.rstrip("\n")[1:], sequence_line.rstrip("\n").upper())
+        next(lines, None)  # '+' separator
+        next(lines, None)  # quality line
+
+
+def _iter_genbank(handle: IO[str]) -> Iterator[tuple[str, str]]:
+    """LOCUS-name ids without description; ORIGIN columns 11+ minus whitespace."""
+    acc = ""
+    chunks: list[str] = []
+    in_seq = False
+    for raw in handle:
+        line = raw.rstrip("\n")
+        if line.startswith("//"):
+            yield (acc, "".join(chunks).upper())
+            acc, chunks, in_seq = "", [], False
+        elif line.startswith("ORIGIN"):
+            in_seq = True
+        elif in_seq:
+            chunks.append(re.sub(r"\s+", "", line[10:]))
+        elif (match := re.match(r"LOCUS\s+(\S+)", line)) is not None:
+            acc = match.group(1)
+
+
+def _iter_embl(handle: IO[str]) -> Iterator[tuple[str, str]]:
+    """ID-before-';' ids without description; SQ lines minus whitespace+digits."""
+    acc = ""
+    chunks: list[str] = []
+    in_seq = False
+    for raw in handle:
+        line = raw.rstrip("\n")
+        if line.startswith("//"):
+            yield (acc, "".join(chunks).upper())
+            acc, chunks, in_seq = "", [], False
+        elif re.match(r"SQ\s", line) is not None:
+            in_seq = True
+        elif in_seq:
+            chunks.append(re.sub(r"[\s\d]", "", line))
+        elif (match := re.match(r"ID\s+([^;]+)", line)) is not None:
+            acc = match.group(1)
+
+
+def _records(fmt: SeqFormat, handle: IO[str]) -> Iterator[tuple[str, str]]:
+    records: Iterator[tuple[str, str]]
+    match fmt:
+        case SeqFormat.fasta:
+            records = _iter_fasta(handle)
+        case SeqFormat.fastq:
+            records = _iter_fastq(handle)
+        case SeqFormat.genbank:
+            records = _iter_genbank(handle)
+        case SeqFormat.embl:
+            records = _iter_embl(handle)
+    return records
+
+
+def to_fasta_lines(path: Path, fmt: SeqFormat | None = None) -> Iterator[str]:
+    """Yield complete FASTA lines for one input file: one verbatim header line
+    per record, then its uppercased sequence wrapped at 60 columns.
+
+    ``fmt`` may be pre-supplied to reuse a sniff (blast.run_blastn's debug
+    echo shares one detection). Raises InputError (INVALID_INPUT) on unreadable,
+    empty, or unrecognized input — the retired any2fasta's fatal path.
+    """
+    if fmt is None:
+        fmt = detect_format(path)
+    try:
+        with open_text(path) as handle:
+            for header, sequence in _records(fmt, handle):
+                yield f">{header}\n"
+                for offset in range(0, len(sequence), _WRAP):
+                    yield f"{sequence[offset : offset + _WRAP]}\n"
+    except (OSError, UnicodeDecodeError, EOFError) as exc:
+        raise InputError(
+            f"could not read input: {exc}",
+            code="INVALID_INPUT",
+            context={"file": str(path)},
+        ) from exc

gapit/summary.py

@@ -0,0 +1,151 @@
+"""Summary mode core: parse abricate-format report tables into a gene matrix.
+
+Mirrors abricate 1.4.0 ``summary_table`` (SPEC.md §6) exactly where it is
+defined, and replaces its silent-undef edges with typed InputErrors
+(``SUMMARY_MALFORMED``) — a documented [gapit-extension] divergence.
+"""
+
+from collections.abc import Callable
+from pathlib import Path, PurePath
+from typing import Literal
+
+from pydantic import BaseModel
+
+from gapit.errors import InputError
+
+FIELDSEP = ";"
+ABSENT = "."
+
+Warn = Callable[[str], None]
+
+
+class SummaryParams(BaseModel, frozen=True):
+    """Summary parameters in effect (metric + path display)."""
+
+    identity: bool = False
+    nopath: bool = False
+
+    @property
+    def metric(self) -> Literal["%COVERAGE", "%IDENTITY"]:
+        """The report column summarized into cells."""
+        return "%IDENTITY" if self.identity else "%COVERAGE"
+
+
+class SummaryRow(BaseModel, frozen=True):
+    """One matrix row: a display label, its distinct-gene count, and the
+    per-gene cell values as the original report strings in row order."""
+
+    file: str
+    num_found: int
+    cells: dict[str, tuple[str, ...]]
+
+
+class SummaryMatrix(BaseModel, frozen=True):
+    """Canonical in-memory summary result: sorted gene universe + ordered rows."""
+
+    params: SummaryParams
+    genes: tuple[str, ...]
+    rows: tuple[SummaryRow, ...]
+
+
+def _read_report(path: Path) -> str:
+    """Read one report table; missing/unreadable/non-UTF-8 is an InputError."""
+    if not path.is_file():
+        raise InputError(
+            f"report file not found or unreadable: {path}",
+            code="INPUT_NOT_FOUND",
+            context={"file": str(path)},
+        )
+    try:
+        return path.read_text(encoding="utf-8")
+    except UnicodeDecodeError as exc:
+        raise InputError(
+            f"report is not valid UTF-8: {path}",
+            code="SUMMARY_MALFORMED",
+            context={"file": str(path)},
+        ) from exc
+
+
+def _lines(text: str) -> list[str]:
+    """Split like Perl's ``while (<$fh>)``: on \\n, no phantom final line."""
+    if not text:
+        return []
+    parts = text.split("\n")
+    if parts[-1] == "":
+        parts.pop()
+    return parts
+
+
+def _detect_separator(text: str) -> str:
+    """[gapit-extension] auto-detect the table separator per file: tab if the
+    first line has any, else comma, else tab (single-column degenerate)."""
+    first = _lines(text)[0] if text else ""
+    if "\t" in first:
+        return "\t"
+    if "," in first:
+        return ","
+    return "\t"
+
+
+def _malformed(path: Path, line_number: int, detail: str) -> InputError:
+    return InputError(
+        f"malformed report row: {detail} ({path}:{line_number})",
+        code="SUMMARY_MALFORMED",
+        context={"file": str(path), "line": str(line_number)},
+    )
+
+
+def build_summary(paths: list[Path], params: SummaryParams, *, warn: Warn) -> SummaryMatrix:
+    """Aggregate report table(s) into the summary matrix.
+
+    Dutch mode (exactly one input) keys rows by each table row's FILE column;
+    otherwise rows are keyed by input filename as given. Rows are sorted by
+    that key — not by display label — matching upstream. The first row seen
+    anywhere is the column map (upstream ``@hdr``); later '#' rows are skipped.
+    """
+    dutch = len(paths) == 1
+    data: dict[str, dict[str, list[str]]] = {}
+    seen: set[str] = set()
+    indexes: dict[str, int] | None = None
+    for path in paths:
+        key = str(path)
+        if key in seen:
+            warn(f"Skipping duplicate file: {key}")
+            continue
+        seen.add(key)
+        text = _read_report(path)
+        if not dutch:
+            data[key] = {}
+        separator = _detect_separator(text)
+        for line_number, line in enumerate(_lines(text), start=1):
+            columns = line.split(separator)
+            if indexes is None:
+                # Header-name -> column index with Perl zip semantics (later dups win).
+                indexes = dict(zip(columns, range(len(columns)), strict=True))
+            if columns[0].startswith("#"):
+                continue
+            assert indexes is not None  # set on the first line, before any data row
+            gene_at = indexes.get("GENE")
+            metric_at = indexes.get(params.metric)
+            if gene_at is None:
+                raise _malformed(path, line_number, "header has no GENE column")
+            if metric_at is None:
+                raise _malformed(path, line_number, f"header has no {params.metric} column")
+            if len(columns) <= max(gene_at, metric_at):
+                raise _malformed(
+                    path, line_number, f"expected >= {max(gene_at, metric_at) + 1} columns"
+                )
+            gene, value = columns[gene_at], columns[metric_at]
+            file_key = PurePath(columns[0]).name if params.nopath else columns[0]
+            row_key = file_key if dutch else key
+            data.setdefault(row_key, {}).setdefault(gene, []).append(value)
+    genes = tuple(sorted({gene for hits in data.values() for gene in hits}))
+    rows = tuple(
+        SummaryRow(
+            file=PurePath(row_key).name if params.nopath else row_key,
+            num_found=len(data[row_key]),
+            cells={gene: tuple(data[row_key][gene]) for gene in genes if gene in data[row_key]},
+        )
+        for row_key in sorted(data)
+    )
+    return SummaryMatrix(params=params, genes=genes, rows=rows)