Submit tasks as job arrays and fix RNAs in distill summaries

.gitignore

@@ -56,3 +56,6 @@ nextflow-local.config
 
 # scratch folder
 scratch/
+
+# local-only reference material (papers, notes)
+misc/

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)

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))
+- [Viral mode (DRAM-v Phase 1)](#example-usage) — see example 8 below
 
 ## Example Usage
 
@@ -70,6 +73,19 @@ nextflow run -bg WrightonLabCSU/DRAM \
   -profile singularity,full_mode
 ```
 
+8) **Viral mode (DRAM-v Phase 1) — AMG flags on geNomad+CheckV catalogs:**
+```bash
+nextflow run WrightonLabCSU/DRAM \
+  --input_fasta <path/to/viral_catalog_dir> \
+  --outdir <output> \
+  --call --annotate --summarize --qc \
+  --use_kofam --use_dbcan --use_merops \
+  --use_dramv true \
+  -profile singularity
+```
+`--use_dramv` runs after `COMBINE_ANNOTATIONS` and adds two columns to `raw-annotations.tsv`:
+`amg_flags` (string of M/K/E/A/P/T/F/B per the DRAM v1 conventions, no `V` since VOGdb is not yet wired, plus a non-v1 `N` for essential viral function — see below) and `is_transposon` (bool). The distillate is filtered to strict-AMG candidates (rows with `M` and without `A`/`P`/`T`/`N`) and emitted as a single `AMG` sheet in `metabolism_summary.xlsx`, with one count column per scaffold (vMAG). The `N` letter marks genes whose IDs hit `bin/assets/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.) that are likely essential for viral processes rather than auxiliary metabolism, and so are excluded from the strict-AMG sheet. They still appear in the full `raw-annotations.tsv` with `N` in `amg_flags` so users can review them. Viral mode forces `groupby_column=scaffold` and skips QUAST and rRNA/tRNA collection — those don't make sense at the per-scaffold granularity. Inputs that come from a typical geNomad → CheckV pipeline (a single multi-fasta of trimmed viral contigs) work out of the box; no VirSorter affi-contigs file is required.
+
 ## Nextflow Tips and Tricks
 
 The `-resume` option in Nextflow DSL2 allows you to efficiently manage and modify your workflow runs: