nonhuman-screen 0.1.0__py3-none-any.whl

nonhuman_screen/__init__.py

@@ -0,0 +1,63 @@
+"""nonhuman-screen: classify sequencing reads by non-human taxonomic content.
+
+Wraps kraken2's LCA classification and reduces per-read verdicts to a
+non-human fraction (NHF) plus per-domain breakdowns, with a human-homology
+guard and UniVec-Core exclusion.  Sample-agnostic: it classifies whatever
+named reads you hand it, so it works equally on a proband, a parent, a tumour,
+or a plain FASTQ.
+
+Two levels of API:
+
+* Engine (stdlib only) — ``Kraken2Runner.classify_sequences({name: seq})``.
+* BAM/allele helpers (needs the ``[bam]`` extra) — ``classify_variant_alt_reads``
+  and ``classify_variants_alt_reads`` compute the non-human fraction of the
+  reads supporting a variant's ALT allele.
+"""
+
+from nonhuman_screen.engine import (
+    ClassificationResult,
+    Kraken2Runner,
+    _ARCHAEA_TAXID,
+    _BACTERIA_TAXID,
+    _EUKARYOTA_TAXID,
+    _FUNGI_TAXID,
+    _HUMAN_TAXID,
+    _METAZOA_TAXID,
+    _UNIVEC_CORE_TAXID,
+    _VIRIDIPLANTAE_TAXID,
+    _VIRUSES_TAXID,
+)
+from nonhuman_screen.alleles import read_supports_alt
+from nonhuman_screen.result import TaxonomicFractions, VariantNHF
+from nonhuman_screen.votes import parse_kmer_votes
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Kraken2Runner",
+    "ClassificationResult",
+    "TaxonomicFractions",
+    "VariantNHF",
+    "read_supports_alt",
+    "parse_kmer_votes",
+    "__version__",
+]
+
+# BAM/allele helpers require pysam ([bam] extra). Expose them at the top level
+# when available, but never make importing the core engine depend on pysam.
+try:
+    from nonhuman_screen.bam import (  # noqa: F401
+        classify_reads_from_bam,
+        classify_variant_alt_reads,
+        classify_variants_alt_reads,
+        reads_supporting_alt,
+    )
+
+    __all__ += [
+        "classify_reads_from_bam",
+        "classify_variant_alt_reads",
+        "classify_variants_alt_reads",
+        "reads_supporting_alt",
+    ]
+except ImportError:
+    pass

nonhuman_screen/alleles.py

@@ -0,0 +1,85 @@
+"""Allele-support determination for reads at a variant locus.
+
+Pure-Python helpers that decide whether an aligned read carries a given
+alternate allele.  They operate on a pysam ``AlignedSegment`` passed in by
+the caller but do **not** import pysam themselves, so this module has no
+third-party dependency.
+"""
+
+
+def _is_symbolic(allele):
+    """Return True if *allele* is a symbolic VCF allele with no literal sequence.
+
+    Symbolic alleles include ``<DEL>``, ``<INS>``, ``<DUP>``, breakend
+    notation containing ``[`` or ``]``, and the overlapping-deletion
+    marker ``*``.
+    """
+    if not allele:
+        return True
+    return allele[0] == "<" or allele == "*" or "[" in allele or "]" in allele
+
+
+def read_supports_alt(
+    read, variant_pos, ref, alt, min_baseq=0, *,
+    aligned_pairs=None, seq=None, quals=None,
+):
+    """Return True if *read* carries the alternate allele at *variant_pos*.
+
+    Extracts the exact read sequence aligned to the reference span of the
+    variant and compares it strictly to the candidate alternate allele.
+    Handles SNPs, MNPs, insertions, deletions, and complex indels natively.
+
+    Returns ``False`` for symbolic alleles or when *alt* is ``None``.
+
+    Args:
+        min_baseq: Minimum base quality threshold for bases considered as
+            alt support.
+        aligned_pairs: Optional pre-computed result of
+            ``read.get_aligned_pairs(matches_only=False)``.  Computed from
+            *read* when not provided.
+        seq: Optional pre-decoded ``read.query_sequence``.  Decoded from
+            *read* when not provided.
+        quals: Optional pre-decoded ``read.query_qualities``. Decoded from
+            *read* only when ``min_baseq > 0`` and not provided.
+    """
+    if alt is None or _is_symbolic(alt):
+        return False
+
+    if seq is None:
+        seq = read.query_sequence
+    if seq is None:
+        return False
+    if min_baseq > 0 and quals is None:
+        quals = read.query_qualities
+
+    if aligned_pairs is None:
+        aligned_pairs = read.get_aligned_pairs(matches_only=False)
+
+    extracted_seq = []
+    in_variant_region = False
+
+    for qpos, rpos in aligned_pairs:
+        # Stop collecting once we reach or pass the end of the reference allele span
+        if rpos is not None and rpos >= variant_pos + len(ref):
+            break
+
+        # Start collecting when we hit the exact start of the variant
+        if rpos == variant_pos:
+            in_variant_region = True
+
+        if in_variant_region:
+            # qpos is None for deleted bases (skip), otherwise append the read base
+            if qpos is not None:
+                if (
+                    min_baseq > 0 and quals is not None
+                    and quals[qpos] < min_baseq
+                ):
+                    return False
+                extracted_seq.append(seq[qpos])
+
+    # If the variant region was skipped entirely due to read boundaries
+    if not in_variant_region:
+        return False
+
+    return "".join(extracted_seq).upper() == alt.upper()
+

