nonhuman-screen 0.1.0__tar.gz

nonhuman_screen-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jlanej
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nonhuman_screen-0.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: nonhuman-screen
+Version: 0.1.0
+Summary: Classify sequencing reads by non-human taxonomic content (kraken2), including the allele-based non-human fraction of reads supporting a variant.
+License: MIT
+Project-URL: Homepage, https://github.com/jlanej/nonhuman-screen
+Project-URL: Documentation, https://github.com/jlanej/nonhuman-screen/tree/main/docs
+Keywords: kraken2,contamination,metagenomics,non-human,taxonomy,variant,bioinformatics,sequencing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: bam
+Requires-Dist: pysam>=0.21.0; extra == "bam"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pysam>=0.21.0; extra == "dev"
+Dynamic: license-file
+
+# nonhuman-screen
+
+Classify sequencing reads by **non-human taxonomic content** using
+[kraken2](https://github.com/DerrickWood/kraken2), and reduce the per-read
+verdicts to a **non-human fraction (NHF)** plus per-domain breakdowns
+(bacterial / archaeal / fungal / protist / viral / UniVec-Core).
+
+The headline capability is the **allele-based NHF**: given a BAM/CRAM and a
+variant, compute the non-human fraction of the reads that support that
+variant's ALT allele — in one call, no boilerplate:
+
+```python
+from nonhuman_screen import classify_variant_alt_reads
+
+v = classify_variant_alt_reads(
+    "sample.bam", "kraken2_db", "chr1", 12345, "A", "T", ref_fasta="ref.fa",
+)
+v.nonhuman_fraction   # 0.0–1.0 over ALT-supporting reads
+v.fractions.bacterial # per-domain breakdown
+v.supporting_reads    # denominator
+```
+
+`nonhuman-screen` is **sample-agnostic**: it classifies whatever reads you hand
+it and never asks whose they are. The same call works on a proband, a parent, a
+tumour, or a plain FASTQ — so it can back higher-level analyses (e.g. flagging
+inherited variant calls that are actually parental contamination) without
+knowing anything about pedigrees.
+
+> Extracted from [`kmer-denovo-filter`](https://github.com/jlanej/kmer_denovo_filter),
+> where this methodology was originally developed, so it can be reused
+> independently.
+
+## How it works (in one paragraph)
+
+Reads are written to a temporary FASTQ and classified by kraken2's LCA
+algorithm. Each read's assigned taxid is mapped to a domain using the
+database's `nodes.dmp` taxonomy. A read counts as **non-human** only if it is
+classified and lies outside the human lineage, outside the human clade, and
+outside UniVec-Core. Two conservative guards reduce false positives: a
+**human-homology guard** (any k-mer voting for human, taxid 9606, drops the read
+from every non-human numerator — important for integrating viruses such as
+HBV/HPV/ERVs) and **UniVec-Core exclusion** (synthetic vector/adapter sequences,
+taxid 81077, are tracked separately and never counted as contamination). See
+[docs/methodology.md](docs/methodology.md).
+
+## Install
+
+```bash
+pip install nonhuman-screen           # core engine (standard library only)
+pip install 'nonhuman-screen[bam]'    # + BAM/CRAM & allele-based NHF (pysam)
+```
+
+The **`bam` extra is required for the BAM/allele helpers and for the
+`nonhuman-screen` CLI** (both classify modes import pysam). The core install
+covers only `Kraken2Runner.classify_sequences` on in-memory reads.
+
+You also need the `kraken2` binary on `PATH` and a kraken2 database — see
+[docs/database.md](docs/database.md).
+
+## Usage
+
+### Allele-based NHF for many variants (batched — one kraken2 call)
+
+```python
+from nonhuman_screen import classify_variants_alt_reads
+
+variants = [("chr1", 12345, "A", "T"), ("chr2", 999, "G", "GAC")]  # pos 0-based
+for v in classify_variants_alt_reads("sample.bam", "kraken2_db", variants,
+                                      ref_fasta="ref.fa"):
+    print(v.variant_key, v.nonhuman_fraction, v.supporting_reads)
+```
+
+The reads supporting all variants' ALT alleles are gathered and classified in a
+**single** kraken2 invocation (its database load dominates runtime), then split
+back per variant. You never re-implement fetch/allele-filter/classify yourself.
+
+### Classify an arbitrary set of reads
+
+```python
+from nonhuman_screen import Kraken2Runner
+
+result = Kraken2Runner("kraken2_db").classify_sequences(
+    {"read1": "ACGT...", "read2": "TTGCA..."}
+)
+result.nonhuman_fraction        # 0.0–1.0
+result.fractions()              # TaxonomicFractions(nonhuman=…, bacterial=…, …)
+result.taxonomy_available       # False if nodes.dmp was missing (fractions unreliable)
+result.nonhuman_read_names      # set of read names
+```
+
+### Command line
+
+```bash
+# Per-variant allele NHF table (headline)
+nonhuman-screen classify \
+    --bam sample.bam --kraken2-db kraken2_db --ref-fasta ref.fa \
+    --variants candidates.vcf.gz --out-prefix sample_contam
+# -> sample_contam.variant_nhf.tsv, sample_contam.summary.json
+
+# Whole-BAM summary
+nonhuman-screen classify --bam sample.bam --kraken2-db kraken2_db
+```
+
+See [docs/cli.md](docs/cli.md).
+
+## Coordinate convention
+
+All `pos` arguments in the Python API are **0-based** (pysam reference
+coordinates); variant keys are `"{chrom}:{pos}:{ref}:{alt}"`. The CLI reads a
+VCF and handles the conversion for you.
+
+## API summary
+
+| Symbol | Needs `[bam]` | Purpose |
+|---|:---:|---|
+| `Kraken2Runner.classify_sequences(seqs)` | no | Classify `{name: seq}` → `ClassificationResult` |
+| `ClassificationResult` | no | Per-domain read-name sets, counts, `fractions()`, `nonhuman_fraction`, `taxonomy_available` |
+| `TaxonomicFractions` | no | Per-domain fractions; `from_result` / `over_reads` |
+| `read_supports_alt(read, variant_pos, ref, alt)` | no | Does an aligned read carry the ALT allele? |
+| `parse_kmer_votes(kmer_string)` | no | Parse kraken2 per-read k-mer detail into taxid votes |
+| `VariantNHF` | no | Result of the allele-based helpers: `variant_key`, `nonhuman_fraction`, `supporting_reads`, `fractions`, `to_dict()` (pos 0-based) |
+| `classify_variant_alt_reads(...)` | yes | Allele-based NHF for one variant → `VariantNHF` |
+| `classify_variants_alt_reads(...)` | yes | Batched allele-based NHF for many variants |
+| `classify_reads_from_bam(...)` | yes | Classify reads by name and/or locus |
+| `reads_supporting_alt(...)` | yes | Read names supporting an ALT allele |
+
+## Docker
+
+The included [`Dockerfile`](Dockerfile) installs the pinned kraken2 (v2.17.1) and
+the package with the `[bam]` extra:
+
+```bash
+docker build -t nonhuman-screen .
+
+docker run --rm -v "$PWD:/data" nonhuman-screen \
+    classify --bam /data/sample.bam --kraken2-db /data/kraken2_db \
+             --variants /data/calls.vcf.gz --out-prefix /data/contam
+```
+
+The image entrypoint is `nonhuman-screen`; mount your BAM and kraken2 database in.
+You still supply the kraken2 database yourself (see [docs/database.md](docs/database.md)).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

nonhuman_screen-0.1.0/README.md

@@ -0,0 +1,145 @@
+# nonhuman-screen
+
+Classify sequencing reads by **non-human taxonomic content** using
+[kraken2](https://github.com/DerrickWood/kraken2), and reduce the per-read
+verdicts to a **non-human fraction (NHF)** plus per-domain breakdowns
+(bacterial / archaeal / fungal / protist / viral / UniVec-Core).
+
+The headline capability is the **allele-based NHF**: given a BAM/CRAM and a
+variant, compute the non-human fraction of the reads that support that
+variant's ALT allele — in one call, no boilerplate:
+
+```python
+from nonhuman_screen import classify_variant_alt_reads
+
+v = classify_variant_alt_reads(
+    "sample.bam", "kraken2_db", "chr1", 12345, "A", "T", ref_fasta="ref.fa",
+)
+v.nonhuman_fraction   # 0.0–1.0 over ALT-supporting reads
+v.fractions.bacterial # per-domain breakdown
+v.supporting_reads    # denominator
+```
+
+`nonhuman-screen` is **sample-agnostic**: it classifies whatever reads you hand
+it and never asks whose they are. The same call works on a proband, a parent, a
+tumour, or a plain FASTQ — so it can back higher-level analyses (e.g. flagging
+inherited variant calls that are actually parental contamination) without
+knowing anything about pedigrees.
+
+> Extracted from [`kmer-denovo-filter`](https://github.com/jlanej/kmer_denovo_filter),
+> where this methodology was originally developed, so it can be reused
+> independently.
+
+## How it works (in one paragraph)
+
+Reads are written to a temporary FASTQ and classified by kraken2's LCA
+algorithm. Each read's assigned taxid is mapped to a domain using the
+database's `nodes.dmp` taxonomy. A read counts as **non-human** only if it is
+classified and lies outside the human lineage, outside the human clade, and
+outside UniVec-Core. Two conservative guards reduce false positives: a
+**human-homology guard** (any k-mer voting for human, taxid 9606, drops the read
+from every non-human numerator — important for integrating viruses such as
+HBV/HPV/ERVs) and **UniVec-Core exclusion** (synthetic vector/adapter sequences,
+taxid 81077, are tracked separately and never counted as contamination). See
+[docs/methodology.md](docs/methodology.md).
+
+## Install
+
+```bash
+pip install nonhuman-screen           # core engine (standard library only)
+pip install 'nonhuman-screen[bam]'    # + BAM/CRAM & allele-based NHF (pysam)
+```
+
+The **`bam` extra is required for the BAM/allele helpers and for the
+`nonhuman-screen` CLI** (both classify modes import pysam). The core install
+covers only `Kraken2Runner.classify_sequences` on in-memory reads.
+
+You also need the `kraken2` binary on `PATH` and a kraken2 database — see
+[docs/database.md](docs/database.md).
+
+## Usage
+
+### Allele-based NHF for many variants (batched — one kraken2 call)
+
+```python
+from nonhuman_screen import classify_variants_alt_reads
+
+variants = [("chr1", 12345, "A", "T"), ("chr2", 999, "G", "GAC")]  # pos 0-based
+for v in classify_variants_alt_reads("sample.bam", "kraken2_db", variants,
+                                      ref_fasta="ref.fa"):
+    print(v.variant_key, v.nonhuman_fraction, v.supporting_reads)
+```
+
+The reads supporting all variants' ALT alleles are gathered and classified in a
+**single** kraken2 invocation (its database load dominates runtime), then split
+back per variant. You never re-implement fetch/allele-filter/classify yourself.
+
+### Classify an arbitrary set of reads
+
+```python
+from nonhuman_screen import Kraken2Runner
+
+result = Kraken2Runner("kraken2_db").classify_sequences(
+    {"read1": "ACGT...", "read2": "TTGCA..."}
+)
+result.nonhuman_fraction        # 0.0–1.0
+result.fractions()              # TaxonomicFractions(nonhuman=…, bacterial=…, …)
+result.taxonomy_available       # False if nodes.dmp was missing (fractions unreliable)
+result.nonhuman_read_names      # set of read names
+```
+
+### Command line
+
+```bash
+# Per-variant allele NHF table (headline)
+nonhuman-screen classify \
+    --bam sample.bam --kraken2-db kraken2_db --ref-fasta ref.fa \
+    --variants candidates.vcf.gz --out-prefix sample_contam
+# -> sample_contam.variant_nhf.tsv, sample_contam.summary.json
+
+# Whole-BAM summary
+nonhuman-screen classify --bam sample.bam --kraken2-db kraken2_db
+```
+
+See [docs/cli.md](docs/cli.md).
+
+## Coordinate convention
+
+All `pos` arguments in the Python API are **0-based** (pysam reference
+coordinates); variant keys are `"{chrom}:{pos}:{ref}:{alt}"`. The CLI reads a
+VCF and handles the conversion for you.
+
+## API summary
+
+| Symbol | Needs `[bam]` | Purpose |
+|---|:---:|---|
+| `Kraken2Runner.classify_sequences(seqs)` | no | Classify `{name: seq}` → `ClassificationResult` |
+| `ClassificationResult` | no | Per-domain read-name sets, counts, `fractions()`, `nonhuman_fraction`, `taxonomy_available` |
+| `TaxonomicFractions` | no | Per-domain fractions; `from_result` / `over_reads` |
+| `read_supports_alt(read, variant_pos, ref, alt)` | no | Does an aligned read carry the ALT allele? |
+| `parse_kmer_votes(kmer_string)` | no | Parse kraken2 per-read k-mer detail into taxid votes |
+| `VariantNHF` | no | Result of the allele-based helpers: `variant_key`, `nonhuman_fraction`, `supporting_reads`, `fractions`, `to_dict()` (pos 0-based) |
+| `classify_variant_alt_reads(...)` | yes | Allele-based NHF for one variant → `VariantNHF` |
+| `classify_variants_alt_reads(...)` | yes | Batched allele-based NHF for many variants |
+| `classify_reads_from_bam(...)` | yes | Classify reads by name and/or locus |
+| `reads_supporting_alt(...)` | yes | Read names supporting an ALT allele |
+
+## Docker
+
+The included [`Dockerfile`](Dockerfile) installs the pinned kraken2 (v2.17.1) and
+the package with the `[bam]` extra:
+
+```bash
+docker build -t nonhuman-screen .
+
+docker run --rm -v "$PWD:/data" nonhuman-screen \
+    classify --bam /data/sample.bam --kraken2-db /data/kraken2_db \
+             --variants /data/calls.vcf.gz --out-prefix /data/contam
+```
+
+The image entrypoint is `nonhuman-screen`; mount your BAM and kraken2 database in.
+You still supply the kraken2 database yourself (see [docs/database.md](docs/database.md)).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

nonhuman_screen-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nonhuman-screen"
+version = "0.1.0"
+description = "Classify sequencing reads by non-human taxonomic content (kraken2), including the allele-based non-human fraction of reads supporting a variant."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+keywords = [
+    "kraken2", "contamination", "metagenomics", "non-human",
+    "taxonomy", "variant", "bioinformatics", "sequencing",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+# The core engine (Kraken2Runner.classify_sequences) is standard-library only
+# and shells out to the `kraken2` binary. No third-party runtime dependency.
+dependencies = []
+
+[project.optional-dependencies]
+# BAM/CRAM + allele-based NHF helpers.
+bam = ["pysam>=0.21.0"]
+dev = ["pytest>=7.0", "pysam>=0.21.0"]
+
+[project.scripts]
+nonhuman-screen = "nonhuman_screen.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/jlanej/nonhuman-screen"
+Documentation = "https://github.com/jlanej/nonhuman-screen/tree/main/docs"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+nonhuman_screen = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

nonhuman_screen-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

nonhuman_screen-0.1.0/src/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-0.1.0/src/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()
+