Skip to content

Nextflow Gene Level Analysis Workflow

rlopez edited this page Jul 31, 2026 · 2 revisions

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

This workflow determines which genes change expression between the experimental conditions of a short-read RNA-Seq experiment. It assumes single-end or paired-end sequencing reads, a reference genome FASTA and a matching GTF/GFF annotation, and quantifies expression over whole annotated features rather than individual isoforms. The pipeline orchestrates the OmicsBox short-read transcriptomics chain end to end — read quality assessment, adapter and quality trimming, spliced alignment to the reference genome with STAR, gene-level read counting with HTSeq, 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 genome<br/>FASTA"/]:::input
    IN5[/"Genome annotation<br/>GTF or GFF"/]:::input
    IN6[/"Experimental design"/]:::input

    %% ---- Processes ----
    P01["FASTQC_RAW"]:::chart
    P02["TRIMMOMATIC"]:::omicsbox
    P03["FASTQC_POST"]:::chart
    P04["STAR"]:::omicsbox
    P05["HTSEQ"]:::omicsbox
    P06["COUNTS_PCA"]:::chart
    P07["EDGER"]:::omicsbox

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

    P02 --> P03
    P02 --> P04

    IN4 --> P04
    IN5 --> P04
    IN5 --> P05

    P04 --> P05

    P05 --> P06
    P05 --> P07
    IN6 --> P06
    IN6 --> P07

    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. Emits the trimmed reads consumed by FASTQC_POST and STAR, 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.
  • STAR — Aligns the trimmed reads to the reference genome with omicsbox star-aligner, using the annotation to build a splice-junction database when the configuration enables it. Emits the coordinate-sorted alignments consumed by HTSEQ together with an alignment report and its charts; splice-junction coordinates and unmapped reads are published as well when those options are switched on.
  • HTSEQ — Counts the aligned reads against the annotation with omicsbox htseq, assigning each read to a feature according to the configured feature type, ID attribute, strand specificity, overlap-resolution mode and minimum mapping quality. Emits the gene-level count table consumed by both COUNTS_PCA and EDGER, plus a quantification report.
    • 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 genes and normalising library sizes as configured. Emits the pairwise differential expression results and a report.

Inputs

A run needs reads, a reference genome, its annotation and an experimental design file. Setting both read parameters, or neither, aborts the run before any OmicsBox job is launched. The three remaining file inputs are optional and are only consulted by the quality-control and trimming steps.

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 / .fsa / .fa / .fna / .fas, plain or .gz) ✅ Reference genome sequence that STAR aligns against. Must describe the same assembly as input_gff.
input_gff GTF / GFF (.gtf / .gff / .gff2 / .gff3) ✅ Annotation of the reference genome. STAR reads it to build the splice-junction database and HTSEQ to assign reads to features, so it has to carry the feature type and ID attribute those steps are configured to count 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.
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 HTSEQ 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/gene_level_analysis/gene_level_analysis.nf --dump_config

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

Step 2 — Customise it

Open the generated gene_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/gene_level_analysis/gene_level_analysis.nf \
    -c gene_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/gene_level_analysis/gene_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 gene_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/gene_level_analysis/gene_level_analysis.nf \
    -c gene_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_star/           # Genome alignments, the alignment report and its charts
    ├── 05_htseq/          # Gene-level count table and the quantification report
    ├── 06_counts_pca/     # Sample-distance statistics chart
    └── 07_edger/          # Differential expression results and the edgeR report

Clone this wiki locally