Skip to content

Nextflow Transcript Level Analysis Workflow

rlopez edited this page Jul 31, 2026 · 2 revisions

Engine: Nextflow  ·  Workflow ID: transcript_level_analysis  ·  Path in repo: nextflow/workflows/transcript_level_analysis/

This workflow determines which transcripts change expression between the experimental conditions of a short-read RNA-Seq experiment, resolving expression at the level of individual isoforms rather than whole genes. It assumes single-end or paired-end sequencing reads together with a reference transcriptome FASTA — an assembled or downloaded set of transcript sequences, not a genome — and an experimental design table declaring which sample belongs to which condition. The pipeline orchestrates the OmicsBox short-read transcriptomics chain end to end: read quality assessment, adapter and quality trimming, expectation-maximisation quantification against the transcriptome with RSEM, and pairwise differential expression testing with edgeR, alongside a principal-component view of the sample distances in the resulting count table.


Workflow Architecture

flowchart TD
    %% ---- Inputs ----
    IN1[/"FASTQ reads"/]:::input
    IN2[/"QC adapters and<br/>contaminants"/]:::input
    IN3[/"Trimming adapters"/]:::input
    IN4[/"Reference<br/>transcriptome FASTA"/]:::input
    IN5[/"Transcript-to-gene<br/>map"/]:::input
    IN6[/"Experimental design"/]:::input

    %% ---- Processes, declared in execution order ----
    P01["FASTQC_RAW"]:::chart
    P02["TRIMMOMATIC"]:::omicsbox
    P03["FASTQC_POST"]:::chart
    P04["RSEM"]:::omicsbox
    P05["COUNTS_PCA"]:::chart
    P06["EDGER"]:::omicsbox

    %% ---- Data flow ----
    IN1 --> P01
    IN1 --> P02
    IN2 -.-> P01
    IN2 -.-> P03
    IN3 -.-> P02

    P02 --> P03
    P02 --> P04

    IN4 --> P04
    IN5 -.-> P04

    P04 --> P05
    P04 --> P06
    IN6 --> P05
    IN6 --> P06

    classDef input fill:#e8f4fd,stroke:#1f77b4,stroke-width:1px;
    classDef omicsbox fill:#fff3e0,stroke:#e67e22,stroke-width:1px;
    classDef chart fill:#f4ecf7,stroke:#8e44ad,stroke-width:1px;
Loading

Pipeline Steps

  • FASTQC_RAW — Assesses the quality of the untrimmed reads with omicsbox fastqc, screening them against user-supplied adapter and contaminant sequences when those files are provided. Its report is a standalone diagnostic: no later step consumes it, so it can be inspected while the rest of the pipeline is still running.
  • TRIMMOMATIC — Cleans the raw reads with omicsbox trimmomatic, applying the adapter-removal, edge-trimming, quality-trimming and read-filtering stages enabled in the configuration. For paired-end input it pairs mates by the configured upstream and downstream filename patterns. Emits the trimmed reads consumed by FASTQC_POST and RSEM, a trimming report, and — for paired-end input — the reads whose mate was discarded, kept apart in their own subfolder.
    • FASTQC_POST — Re-runs omicsbox fastqc on the trimmed reads so the effect of trimming can be compared against FASTQC_RAW. Like the raw-read assessment, it is a standalone diagnostic.
  • RSEM — Quantifies expression by aligning the trimmed reads against the reference transcriptome and distributing multi-mapping reads over the isoforms they are compatible with, using omicsbox rsem under the configured strand specificity, read-start-position and fragment-length settings. Emits the transcript-level count table and a quantification report; when the workflow is configured for gene-level analysis it additionally sums each gene's isoform estimates into a gene-level table, grouping them by the supplied transcript-to-gene map. Whichever of the two tables matches the configured level is the one COUNTS_PCA and EDGER consume. The per-sample read alignments against the transcript sequences are published as well when that option is enabled.
    • COUNTS_PCA — Projects the samples of the count table onto their principal components with omicsbox counts-pca, colouring them by the experimental factors of the design file when the step is configured to do so. Produces the sample-distance chart in the configured chart format.
  • EDGER — Tests for differential expression between the conditions declared in the experimental design with omicsbox edger, after discarding low-count features and normalising library sizes as configured, and applying the configured design type and statistical test. Emits the pairwise differential expression results and a report.

Inputs

A run needs reads, a reference transcriptome and an experimental design file. Setting both read parameters, or neither, aborts the run before any OmicsBox job is launched. The four remaining file inputs are optional and are only consulted by the steps that read them.

