wf-transcriptomes-v202/docs/06_pipeline_overview.md

Background

The methodology implemented within the wf-transcriptomes workflow follows from the largest independent long-read RNA benchmark to date. The Systematic assessment of long-read RNA-seq methods for transcript identification and quantification concluded that, in well-annotated genomes, reference-based methods perform best. Our own previous research, benchmarking, and support of community members has shown that an automated, hands-off de-novo discovery pipeline to be bothersome for many use cases. The wf-transcriptomes workflow therefore focuses on a reference-guided approach rather than a novelty-first one.

The benchmark paper above explicitly recommends bambu for identifying sample-specific transcriptomes in well-annotated organisms when only limited novelty is expected. The paper also names bambu as one of the best options when quantification is important, which supports using it as the core engine for downstream DGE and DTU analyses. For method details and current implementation notes, see the bambu GitHub repository.

In spike-in evaluations, bambu generally showed high precision and was among the better F1 performers. This is an acceptable tradeoff for a production workflow where false transcript calls might be confound downstream analysis. Users interested more in novel discovery may wish to amend the parameters of the workflow away from their defaults. bambu also performed especially well on long non-spliced SIRVs, which supports its use on long-read datasets where transcript-end definition matters.

The workflow's choice of SQANTI3 as a companion QC and annotation layer matches the benchmark paper, which used SQANTI3 categories and metrics as its transcript assessment framework; so our outputs align with the field’s standard reporting language. This step is useful for structural isoform classification and provides standard QC summaries for reporting, method comparison, or deeper transcript model review. See the SQANTI3 repository and the SQANTI3 isoform classification documentation for category definitions and usage details.

1. Getting your files into the workflow

The shared EPI2ME input handling collects FASTQ or BAM inputs, works out whether you have a single sample or a multiplexed run, and produces per-sample FASTQ files plus read statistics. These files are used in the downstream report.

2. Sample sheet formulation

The sample sheet is optional for simple single-sample runs, but it allows sample aliases to be mapped to barcodes in multiplexed runs and is required for --de_analysis.

• Every row must contain barcode and alias.
• barcode must use the usual ONT-style naming such as barcode01, barcode02, and the values must be unique.
• alias is the user-facing sample name, must be unique, must not begin with the word barcode and may contain only letters, numbers, ., _ or -.
• For --de_analysis, the sheet must also contain the primary condition column (condition by default, overridable with --condition_column), plus any columns named in --covariates.

When multiplexed input folders are named by barcode, the workflow matches those folder names against the barcode column. If the folders are named by alias, the workflow can match them against alias, but the sample sheet still needs a barcode column because the shared validator expects it.

Example sample sheets:

Example sample sheet for a simple multiplexed analysis

This example contains the minimal barcode and alias columns:

barcode,alias
barcode01,rep1
barcode02,rep2
barcode03,rep3
barcode04,rep4

Example sample sheet for a differential expression analysis

This example is suitable for a multiplexed run and also satisfies the minimum requirements for a two-group DE/DTU comparison; containing the barcode, alias and condition columns.

barcode,alias,condition
barcode01,control_rep1,control
barcode02,control_rep2,control
barcode03,control_rep3,control
barcode04,treated_rep1,treated
barcode05,treated_rep2,treated
barcode06,treated_rep3,treated

Additional columns to use as contrast facets may be named with the --covariates parameter.

3. Genome alignment

Each sample is aligned to the supplied reference genome with minimap2 in a splice aware mode, then sorted and indexed with samtools. The aligned BAMs under samples/<alias>/alignment/ are the main alignment files used for transcriptome analysis, SQANTI3 QC, and optional IGV viewing.

4. Optional modified base summarisation

When aligned BAMs contain modified base tags (MM and ML), the workflow also runs modkit on each sample alignment. It first checks which modified base codes are present in the BAM, then runs modkit pileup to produce a per-sample bedMethyl file, a simple per-sample summary table, and one bigWig track per requested or inferred modification under samples/<alias>/mods/.

If --mod_codes is set, those codes are passed directly to modkit pileup. If it is omitted, the workflow infers the available primary_base:mod_code pairs from the aligned BAM with modkit modbam check-tags. These outputs are also included in the optional IGV configuration when --igv is enabled.

5. Cohort transcriptome construction

All aligned samples are analysed together with bambu to produce the primary cohort transcriptome, transcript counts, gene counts, and the RDS objects used for downstream differential analysis. This shared model is the main cohort-level result and is published under cohort/. Before writing outputs, transcript filtering removes only transcripts with zero total transcript counts across samples; it does not use fullLengthCounts for this quantification filter.

6. Independent per-sample transcriptomes

Each sample is also processed separately with bambu so the workflow produces sample-specific GTF, FASTA, count tables, and metadata under samples/<alias>/. These per-sample outputs are useful for inspecting sample specific transcript models without changing the shared cohort transcriptome used for DE/DTU.

7. Transcript sequence generation and QC

Transcript FASTA files are derived from GTF plus genome using gffread. SQANTI3 classifies the cohort and per-sample transcriptomes and produces structural QC summaries. The cohort SQANTI3 results live under cohort/sqanti/, while per-sample SQANTI3 directories are published under samples/<alias>/sqanti/.

8. Optional DE and DTU analysis

When --de_analysis is enabled, the workflow checks the experimental design, runs DESeq2 for differential gene expression, and runs DEXSeq for differential transcript usage. These analyses use the shared bambu outputs and the design columns in the sample sheet, and each comparison is written to its own subdirectory under de_analysis/<contrast>/.

9. What you need to provide

The workflow's analysis is controlled by a user provided genome, annotation, and bambu mode.

• use --transcriptome_mode to choose between discover and fixed_annotation
• --transcriptome_source has been removed; use --transcriptome_mode instead
• both --ref_genome and --ref_annotation are required in both modes
• --ref_transcriptome has been removed; if you want annotation-based quantification, use --transcriptome_mode fixed_annotation together with --ref_genome and --ref_annotation
• when --de_analysis is enabled, the sample sheet must contain alias, the primary condition column, and any requested columns named in --covariates