bio-interdomain-hgt

Bio Interdomain HGT

Detect, polarize, and confirm horizontal gene transfer between a query genome (virus, MAG, isolate, or bin) and other domains of life. Built for the common asymmetric case where the query is well annotated but the comparison set is genome-only (proteins missing). Pairs with /bio-annotation (homology/taxonomy), /bio-phylogenomics (trees), /bio-viromics (viral classification), and /bio-fasta-database-curator (building the arbiter database).

Instructions

Run the steps in order; capture outputs and provenance at each step. Steps 0 (database gate) and 5 (frame-aware context guard on eukaryotic DNA) are the ones most often skipped and most often responsible for wrong conclusions.

Use the versioned evidence driver after the homology, context, and tree tools have produced their normalized TSVs:

uv run --script skills/bio-interdomain-hgt/scripts/run_hgt_evidence.py \
  forward_hits.tsv --arbiter-hits arbiter_hits.tsv --reciprocal reciprocal.tsv \
  --context context.tsv --trees trees.tsv --sampling-depth sampling_depth.tsv \
  --databases databases.json --hypotheses hypotheses.tsv --reflections reflections.tsv \
  --query-domain ncldv --out results/bio-interdomain-hgt

The driver checksum-verifies the comprehensive arbiter, labels, and comparison collection; applies homology, reciprocal-best-hit, direction, frame-aware context, and phylogeny gates; normalizes confirmed candidates by lineage sampling depth; and requires a hypothesis reflection at every gate. Its run contract is schemas/hgt-evidence.schema.json.

Step 0 — Database availability gate (DO THIS FIRST; never hardcode paths)

HGT calls are only as good as the reference. Resolve the site/project DB root from $BIO_DB_ROOT (or ask) — never bake absolute paths into the analysis. Verify that BOTH of the following exist before any search; if one is missing, build it or STOP.

1. A comprehensive multi-domain reciprocal-arbiter proteome: a single protein search database (DIAMOND .dmnd or MMseqs2) that contains eukaryotes + bacteria
   • archaea + viruses (including NCLDV/giant viruses and phages) + organelles, with a parallel genome_id -> lineage labels table. This one database is what makes "best-hit taxon" — and therefore transfer direction — meaningful.
   • Building blocks: EukProt, GTDB, NCBI nr/RefSeq, IMG/VR, a giant-virus proteome (GVDB / gvclass-style), organelle RefSeq.
   • Check: list $BIO_DB_ROOT for an existing combined-proteome .dmnd + labels.
   • If absent: build it with /bio-fasta-database-curator (prefix every header by domain, e.g. EUK__, BAC__, ARC__, NCLDV__, PHAGE__, then diamond makedb). A clustered build (clusterednr / MMseqs2-reduced) is much faster at comparable sensitivity — prefer it.
   • A euk-only or virus-only arbiter CANNOT polarize transfer. Confirm it spans every candidate donor domain.
2. A per-domain genome/proteome collection for the comparison side (e.g. a eukaryote genome catalog such as EukProt/MMETSP/NCBI/Mycocosm; a viral genome catalog such as IMG/VR/RefSeq). Prefer one with a queryable metadata table (per-genome taxonomy + completeness + contamination) so hits can be quality-flagged.
   • Record whether the collection ships PROTEINS or only NUCLEOTIDES — this decides the forward-search tool in Step 2.