feat: make --gtf and --bed mutually exclusive; GTF now runs all analyses

Allow users to provide either a GTF or BED annotation file (but not both).
GTF mode runs everything (dupRadar, featureCounts, and all 7 RSeQC tools)
by deriving transcript-level structure from the GTF. BED mode runs only
RSeQC tools, skipping dupRadar/featureCounts with a warning.

Key changes:
- Extend GTF parser with Transcript struct (exon blocks + CDS range)
- Add from_genes() constructors to all 5 annotation-requiring RSeQC tools
- Extract shared junction/intron helpers into rseqc::common module
- Pre-build all RSeQC data structures once (no more per-BAM BED re-parsing)
- Fix inner_distance first-transcript-per-chromosome RSeQC bug
- Update all documentation to reflect new CLI semantics

Author: ewels

AGENTS.md

@@ -63,7 +63,8 @@ src/
       mod.rs        — Re-exports output
       output.rs     — featureCounts-format output & biotype counting
     rseqc/
-      mod.rs        — Re-exports all 7 RSeQC modules
+      mod.rs        — Re-exports all 7 RSeQC modules + common helpers
+      common.rs             — Shared junction/intron extraction, from_genes/from_bed builders
       bam_stat.rs           — bam_stat.py reimplementation
       infer_experiment.rs   — infer_experiment.py reimplementation
       read_duplication.rs   — read_duplication.py reimplementation
@@ -83,17 +84,19 @@ in `main.rs`, no `lib.rs`. The `rna` module contains sub-modules for each tool g
 Inter-module access uses `crate::` paths (e.g., `use crate::rna::dupradar::counting::GeneCounts;`).
 
 The CLI uses a single subcommand:
-- `rustqc rna <BAM>... --gtf <GTF> [--bed <BED>] [OPTIONS]`
-
-This runs all analyses in a single pass: dupRadar duplicate rate analysis,
-featureCounts-compatible gene counting, and all 7 RSeQC-equivalent tools
-(bam_stat, infer_experiment, read_duplication, read_distribution,
-junction_annotation, junction_saturation, inner_distance).
-
-The `--bed` flag is optional. If omitted, a warning is printed and the 5 tools
-that require a BED12 gene model (infer_experiment, read_distribution,
-junction_annotation, junction_saturation, inner_distance) are skipped.
-The 2 tools that don't need a BED file (bam_stat, read_duplication) still run.
+- `rustqc rna <BAM>... (--gtf <GTF> | --bed <BED>) [OPTIONS]`
+
+The `--gtf` and `--bed` flags are **mutually exclusive** — provide one or the other:
+
+- **`--gtf`** (recommended): Runs all analyses — dupRadar duplicate rate analysis,
+  featureCounts-compatible gene counting, and all 7 RSeQC-equivalent tools
+  (bam_stat, infer_experiment, read_duplication, read_distribution,
+  junction_annotation, junction_saturation, inner_distance). The GTF parser
+  extracts transcript-level structure (exons + CDS features) to derive all
+  data needed by every tool.
+- **`--bed`**: Runs only the 7 RSeQC tools + bam_stat + read_duplication.
+  DupRadar and featureCounts are skipped (they require gene-level annotation
+  with biotype attributes that BED12 cannot provide).
 
 Individual tools can be disabled via the YAML config file (each has an `enabled`
 toggle). Tool-specific parameters (e.g., `--min-intron`, `--inner-distance-lower-bound`)

CHANGELOG.md

@@ -29,10 +29,10 @@ be disabled via the YAML config file.
 - bam_stat -- alignment statistics
 - infer_experiment -- library strandedness inference
 - read_duplication -- position-based and sequence-based duplication histograms
-- read_distribution -- read distribution across genomic features (requires `--bed`)
-- junction_annotation -- splice junction classification (requires `--bed`)
-- junction_saturation -- junction saturation curves (requires `--bed`)
-- inner_distance -- insert size estimation for paired-end reads (requires `--bed`)
+- read_distribution -- read distribution across genomic features
+- junction_annotation -- splice junction classification
+- junction_saturation -- junction saturation curves
+- inner_distance -- insert size estimation for paired-end reads
 
 ### General
 

README.md

@@ -29,7 +29,7 @@ All tools accept SAM/BAM/CRAM input and support processing multiple files in a s
 
 ### `rustqc rna` -- RNA-Seq quality control
 
