WrightonLabCSU · tpall · Nov 20, 2025 · Nov 20, 2025 · Nov 21, 2025 · Nov 21, 2025
diff --git a/.gitignore b/.gitignore
@@ -56,3 +56,6 @@ nextflow-local.config
 
 # scratch folder
 scratch/
+
+# local-only reference material (papers, notes)
+misc/
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,23 @@
 
 All notable changes to this project will be documented in this file.
 
+## Unreleased (feature/dramv-phase1)
+
+### Features
+
+- **DRAM-v Phase 1: viral mode for geNomad+CheckV catalogs.** A new `--use_dramv` flag adds AMG flagging and viral-flavoured distillation on top of the bacterial annotate pipeline, no VirSorter affi-contigs required.
+  - New `DRAMV_FLAGS` process runs after `COMBINE_ANNOTATIONS` and appends `amg_flags` (M/K/E/A/P/T/F/B per DRAM v1 conventions, less the `V` flag pending VOGdb integration) and `is_transposon` columns to `raw-annotations.tsv`.
+  - `distill.py --amg_only` filters annotations to AMG candidates (`M` set, `A`/`P`/`T` clear), restricts the distillate form to `potential_amg=TRUE` rows, and collapses them into a single `AMG` Excel sheet.
+  - Viral mode forces `groupby_column=scaffold`, skips QUAST and the rRNA/tRNA collectors (none of which align with per-vMAG aggregation), and runs SUMMARIZE in `--amg_only` mode.
+  - Bundled assets: `bin/assets/amg_database.tsv` (ported verbatim from DRAM v1) and `bin/utils/dramv_constants.py` (TRANSPOSON_PFAMS, CELL_ENTRY_CAZYS, VIRAL_PEPTIDASES_MEROPS).
+  - Pytest unit suite at `tests/unit/test_dramv_flags.py` covering individual flag firing, B-flag scaffold boundaries, sub-3-gene scaffolds, K-forces-M, E (verified AMG), F window, and FASTA parsing.
+
+### Bug Fixes
+
+- `bin/distill.py`: rewrote the pandas-era summarisation path on top of polars + `rule_parser.evaluate_rules_on_anno`, dropped the broken pandas `write_summarized_genomes_to_xlsx` shadow, fixed `bin_taxnomy` typo, swapped `pd.read_csv` for `pl.read_csv` for rrna/trna/quast, and converted the rrna section of `make_genome_stats` to polars.
+- `modules/local/distill/distill.nf`: stage rrna / trna / quast inputs under distinct names so the same `default_sheet` dummy in viral mode no longer triggers a Nextflow input-name collision.
+- `conf/modules.config`: dropped the `task.ext.args = "--groupby_column …"` SUMMARIZE override that double-defined the flag and silently won the click race.
+
 ## 2.0.0-beta24 - 2026-02-03
 
 [3659fda](https://github.com/WrightonLabCSU/DRAM/commit/3659fdaa0f9779108840e3bbf97c6d196b37a7d3)...[32d0527](https://github.com/WrightonLabCSU/DRAM/commit/32d05274be6eaeaed48de6bb5a047bd67f21fea1)

diff --git a/README.md b/README.md
@@ -8,6 +8,8 @@
 
 DRAM v2 (Distilled and Refined Annotation of Metabolism Version 2) is a tool for annotating metagenomic and genomic assembled data (e.g. scaffolds or contigs) or called genes (e.g. nuclotide or amino acid format). DRAM annotates MAGs using [KEGG](https://www.kegg.jp/) (if provided by the user), [UniRef90](https://www.uniprot.org/), [PFAM](https://pfam.xfam.org/), [dbCAN](http://bcb.unl.edu/dbCAN2/), [RefSeq viral](https://www.ncbi.nlm.nih.gov/genome/viruses/), [VOGDB](http://vogdb.org/) and the [MEROPS](https://www.ebi.ac.uk/merops/) peptidase database as well as custom user databases.
 
+Viral catalogs from a typical geNomad → CheckV pipeline are also supported via **DRAM-v Phase 1 viral mode** (`--use_dramv true`): per-vMAG (per-scaffold) AMG flagging (M/K/E/A/P/T/F/B per the v1 conventions) and a viral-flavoured distillate, no VirSorter affi-contigs file required. See the "Viral mode" example below.
+
 DRAM is run in four stages: 
 1) Gene Calling Prodogal - genes are called on user provided scaffolds or contigs 
 2) Gene Annotation - genes are annotated with a set of user defined databases 