nonhuman_screen/bam.py

@@ -0,0 +1,216 @@
+"""BAM-aware entry points: classify reads, and classify per-variant allele support.
+
+This module is the convenient, high-level surface most callers want.  It pulls
+read sequences out of a BAM/CRAM and hands them to the pysam-free
+:class:`~nonhuman_screen.engine.Kraken2Runner`, so no consumer has to
+re-implement the "which reads support this allele, and how non-human are they"
+machinery.
+
+Requires the ``[bam]`` extra (pysam).  Import errors here are deliberately
+actionable.
+
+Coordinate convention: every ``pos`` is **0-based** (pysam reference
+coordinates), and variant keys are ``"{chrom}:{pos}:{ref}:{alt}"`` to match the
+internal conventions of consuming pipelines.
+"""
+
+from __future__ import annotations
+
+try:
+    import pysam
+except ImportError as exc:  # pragma: no cover - import-guard
+    raise ImportError(
+        "nonhuman_screen.bam requires pysam. Install with: "
+        "pip install 'nonhuman-screen[bam]'"
+    ) from exc
+
+from nonhuman_screen.alleles import read_supports_alt
+from nonhuman_screen.engine import Kraken2Runner
+from nonhuman_screen.result import TaxonomicFractions, VariantNHF
+
+
+def _as_variant(v):
+    """Normalize a variant into a ``(chrom, pos, ref, alt)`` tuple (pos 0-based)."""
+    if isinstance(v, (tuple, list)):
+        chrom, pos, ref, alt = v
+        return (chrom, int(pos), ref, alt)
+    if isinstance(v, dict):
+        return (v["chrom"], int(v["pos"]), v["ref"], v["alt"])
+    return (v.chrom, int(v.pos), v.ref, v.alt)
+
+
+def _open(bam_path, ref_fasta):
+    return pysam.AlignmentFile(
+        bam_path, reference_filename=ref_fasta if ref_fasta else None
+    )
+
+
+def _alt_support_seqs(bam, chrom, pos, ref, alt, *, min_baseq=0):
+    """Return ``{read_name: sequence}`` for reads supporting *alt* at 0-based *pos*.
+
+    Fragments are de-duplicated by read name (first supporting mate wins), so a
+    paired-end fragment contributes at most one sequence — consistent with how
+    fragment-level fractions are computed downstream.
+    """
+    out = {}
+    span = pos + max(len(ref) if ref else 1, 1)
+    for read in bam.fetch(chrom, pos, span):
+        name = read.query_name
+        if name in out:
+            continue
+        seq = read.query_sequence
+        if not seq:
+            continue
+        if read_supports_alt(read, pos, ref, alt, min_baseq):
+            out[name] = seq
+    return out
+
+
+def reads_supporting_alt(
+    bam_path, chrom, pos, ref, alt, *, ref_fasta=None, min_baseq=0
+):
+    """Return the set of read names supporting *alt* at 0-based *pos*.
+
+    A thin, classification-free helper for callers that only need the
+    allele-support read set (e.g. to feed their own logic).
+    """
+    with _open(bam_path, ref_fasta) as bam:
+        return set(_alt_support_seqs(bam, chrom, pos, ref, alt, min_baseq=min_baseq))
+
+
+def classify_reads_from_bam(
+    bam_path,
+    db_path,
+    *,
+    read_names=None,
+    loci=None,
+    ref_fasta=None,
+    confidence=0.0,
+    threads=1,
+    memory_mapping=False,
+    tmpdir=None,
+):
+    """Classify a set of reads from a BAM/CRAM and return a ``ClassificationResult``.
+
+    Args:
+        read_names: Set of read names to classify.  When *loci* is not given,
+            the whole file is scanned for these names.
+        loci: Optional ``{(chrom, pos): {read_name, ...}}`` mapping (0-based
+            ``pos``) to restrict fetching to specific loci — far cheaper than a
+            whole-file scan.  When both are given, *read_names* acts as an
+            additional filter on the fetched reads.
+    """
+    if not read_names and not loci:
+        return Kraken2Runner.Result()
+
+    sequences = {}
+    with _open(bam_path, ref_fasta) as bam:
+        if loci:
+            name_filter = set(read_names) if read_names else None
+            for (chrom, pos), names in sorted(loci.items()):
+                targets = set(names)
+                if name_filter is not None:
+                    targets &= name_filter
+                if not targets:
+                    continue
+                for read in bam.fetch(chrom, pos, pos + 1):
+                    n = read.query_name
+                    if n in targets and read.query_sequence and n not in sequences:
+                        sequences[n] = read.query_sequence
+        else:
+            wanted = set(read_names)
+            for read in bam.fetch(until_eof=True):
+                n = read.query_name
+                if n in wanted and read.query_sequence and n not in sequences:
+                    sequences[n] = read.query_sequence
+
+    if not sequences:
+        return Kraken2Runner.Result()
+
+    runner = Kraken2Runner(
+        db_path, confidence=confidence, threads=threads,
+        memory_mapping=memory_mapping,
+    )
+    return runner.classify_sequences(sequences, tmpdir=tmpdir)
+
+
+def classify_variants_alt_reads(
+    bam_path,
+    db_path,
+    variants,
+    *,
+    ref_fasta=None,
+    min_baseq=0,
+    confidence=0.0,
+    threads=1,
+    memory_mapping=False,
+    tmpdir=None,
+):
+    """Compute the allele-based non-human fraction for many variants at once.
+
+    For each variant, the reads supporting its ALT allele are gathered; the
+    union of those reads is classified with **a single kraken2 invocation**
+    (kraken2's database load dominates runtime, so batching matters), then the
+    result is split back per variant by read-name intersection.
+
+    Args:
+        variants: Iterable of variants, each a ``(chrom, pos, ref, alt)`` tuple
+            (0-based ``pos``), a mapping with those keys, or any object with
+            ``chrom``/``pos``/``ref``/``alt`` attributes.
+
+    Returns:
+        A list of :class:`~nonhuman_screen.result.VariantNHF`, in input order.
+    """
+    normalized = [_as_variant(v) for v in variants]
+
+    sequences = {}
+    per_variant_names = []
+    with _open(bam_path, ref_fasta) as bam:
+        for chrom, pos, ref, alt in normalized:
+            vs = _alt_support_seqs(bam, chrom, pos, ref, alt, min_baseq=min_baseq)
+            per_variant_names.append(set(vs))
+            for name, seq in vs.items():
+                sequences.setdefault(name, seq)
+
+    runner = Kraken2Runner(
+        db_path, confidence=confidence, threads=threads,
+        memory_mapping=memory_mapping,
+    )
+    result = runner.classify_sequences(sequences, tmpdir=tmpdir) if sequences \
+        else Kraken2Runner.Result()
+
+    out = []
+    for (chrom, pos, ref, alt), names in zip(normalized, per_variant_names):
+        out.append(
+            VariantNHF(
+                chrom=chrom, pos=pos, ref=ref, alt=alt,
+                supporting_read_names=frozenset(names),
+                fractions=TaxonomicFractions.over_reads(result, names),
+            )
+        )
+    return out
+
+
+def classify_variant_alt_reads(
+    bam_path, db_path, chrom, pos, ref, alt, *,
+    ref_fasta=None, min_baseq=0, confidence=0.0, threads=1,
+    memory_mapping=False, tmpdir=None,
+):
+    """Allele-based non-human fraction for a single variant.
+
+    Convenience wrapper over :func:`classify_variants_alt_reads`.
+
+    Example::
+
+        vnhf = classify_variant_alt_reads(
+            "sample.bam", "kraken2_db", "chr1", 12345, "A", "T",
+            ref_fasta="ref.fa",
+        )
+        vnhf.nonhuman_fraction   # 0.0-1.0 over ALT-supporting reads
+        vnhf.fractions.bacterial # per-domain breakdown
+    """
+    return classify_variants_alt_reads(
+        bam_path, db_path, [(chrom, pos, ref, alt)],
+        ref_fasta=ref_fasta, min_baseq=min_baseq, confidence=confidence,
+        threads=threads, memory_mapping=memory_mapping, tmpdir=tmpdir,
+    )[0]