Parameter Format Required Description
input_single_end / input_paired_end FASTQ (.fastq / .fq / .fastq.gz / .fq.gz) ✅ Glob matching the read files of every sample — set exactly one of the two, whichever matches the library layout. Paired-end mates are paired by filename, so those files must follow one consistent convention, declared through the upstream_pattern and downstream_pattern settings.
input_fasta FASTA (.fasta / .fa / .fna / .ffn, plain or .gz) ✅ Reference transcriptome that RSEM quantifies against — one sequence per transcript, not a genome assembly. Its sequence identifiers are the features the count table and the differential expression results are keyed on.
experimental_design Tab-delimited text (.txt) ✅ Sample-to-factor table read by COUNTS_PCA and EDGER. Its column headers have to match the experimental factors named in those two steps' configuration.
rsem.gene_trans_map Tab-delimited text (.txt) ⬜ Mapping from each transcript to the gene it belongs to, one gene id / transcript id pair per line. RSEM groups isoform estimates by it, so it is read only when the workflow is configured for gene-level analysis — and it is mandatory there, the run stopping at start-up without it.
trimmomatic.adapters FASTA (.fasta / .fa / .faa / .fsa / .ffn / .fnn / .fna / .txt) ⬜ Custom adapter sequences for TRIMMOMATIC, relevant when that step is configured to remove adapters from a custom list rather than a built-in one.
fastqc.adapters FASTA (.fasta / .fsa / .fa / .fna / .fas) ⬜ Custom adapter sequences to screen for, consumed by both FASTQC_RAW and FASTQC_POST. Supplying the file enables adapter screening in those steps.
fastqc.contaminants FASTA (.fasta / .fsa / .fa / .fna / .fas) ⬜ Custom contaminant sequences to screen for, consumed by both FASTQC_RAW and FASTQC_POST. Supplying the file enables contaminant screening in those steps.

Experimental design file format

Sample	Condition
sample1	Control
sample2	Control
sample3	Treatment
sample4	Treatment

Note

The sample identifiers in the design file are what tie the differential expression analysis back to the reads: the sample names in the count table RSEM produces are derived from the read filenames, and EDGER matches the design table against them. Any TRIMMOMATIC option that renames the trimmed read files — an output prefix, for instance — therefore has to be reflected in the design file too, or the differential expression step fails.


Configuration

This workflow follows the repository's self-documenting configuration strategy: you do not need to memorise parameter names, consult a reference table, or learn the OmicsBox CLI syntax. Every customisable option is already declared, grouped, and documented with inline comments inside the workflow's own configuration file.

To configure a run:

  1. Generate your own copy of the configuration file — Step 1 of Execution below.
  2. Open it in any text editor and read the inline comments; each option lists its accepted values and its default.
  3. Fill in the values you need and comment / uncomment the flags you want to enable or disable.
  4. Leave everything else untouched — the entries you do not change fall back to the tested defaults.

Tip

Keep your customised configuration file next to your project data and under version control. It is a complete, human-readable record of how a run was parameterised, which is all you need to reproduce it later.


Execution

Before running this workflow for the first time, complete the environment setup described on the central Nextflow Execution & Configuration page.

Two ways to run this workflow are supported. Option A is recommended when you want to inspect or modify the pipeline code; Option B runs the published version straight from GitHub with no manual clone.

Option A — Local Clone

Assuming you have already cloned the repository and navigated to its root directory:

Step 1 — Dump the configuration file

nextflow run nextflow/workflows/transcript_level_analysis/transcript_level_analysis.nf --dump_config

This copies the self-documenting template to ./transcript_level_analysis.config in your current directory and exits. No OmicsBox job is launched.

Step 2 — Customise it

Open the generated transcript_level_analysis.config and edit it as described in Configuration: set your input paths and output folder, then fill in or comment/uncomment the step-specific flags you want to change. Save the file.

Step 3 — Run the workflow

nextflow run nextflow/workflows/transcript_level_analysis/transcript_level_analysis.nf \
    -c transcript_level_analysis.config \
    -resume

Option B — Directly from GitHub

No clone required — the engine fetches the workflow for you.

Step 1 — Dump the configuration file

nextflow run BioBam/omicsbox-engine-workflows \
    -r main \
    -main-script nextflow/workflows/transcript_level_analysis/transcript_level_analysis.nf \
    --dump_config

The template is written to your current directory exactly as in Option A.

Step 2 — Customise it

Edit the generated transcript_level_analysis.config exactly as in Option A — see Configuration. Since the pipeline code lives remotely, this file is the only thing you own and edit.

Step 3 — Run the workflow

nextflow run BioBam/omicsbox-engine-workflows \
    -r main \
    -main-script nextflow/workflows/transcript_level_analysis/transcript_level_analysis.nf \
    -c transcript_level_analysis.config \
    -resume

Outputs

All results are written under the output directory set in your configuration file (local_folder), inside a subfolder named after the Nextflow session ID of the run. Each step publishes to its own numbered directory, so every file can be traced back to the process that produced it:

results/
└── <session-id>/
    ├── 01_fastqc_raw/     # Quality-control report of the raw reads
    ├── 02_trimmomatic/    # Trimmed reads and the trimming report
    │   └── unpaired/      # Reads that lost their mate during trimming, paired-end runs only
    ├── 03_fastqc_post/    # Quality-control report of the trimmed reads
    ├── 04_rsem/           # Count tables, the quantification report and the read alignments
    ├── 05_counts_pca/     # Sample-distance statistics chart
    └── 06_edger/          # Differential expression results and the edgeR report

Clone this wiki locally