Repository navigation
Nextflow Transcript Level Analysis Workflow
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.
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;
-
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 byFASTQC_POSTandRSEM, 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
-
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 rsemunder 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 oneCOUNTS_PCAandEDGERconsume. 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.
-
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 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.
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.
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/transcript_level_analysis/transcript_level_analysis.nf --dump_configThis 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 \
-resumeNo 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_configThe 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 \
-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_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
-
Nextflow
-
Snakemake