feat(subworkflows): gtf_hybridmerge_gffcompare

[pinin4fjords]

Summary

Adds a new subworkflow gtf_hybridmerge_gffcompare that builds a hybrid GTF from a novel-transcript GTF and a reference annotation:

1. gffcompare classifies every novel transcript against the reference (assigns class codes).
2. gawk keeps only transcripts whose class code is in a user-supplied set (e.g. "u" for novel intergenic, "u,j,i" for a wider net).
3. bedtools intersect -v (optional) subtracts survivors that overlap a user-supplied blacklist BED, e.g. rRNA or repeat regions. Skipped by passing channel.empty().
4. gawk concatenates the survivors with an annotation backbone GTF, stripping comment lines and synthesising any gene row whose gene_id is referenced by a novel transcript but absent from the backbone. Synth gene rows span the union of their child transcripts' coordinates so the gene span is scientifically correct, not just the first transcript's footprint.

The output is a self-consistent hybrid GTF suitable as a --sjdbGTFfile for a second STAR pass, as input to gffread for transcriptome FASTA generation, or as the annotation any other downstream tool consumes.

The subworkflow takes a separate ch_reference_gtf (used by gffcompare for classification) and ch_backbone_gtf (the annotation skeleton the survivors are grafted onto). For most callers these are the same file - pass the same channel twice. Callers that want classification done against a fuller annotation but the novel transcripts grafted onto a reduced backbone (e.g. canonical-only) pass two different channels.

The emitted hybrid_gtf meta is the backbone's meta, not the novel input's. The hybrid GTF is logically the backbone annotation with novel transcripts grafted on, so its identity (and any downstream .join() that wants to align it with star-index, transcriptome-fasta or other backbone-keyed channels) should follow the backbone.

Name

gtf_hybridmerge_gffcompare follows the spec's "name by purpose" branch (the subworkflow has conditional logic - the optional blacklist intersect) plus the dominant tool. The compound verb "hybridmerge" matches the subsampledepth/markduplicates shape used by existing subworkflows; "build" and "annotation" were dropped from an earlier draft as redundant (every subworkflow produces output; a GTF is an annotation). Happy to revisit if the reviewer prefers a different form.

Components

• gffcompare (existing)
• gawk (existing, aliased as GAWK_FILTER and GAWK_CONCAT)
• bedtools/intersect (existing)

No new modules are introduced. The two gawk programs (class-code filter and backbone-plus-novel concat) are buffer-then-emit so the order of transcript / exon rows in their inputs doesn't matter; the awk source lives in awk/{filter,concat}.awk next to the subworkflow main.nf and is passed to GAWK via the program_file input (${moduleDir}/awk/..., so the subworkflow stays location-independent). Consumers includeConfig the bundled nextflow.config or pass it with -c for the prefix / suffix / closure-form args.

Caller-policy bits

The bundled config sets ext.args = '-v' on BEDTOOLS_INTERSECT so the channel name ch_blacklist_bed actually subtracts. Consumers that want strand-aware subtraction (-v -s) or positive overlap can override in their own modules.config.

The class-codes value flows through the subworkflow's val_class_codes take onto meta.class_codes and is read at task launch via a closure-form ext.args on GAWK_FILTER. The key is dropped from meta before the hybrid_gtf is emitted (carried by the backbone-meta swap at the concat step) so the value cannot leak downstream and break consumer joins.

Scope

Input format: standard GTF2 with gene_id / transcript_id attributes and gene / transcript feature types. GFF3 dialects and prokaryotic GTFs without transcript rows are out of scope. Surveyed nf-core/rnaseq's issue queue around attribute / feature-type edge cases: the only recurring concern is prokaryotic annotations, which don't apply to hybrid-transcriptome building. Parameterising attribute / feature-type names would add surface area for no real-world benefit in the consumers that need this subworkflow.

Resource sizing: GAWK steps run under process_single and hold the full input in awk arrays. Fine for annotation-scale GTFs; consumers feeding >~500 MB GTFs should override memory / cpus directly via withName.

Test plan

• nf-test test subworkflows/nf-core/gtf_hybridmerge_gffcompare/tests/main.nf.test --profile docker passes locally (2 tests covering both the no-blacklist passthrough branch and the with-blacklist intersect branch).
• nf-core subworkflows lint gtf_hybridmerge_gffcompare clean (28 passed, 0 warned, 0 failed).
• pre-commit run clean.
• CI green.

Tests use existing nf-core/test-datasets:modules fixtures: chr21_gencode.gtf as reference + backbone, genome.gtf (chr22 subset) as the novel input, genome.blacklist_intervals.bed (chr22) as the blacklist. The cross-contig setup gives every chr22 novel transcript a class_code "u" against the chr21 reference, exercising the class-code filter, the blacklist subtraction, and the synth-gene-row code path in one chain. No new test fixtures required.

Beyond the snapshot, the tests assert:

• every non-comment line in the hybrid GTF carries a well-formed gene_id "..." attribute (catches gawk/Groovy string-escaping regressions),
• the hybrid_gtf meta equals the backbone meta exactly (catches both meta-source mistakes and key-leakage),
• at least one synthesised gene row appears on the novel contig (confirms the synth code path actually fired),
• every synthesised gene row's span equals the min(start) / max(end) of its child transcripts (catches a regression to first-transcript coords).

🤖 Generated with Claude Code

[jonasscheid]

LGTM, good idea with outsourcing the awk programms