Repository navigation
Nextflow Gene Level Analysis Workflow
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.
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;
-
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 byFASTQC_POSTandSTAR, 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 fastqcon the trimmed reads so the effect of trimming can be compared againstFASTQC_RAW. Like the raw-read assessment, it is a standalone diagnostic.
-
FASTQC_POST — Re-runs
-
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 byHTSEQtogether 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 bothCOUNTS_PCAandEDGER, 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.
-
COUNTS_PCA — Projects the samples of the count table onto their principal components with
-
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.
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.
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:
- Generate your own copy of the configuration file — Step 1 of Execution below.
- Open it in any text editor and read the inline comments; each option lists its accepted values and its default.
- Fill in the values you need and comment / uncomment the flags you want to enable or disable.
- 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.
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.
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_configThis 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 \
-resumeNo clone required — the engine fetches the workflow for you.
Step 1 — Dump the configuration file
nextflow run BioBam/omicsbox-engine-workflows \
-r develop \
-main-script nextflow/workflows/gene_level_analysis/gene_level_analysis.nf \
--dump_configThe 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 develop \
-main-script nextflow/workflows/gene_level_analysis/gene_level_analysis.nf \
-c gene_level_analysis.config \
-resumeAll 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
-
Nextflow
-
Snakemake