-Performs dupRadar-equivalent duplicate rate analysis, featureCounts-compatible read counting, and 7 RSeQC-equivalent QC analyses in a single pass. Given a duplicate-marked BAM, GTF annotation, and optional BED12 gene model, it computes per-gene duplication rates, fits a logistic regression model, generates diagnostic plots, produces gene-level count files with biotype summaries, and runs comprehensive QC metrics (bam_stat, infer_experiment, read_duplication, read_distribution, junction_annotation, junction_saturation, inner_distance).
+Performs dupRadar-equivalent duplicate rate analysis, featureCounts-compatible read counting, and 7 RSeQC-equivalent QC analyses in a single pass. Given a duplicate-marked BAM and either a GTF annotation or a BED12 gene model, it computes per-gene duplication rates, fits a logistic regression model, generates diagnostic plots, produces gene-level count files with biotype summaries, and runs comprehensive QC metrics (bam_stat, infer_experiment, read_duplication, read_distribution, junction_annotation, junction_saturation, inner_distance).
 
 | Feature | dupRadar (R) | RustQC |
 |---------|-------------|--------|
@@ -56,7 +56,7 @@ The `rustqc rna` command also includes reimplementations of 7 popular [RSeQC](ht
 | junction_saturation | `junction_saturation.py` | Saturation analysis of detected splice junctions |
 | inner_distance | `inner_distance.py` | Inner distance distribution for paired-end reads |
 
-All RSeQC tools run by default. Five of the seven tools require a BED12 gene model file (`--bed`); if `--bed` is not provided, those tools are skipped with a warning. Individual tools can be disabled via the [configuration file](#configuration).
+All RSeQC tools run by default when annotation is provided via `--gtf` or `--bed`. With a GTF file, all 7 tools run alongside dupRadar and featureCounts. With a BED file only, all 7 RSeQC tools run but dupRadar and featureCounts are skipped (they require a GTF). Individual tools can be disabled via the [configuration file](#configuration).
 
 ## Density scatter plots
 
@@ -140,15 +140,16 @@ The binary will be at `target/release/rustqc`.
 ### RNA duplicate rate analysis
 
 ```bash
-rustqc rna <INPUT>... --gtf <GTF> [OPTIONS]
+rustqc rna <INPUT>... (--gtf <GTF> | --bed <BED>) [OPTIONS]
 ```
 
 #### Required arguments
 
 | Argument | Description |
 |----------|-------------|
 | `<INPUT>...` | One or more duplicate-marked alignment files (SAM/BAM/CRAM). Duplicates must be flagged (SAM flag 0x400), not removed. BAM/CRAM files should be sorted and indexed for parallel processing. |
-| `--gtf <GTF>` | Path to a GTF gene annotation file (e.g., from Ensembl or UCSC). |
+| `--gtf <GTF>` | Path to a GTF gene annotation file. Runs all analyses (dupRadar + featureCounts + all 7 RSeQC tools). Mutually exclusive with `--bed`. |
+| `--bed <BED>` | Path to a BED12 gene model file. Runs RSeQC tools only (dupRadar and featureCounts are skipped). Mutually exclusive with `--gtf`. |
 
 #### Options
 
@@ -166,10 +167,13 @@ rustqc rna <INPUT>... --gtf <GTF> [OPTIONS]
 #### Examples
 
 ```bash
-# Single BAM, single-end, unstranded
+# Single BAM with GTF (all analyses: dupRadar + featureCounts + all 7 RSeQC tools)
 rustqc rna sample.markdup.bam --gtf genes.gtf --outdir results/
 
-# Single BAM, paired-end, reverse-stranded
+# Single BAM with BED (RSeQC tools only, no dupRadar/featureCounts)
+rustqc rna sample.markdup.bam --bed genes.bed --outdir results/
+
+# Paired-end, reverse-stranded
 rustqc rna sample.markdup.bam --gtf genes.gtf --paired --stranded 2 --outdir results/
 
 # CRAM input with reference FASTA
@@ -184,21 +188,12 @@ rustqc rna sample.markdup.bam --gtf gencode.gtf --paired --biotype-attribute gen
 
 ### RSeQC tools
 
-The RSeQC tools are integrated into `rustqc rna` and run automatically. To enable the tools that require a BED12 gene model (infer_experiment, read_distribution, junction_annotation, junction_saturation, inner_distance), pass `--bed`:
-
-```bash
-# Run everything: dupRadar + featureCounts + all 7 RSeQC tools
-rustqc rna sample.markdup.bam --gtf genes.gtf --bed genes.bed --outdir results/
-
-# Without --bed: dupRadar + featureCounts + bam_stat + read_duplication only
-rustqc rna sample.markdup.bam --gtf genes.gtf --outdir results/
-```
+The 7 RSeQC tools are integrated into `rustqc rna` and run automatically with either `--gtf` or `--bed`. With a GTF file, all analyses run (dupRadar + featureCounts + all 7 RSeQC tools). With a BED file, only the 7 RSeQC tools run.
 
 RSeQC-specific options:
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `--bed <BED>` | none | BED12 gene model (enables 5 additional RSeQC tools) |
 | `-q` / `--mapq <N>` | `30` | Minimum mapping quality for RSeQC tools |
 | `--infer-experiment-sample-size <N>` | `200000` | Max reads to sample for strandedness inference |
 | `--min-intron <N>` | `50` | Minimum intron size for junction tools |

benchmark/README.md

@@ -154,27 +154,11 @@ cargo build --release
 > to match the GENCODE GTF. The `--biotype-attribute gene_type` flag is needed
 > because GENCODE uses `gene_type` instead of the Ensembl default `gene_biotype`.
 
-### 5. Run RSeQC tools (RustQC reimplementations)
+### 5. RSeQC tools (RustQC reimplementations)
 
-The RSeQC tools are integrated into `rustqc rna` and run automatically when a
-`--bed` file is provided. To include all 7 RSeQC tools in the analysis, add
-`--bed` to the command:
-
-```bash
-# Small — all analyses including RSeQC tools
-./target/release/rustqc rna benchmark/input/small/test.bam \
-  --gtf benchmark/input/small/chr6.gtf -p --skip-dup-check \
-  --bed benchmark/input/small/chr6.bed \
-  -o benchmark/RustQC/small
-
-# Large — all analyses including RSeQC tools
-./target/release/rustqc rna benchmark/input/large/GM12878_REP1.markdup.sorted.bam \
-  --gtf benchmark/input/large/genes.gtf -p -t 10 \
-  --bed benchmark/input/large/genes.bed \
-  -o benchmark/RustQC/large \
-  -c benchmark/input/large/config.yaml \
-  --biotype-attribute gene_type
-```
+All 7 RSeQC tools are integrated into `rustqc rna` and run automatically when
+`--gtf` is provided (the commands in step 4 already include all RSeQC analyses).
+No separate `--bed` file is needed — all required data is derived from the GTF.
 
 ### 6. Generate RSeQC Python reference outputs
 

docs/src/content/docs/getting-started/introduction.md

@@ -55,7 +55,7 @@ Seven reimplementations of [RSeQC](https://rseqc.sourceforge.net/) tools, all in
 | junction_saturation | Assess saturation of splice junction detection at increasing read depths |
 | inner_distance | Compute inner distance between paired-end read mates |
 
-Five tools (infer_experiment, read_distribution, junction_annotation, junction_saturation, inner_distance) require a BED12 gene model file via `--bed`. If `--bed` is omitted, these tools are skipped with a warning while the remaining tools still run. Individual tools can be disabled via the YAML configuration file.
+When a GTF file is provided via `--gtf`, all 7 tools run automatically — transcript-level structure is extracted from the GTF. Alternatively, a BED12 gene model file can be provided via `--bed` (mutually exclusive with `--gtf`), which runs only the RSeQC tools. Individual tools can be disabled via the YAML configuration file.
 
 ## Credits
 

docs/src/content/docs/getting-started/quickstart.md

@@ -10,8 +10,7 @@ This guide walks you through a basic RustQC analysis from start to finish.
 The `rustqc rna` command runs all analyses in a single pass. It requires:
 
 - A **duplicate-marked** alignment file (BAM, SAM, or CRAM). Duplicates must be flagged with SAM flag 0x400 by a tool like [Picard MarkDuplicates](https://broadinstitute.github.io/picard/), [samblaster](https://github.com/GregoryFaust/samblaster), or [sambamba](https://github.com/biod/sambamba).
-- A **GTF annotation** file (for dupRadar, featureCounts, and gene-level analyses).
-- Optionally, a **BED12 gene model** file (`--bed`) for the 5 RSeQC tools that require it (infer_experiment, read_distribution, junction_annotation, junction_saturation, inner_distance). If omitted, these tools are skipped with a warning.
+- Either a **GTF annotation** file (`--gtf`) or a **BED12 gene model** file (`--bed`). With a GTF, all analyses run (dupRadar, featureCounts, and all 7 RSeQC tools). With a BED file, only the 7 RSeQC tools run. The two flags are mutually exclusive.
 
 ## RNA-seq duplicate analysis
 
@@ -50,13 +49,12 @@ integrated into the `rustqc rna` command. They run automatically alongside the
 dupRadar and featureCounts analyses:
 
 ```bash
-# Run everything: dupRadar + featureCounts + all 7 RSeQC tools
-rustqc rna sample.markdup.bam --gtf genes.gtf --bed genes.bed -p -o results/
-```
+# Run everything with a GTF: dupRadar + featureCounts + all 7 RSeQC tools
+rustqc rna sample.markdup.bam --gtf genes.gtf -p -o results/
 
-The `--bed` flag provides a BED12 gene model required by 5 of the 7 tools. If
-omitted, those tools are skipped with a warning while bam_stat and
-read_duplication still run.
+# Or run RSeQC tools only with a BED file (no dupRadar/featureCounts)
+rustqc rna sample.markdup.bam --bed genes.bed -p -o results/
+```
 
 To disable specific RSeQC tools, use a YAML config file:
 
@@ -67,7 +65,7 @@ inner_distance:
 ```
 
 ```bash
-rustqc rna sample.markdup.bam --gtf genes.gtf --bed genes.bed -p -c config.yaml -o results/
+rustqc rna sample.markdup.bam --gtf genes.gtf -p -c config.yaml -o results/
 ```
 
 See [RSeQC Outputs](/outputs/rseqc/) for details on output files.
@@ -79,32 +77,32 @@ producing its own set of output files:
 
 ```bash
 rustqc rna sample1.bam sample2.bam sample3.bam \
-  --gtf genes.gtf --bed genes.bed -p -t 8 -o results/
+  --gtf genes.gtf -p -t 8 -o results/
 ```
 
-The GTF and BED files are parsed once and shared across all samples. Threads
+The annotation file is parsed once and shared across all samples. Threads
 are distributed automatically among concurrent jobs.
 
 ## Common options
 
 ```bash
 # Stranded library (forward)
-rustqc rna sample.bam --gtf genes.gtf --bed genes.bed -p -s 1
+rustqc rna sample.bam --gtf genes.gtf -p -s 1
 
 # Use 8 threads
-rustqc rna sample.bam --gtf genes.gtf --bed genes.bed -p -t 8
+rustqc rna sample.bam --gtf genes.gtf -p -t 8
 
 # CRAM input with reference
-rustqc rna sample.cram --gtf genes.gtf --bed genes.bed -p --reference genome.fa
+rustqc rna sample.cram --gtf genes.gtf -p --reference genome.fa
 
 # Skip duplicate-marking validation
 rustqc rna sample.bam --gtf genes.gtf -p --skip-dup-check
 
 # Use a YAML config file
-rustqc rna sample.bam --gtf genes.gtf --bed genes.bed -p --config config.yaml
+rustqc rna sample.bam --gtf genes.gtf -p --config config.yaml
 
 # Custom MAPQ cutoff for RSeQC tools
-rustqc rna sample.bam --gtf genes.gtf --bed genes.bed -p -q 20 -o results/
+rustqc rna sample.bam --gtf genes.gtf -p -q 20 -o results/
 ```
 
 ## Next steps

docs/src/content/docs/outputs/rseqc.md

@@ -9,7 +9,7 @@ original Python implementation.
 
 All RSeQC tools run automatically as part of the `rustqc rna` command and use
 the input filename stem as a prefix for output files. For example,
-`rustqc rna sample.bam --gtf genes.gtf --bed genes.bed -o results/` produces
+`rustqc rna sample.bam --gtf genes.gtf -o results/` produces
 RSeQC output files like `results/sample.bam_stat.txt`.
 
 ## bam_stat

docs/src/content/docs/usage/cli-reference.md

@@ -16,7 +16,7 @@ read_distribution, junction_annotation, junction_saturation, inner_distance).
 ### Synopsis
 
 ```
-rustqc rna <INPUT>... --gtf <GTF> [--bed <BED>] [OPTIONS]
+rustqc rna <INPUT>... (--gtf <GTF> | --bed <BED>) [OPTIONS]
 ```
 
 ### Positional arguments
@@ -31,32 +31,36 @@ producing its own set of output files. Threads are divided evenly among
 concurrent jobs.
 
 ```bash
-# Single file
-rustqc rna sample.bam --gtf genes.gtf --bed genes.bed
+# Single file with GTF (all analyses)
+rustqc rna sample.bam --gtf genes.gtf
+
+# Single file with BED (RSeQC tools only; dupRadar/featureCounts skipped)
+rustqc rna sample.bam --bed genes.bed
 
 # Multiple files
-rustqc rna sample1.bam sample2.bam sample3.bam --gtf genes.gtf --bed genes.bed
+rustqc rna sample1.bam sample2.bam sample3.bam --gtf genes.gtf
 ```
 
-### Required options
+### Annotation options
 
-#### `--gtf <GTF>` / `-g <GTF>`
+Exactly one of `--gtf` or `--bed` must be provided. They are **mutually exclusive**.
 
-Path to the GTF gene annotation file. Used to define gene models for read
-counting and expression-level calculation. The GTF must contain `exon` features
-with a `gene_id` attribute.
+#### `--gtf <GTF>` / `-g <GTF>`
 
-### General options
+Path to a GTF gene annotation file. The GTF must contain `exon` features with a
+`gene_id` attribute. When a GTF is provided, **all analyses run**: dupRadar,
+featureCounts, and all 7 RSeQC tools. Transcript-level structure (exon blocks,
+CDS features) is extracted automatically and used by the RSeQC tools that
+previously required a separate BED file.
 
 #### `-b, --bed <BED>`
 
-Path to a BED12-format gene model file. Required for 5 of the 7 RSeQC tools
-(infer_experiment, read_distribution, junction_annotation, junction_saturation,
-inner_distance).
+Path to a BED12-format gene model file. When a BED file is provided **without**
+a GTF, only the 7 RSeQC tools run (plus bam_stat and read_duplication). dupRadar
+and featureCounts are skipped because BED files lack gene-level grouping and
+biotype information.
 
-If omitted, a warning is printed listing the tools that will be skipped. The
-2 tools that do not need a BED file (bam_stat, read_duplication) still run.
-Individual tools can also be disabled via the [configuration file](/usage/configuration/).
+Individual tools can be disabled via the [configuration file](/usage/configuration/).
 
 #### `-o, --outdir <DIR>`
 
@@ -170,35 +174,35 @@ tool runs by default as part of `rustqc rna` and can be disabled via the
 ### Examples
 
 ```bash
-# Basic paired-end analysis (all tools)
-rustqc rna sample.bam --gtf genes.gtf --bed genes.bed -p -o results/
+# Basic paired-end analysis with GTF (all tools)
+rustqc rna sample.bam --gtf genes.gtf -p -o results/
 
-# Reverse-stranded library with 8 threads
-rustqc rna sample.bam --gtf genes.gtf --bed genes.bed -p -s 2 -t 8 -o results/
+# BED-only mode (RSeQC tools only; dupRadar/featureCounts skipped)
+rustqc rna sample.bam --bed genes.bed -p -o results/
 
-# Without BED file (bam_stat + read_duplication only, others skipped)
-rustqc rna sample.bam --gtf genes.gtf -p -o results/
+# Reverse-stranded library with 8 threads
+rustqc rna sample.bam --gtf genes.gtf -p -s 2 -t 8 -o results/
 
 # CRAM input with reference
-rustqc rna sample.cram --gtf genes.gtf --bed genes.bed -p -r genome.fa -o results/
+rustqc rna sample.cram --gtf genes.gtf -p -r genome.fa -o results/
 
 # GENCODE GTF with explicit biotype attribute
-rustqc rna sample.bam --gtf gencode.v46.gtf --bed genes.bed -p \
+rustqc rna sample.bam --gtf gencode.v46.gtf -p \
   --biotype-attribute gene_type -o results/
 
 # Custom junction saturation sampling range
-rustqc rna sample.bam --gtf genes.gtf --bed genes.bed -p \
+rustqc rna sample.bam --gtf genes.gtf -p \
   --junction-saturation-percentile-floor 10 \
   --junction-saturation-percentile-ceiling 100 \
   --junction-saturation-percentile-step 10 -o results/
 
 # Custom inner distance histogram bounds
-rustqc rna sample.bam --gtf genes.gtf --bed genes.bed -p \
+rustqc rna sample.bam --gtf genes.gtf -p \
   --inner-distance-lower-bound -500 --inner-distance-upper-bound 500 \
   --inner-distance-step 10 -o results/
 
 # Multiple BAM files with parallel processing
-rustqc rna *.bam --gtf genes.gtf --bed genes.bed -p -t 8 -o results/
+rustqc rna *.bam --gtf genes.gtf -p -t 8 -o results/
 ```
 
 ---