@@ -26,6 +28,7 @@ For more detail on DRAM and how DRAM v2 works please see our DRAM products:
 - [Usage Examples](https://dramit.readthedocs.io/en/latest/usage.html)
 - [Parameter API]([#command-line-options](https://dramit.readthedocs.io/en/latest/params_doc.html))
 - [Rules API]([#nextflow-tips-and-tricks](https://dramit.readthedocs.io/en/latest/rules_parser.html))
+- [DRAM-v (Viral mode)](#dram-v-viral-mode) — per-sample / catalog launches, flag reference, `auxiliary_score`, geNomad adapter
 
 ## Example Usage
 
@@ -70,6 +73,98 @@ nextflow run -bg WrightonLabCSU/DRAM \
   -profile singularity,full_mode
 ```
 
+8) **Viral mode (DRAM-v) — AMG flags on geNomad+CheckV viral contigs.** See the dedicated [DRAM-v (Viral mode)](#dram-v-viral-mode) chapter below for the full guide (per-sample vs catalog, flag reference, `auxiliary_score`, and the geNomad adapter).
+
+## DRAM-v (Viral mode)
+
+DRAM-v adds three columns to the per-gene table and ships an AMG-filtered distillate. Designed for input from a geNomad → CheckV pipeline (no VirSorter affi-contigs file required).
+
+> **Note.** DRAM-v Phase 2 (V flag, `auxiliary_score`, geNomad adapter, `--max_auxiliary_score`, `--genomad_filename_prefix`) currently lives on this fork's `dev` branch only — `nextflow run WrightonLabCSU/DRAM ...` will not recognise these flags. Launch with `nextflow run tpall/DRAM -r dev ...` until the changes are upstreamed.
+
+Two run modes — pick whichever matches your input:
+
+- **Per-sample mode** — DRAM runs separately on each sample's filtered viral fasta (`<sample>_filtered.fna`). Used during development, smoke testing, or when you want per-sample annotations without going through clustering.
+- **Catalog mode** — DRAM runs once on a clustered vOTU catalog whose contigs were renamed `<sample>_<orig>` upstream. Standard MIUViG / Sullivan-lab production path, recommended for any multi-sample analysis.
+
+### What `--use_dramv` produces
+
+Three new columns in `ANNOTATE/raw-annotations.tsv` and `ANNOTATE/annotations_with_flags.tsv`:
+
+| Column | Type | Meaning |
+| --- | --- | --- |
+| `amg_flags` | str | concatenated single-letter flags in v1 order: `M K E V A P T F B`, plus a non-v1 `N` (see below) |
+| `is_transposon` | bool | the gene's Pfam hits intersect a curated transposon set |
+| `auxiliary_score` | int 1-5 | v1 flank-confidence score; lower = stronger viral context |
+
+The `--amg_only` distillate (a single `AMG` sheet in `metabolism_summary.xlsx`, one count column per scaffold) keeps rows where `amg_flags` contains `M`, lacks `A`/`P`/`T`/`N`, **and** `auxiliary_score ≤ --max_auxiliary_score` (default 3). Set `--max_auxiliary_score 5` to disable the score filter.
+
+Viral mode forces `groupby_column=scaffold` and skips QUAST + rRNA/tRNA collection — none of those make sense per-scaffold.
+
+### Per-sample mode
+
+```bash
+nextflow run tpall/DRAM -r dev \
+  --input_fasta path/to/filtered_fastas_dir \
+  --fasta_fmt "*.fna" \
+  --outdir results/dramv \
+  --call --annotate --summarize \
+  --use_kofam --use_dbcan --use_merops \
+  --use_dramv true \
+  --genomad_genes "path/to/genomad_genes/*_virus_genes.tsv" \
+  -profile singularity
+```
+
+Each gene id matches between DRAM and geNomad (both call genes from scratch on the same per-sample fasta), so the geNomad → DRAM join hits via direct gene-id equality.
+
+### Catalog mode
+
+```bash
+nextflow run tpall/DRAM -r dev \
+  --input_fasta path/to/votu_catalog.fa \
+  --outdir results/dramv \
+  --call --annotate --summarize \
+  --use_kofam --use_dbcan --use_merops \
+  --use_dramv true \
+  --genomad_genes "path/to/genomad_genes/*_virus_genes.tsv" \
+  --genomad_filename_prefix true \
+  -profile singularity
+```
+
+Catalog contigs are typically renamed `<sample>_<orig>` upstream so cross-sample names don't collide. Without `--genomad_filename_prefix true`, geNomad's per-sample gene ids (`<orig>_<num>`) won't match DRAM's catalog gene ids (`<sample>_<orig>_<num>`) and `auxiliary_score` collapses to 5 for every row — which the default `--max_auxiliary_score 3` filter would then drop entirely. With the flag on, each `<sample>_virus_genes.tsv` filename is parsed to derive the prefix and the join lines up.
+
+### Flag reference
+
+| Flag | Meaning |
+| --- | --- |
+| **`M`** | metabolism — gene matches a curated metabolic-gene set (KEGG/Pfam/CAZy/EC) |
+| **`K`** | gene id appears in `bin/assets/amg_database.tsv`. `K` force-sets `M` per v1 |
+| **`E`** | same as `K`, restricted to verified AMG rows |
+| **`V`** | gene has a VOG hit whose VOGdb `FunctionalCategory` is `Xr` (replication) or `Xs` (structure). Requires `vog_annotations_latest.tsv`; `--use_dramv` auto-enables `--use_vog` |
+| **`A`** | gene matches the curated cell-entry CAZy set |
+| **`P`** | gene matches the curated viral peptidase MEROPS set |
+| **`T`** | any gene on the same scaffold has `is_transposon=true` |
+| **`F`** | gene is within `--amg_length_from_end` (default 5000) bp of either contig end |
+| **`B`** | gene is part of a 3-consecutive-`M`-gene window on the scaffold |
+| **`N`** *(not v1)* | gene id hits `amg_database.tsv` rows where `essential_viral_function=TRUE`, per [Martin et al. 2025](https://doi.org/10.1038/s41564-025-02095-4). Paper-cautioned genes (DsrC, QueC/QueF, folA/folB/folK, RNR, mazG, pur*, etc.) likely essential for viral processes rather than auxiliary metabolism. `N`-flagged rows are excluded from the strict-AMG distillate but stay in the full `raw-annotations.tsv` for review. `N` does **not** force `M`. |
+
+### `auxiliary_score` reference
+
+Verbatim port of v1's flank-confidence algorithm (`mag_annotator/annotate_vgfs.py:calculate_auxiliary_scores`, commit `6cd68f9`). Lower is better:
+
+| Score | Condition |
+| --- | --- |
+| 1 | hallmark virus genes on **both** flanks |
+| 2 | hallmark on one side, viral-like on the other |
+| 3 | viral-like on both sides |
+| 4 | hallmark/viral-like on at least one side, **or** self carries one |
+| 5 | first/last on scaffold, **or** no viral context anywhere |
+
+Then the `B`-flag downgrade fires: any gene with `B` in `amg_flags` and `auxiliary_score < 4` is bumped to 4 (a stretch of three metabolic genes is suspicious in a true viral region).
+
+Without `--genomad_genes`, every gene scores 5 (v1 fallback for genomes without VirSorter input). Provide it to populate the score: geNomad's `virus_hallmark = 1` rows and marker suffix `.VV` / `.Vv` map to VirSorter hallmark (cat `0`); marker suffix `.vV` / `.vv` maps to viral-like (cat `1`).
+
+The DRAM-v ↔ geNomad join is hybrid: direct gene-id equality first, position-overlap on the parent assembly contig as fallback. CheckV-trimmed provirus contigs (`<contig>|provirus_<start>_<end>`) are handled in both paths.
+
 ## Nextflow Tips and Tricks
 
 The `-resume` option in Nextflow DSL2 allows you to efficiently manage and modify your workflow runs:

diff --git a/assets/NO_FILE b/assets/NO_FILE
diff --git a/assets/internal/generate_sql_database.py b/assets/internal/generate_sql_database.py