nonhuman_screen/cli.py

@@ -0,0 +1,187 @@
+"""Command-line interface: ``nonhuman-screen``.
+
+Subcommands
+-----------
+``classify`` — screen reads from a BAM/CRAM for non-human content.  With
+``--variants`` it computes the allele-based non-human fraction for every ALT
+allele (the reads supporting each ALT are classified); otherwise it classifies
+all mapped reads and reports a single batch summary.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import shutil
+import sys
+
+from nonhuman_screen import __version__
+from nonhuman_screen.alleles import _is_symbolic
+
+
+def _build_parser():
+    parser = argparse.ArgumentParser(
+        prog="nonhuman-screen",
+        description="Classify sequencing reads by non-human taxonomic content.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    c = sub.add_parser(
+        "classify",
+        help="Screen reads from a BAM/CRAM for non-human content.",
+    )
+    c.add_argument("--bam", required=True, help="Input BAM/CRAM.")
+    c.add_argument(
+        "--kraken2-db", required=True,
+        help="Path to a kraken2 database directory.",
+    )
+    c.add_argument(
+        "--ref-fasta", default=None,
+        help="Reference FASTA (required for CRAM).",
+    )
+    c.add_argument(
+        "--variants", default=None,
+        help="VCF/BCF of variants. When given, compute the allele-based "
+             "non-human fraction for every ALT allele instead of a whole-BAM "
+             "summary.",
+    )
+    c.add_argument(
+        "--min-baseq", type=int, default=0,
+        help="Minimum base quality for a read to count as ALT support "
+             "(default: 0).",
+    )
+    c.add_argument(
+        "--out-prefix", default=None,
+        help="Write outputs to <prefix>.variant_nhf.tsv / <prefix>.summary.json. "
+             "When omitted, results are printed to stdout.",
+    )
+    c.add_argument("--threads", type=int, default=1, help="kraken2 threads.")
+    c.add_argument(
+        "--confidence", type=float, default=0.0,
+        help="kraken2 confidence threshold 0.0-1.0 (default: 0.0).",
+    )
+    c.add_argument(
+        "--memory-mapping", action="store_true", default=False,
+        help="Pass --memory-mapping to kraken2 to reduce RAM.",
+    )
+    return parser
+
+
+def _read_vcf_variants(path):
+    """Yield ``(chrom, pos0, ref, alt)`` for every concrete ALT allele."""
+    import pysam
+
+    with pysam.VariantFile(path) as vcf:
+        for rec in vcf:
+            if rec.alts is None:
+                continue
+            for alt in rec.alts:
+                # Skip symbolic (<DEL>), breakend (N[chr2:321[), and the
+                # spanning-deletion (*) alleles — none has a literal sequence to
+                # match reads against.
+                if _is_symbolic(alt):
+                    continue
+                yield (rec.chrom, rec.start, rec.ref, alt)
+
+
+_TSV_COLUMNS = (
+    "variant_key", "supporting_reads", "nonhuman_fraction",
+    "bacterial", "archaeal", "fungal", "protist", "viral", "univec_core",
+    "human_lineage", "unclassified",
+)
+
+
+def _classify_variants(args):
+    from nonhuman_screen.bam import classify_variants_alt_reads
+
+    variants = list(_read_vcf_variants(args.variants))
+    logging.info("Classifying ALT-supporting reads for %d alleles", len(variants))
+    results = classify_variants_alt_reads(
+        args.bam, args.kraken2_db, variants,
+        ref_fasta=args.ref_fasta, min_baseq=args.min_baseq,
+        confidence=args.confidence, threads=args.threads,
+        memory_mapping=args.memory_mapping,
+    )
+
+    lines = ["\t".join(_TSV_COLUMNS)]
+    for v in results:
+        f = v.fractions
+        lines.append("\t".join(str(x) for x in (
+            v.variant_key, v.supporting_reads, v.nonhuman_fraction,
+            f.bacterial, f.archaeal, f.fungal, f.protist, f.viral,
+            f.univec_core, f.human_lineage, f.unclassified,
+        )))
+    tsv = "\n".join(lines) + "\n"
+
+    if args.out_prefix:
+        tsv_path = f"{args.out_prefix}.variant_nhf.tsv"
+        with open(tsv_path, "w") as fh:
+            fh.write(tsv)
+        with open(f"{args.out_prefix}.summary.json", "w") as fh:
+            json.dump([v.to_dict() for v in results], fh, indent=2)
+        logging.info("Wrote %s", tsv_path)
+    else:
+        sys.stdout.write(tsv)
+    return 0
+
+
+def _classify_all(args):
+    import pysam
+
+    from nonhuman_screen.engine import Kraken2Runner
+
+    sequences = {}
+    with pysam.AlignmentFile(
+        args.bam, reference_filename=args.ref_fasta or None
+    ) as bam:
+        for read in bam.fetch(until_eof=True):
+            n = read.query_name
+            if read.query_sequence and n not in sequences:
+                sequences[n] = read.query_sequence
+
+    runner = Kraken2Runner(
+        args.kraken2_db, confidence=args.confidence, threads=args.threads,
+        memory_mapping=args.memory_mapping,
+    )
+    result = runner.classify_sequences(sequences)
+    summary = {
+        "reads": result.total,
+        "classified": result.classified,
+        "taxonomy_available": result.taxonomy_available,
+        "nonhuman_fraction": result.nonhuman_fraction,
+        "fractions": result.fractions().to_dict(),
+    }
+    out = json.dumps(summary, indent=2)
+    if args.out_prefix:
+        with open(f"{args.out_prefix}.summary.json", "w") as fh:
+            fh.write(out + "\n")
+    else:
+        sys.stdout.write(out + "\n")
+    logging.info("%s", result.summary())
+    return 0
+
+
+def main(argv=None):
+    logging.basicConfig(
+        level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s",
+    )
+    args = _build_parser().parse_args(argv)
+
+    if args.command == "classify":
+        if shutil.which("kraken2") is None:
+            sys.stderr.write(
+                "error: kraken2 not found on PATH. Install kraken2 "
+                "(see docs/database.md) and try again.\n"
+            )
+            return 2
+        if args.variants:
+            return _classify_variants(args)
+        return _classify_all(args)
+
+    return 1  # pragma: no cover - argparse requires a subcommand
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())