Repository navigation
Nextflow Metagenomics Analysis Workflow
Engine:
Nextflow· Workflow ID:metagenomics_analysis· Path in repo:nextflow/workflows/metagenomics_analysis/
This workflow characterises the gene content and the biological functions encoded by a mixed microbial community, starting from raw short-read shotgun sequencing of the whole sample: no isolate, no reference genome, and no prior knowledge of which organisms are present. It assumes Illumina-style shotgun metagenomic reads, single-end or paired-end, and covers the whole chain in one run — read quality control and preprocessing, removal of host and other contaminant reads, de novo assembly of the community, gene prediction on the resulting contigs, and functional annotation of the predicted genes along two independent lines of evidence. The pipeline orchestrates the OmicsBox metagenomics suite, from FastQC and Trimmomatic through contaminant removal, MEGAHIT and Prodigal, to Pfam-Scan domain annotation and EggNOG-mapper ortholog-based functional annotation.
flowchart TD
%% ---- Inputs ----
IN1[/"Short reads FASTQ"/]:::input
IN2[/"Adapter and<br/>contaminant FASTA"/]:::input
IN3[/"Trimming adapter<br/>FASTA"/]:::input
IN4[/"Target genome FASTA"/]:::input
%% ---- Processes, declared in execution order ----
P01["FASTQC_RAW"]:::chart
P02["TRIMMOMATIC"]:::omicsbox
P03["FASTQC_POST"]:::chart
P04["CONT_REM"]:::omicsbox
P05["MEGAHIT"]:::omicsbox
P06["PRODIGAL"]:::omicsbox
P07["PFAM_SCAN"]:::omicsbox
P08["EGGNOG_MAPPER"]:::omicsbox
%% ---- Data flow ----
IN1 --> P01
IN1 --> P02
IN2 -.-> P01
IN2 -.-> P03
IN3 -.-> P02
IN4 -.-> P04
P02 --> P03
P02 --> P04
P04 --> P05
P05 --> P06
P06 --> P07
P06 --> P08
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 the user-supplied adapter and contaminant lists when those files are provided. Its report is terminal — no later step consumes it — and serves as the baseline the post-trimming run is compared against. -
TRIMMOMATIC — Preprocesses the reads with
omicsbox trimmomatic, applying the adapter removal, edge trimming, quality trimming and quality/length 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_POSTandCONT_REM, along with a trimming report and, for paired-end runs, the reads whose mate did not survive filtering.-
FASTQC_POST — Re-runs
omicsbox fastqcon the trimmed reads, so the effect of the preprocessing can be read against the raw baseline before the assembly is attempted.
-
FASTQC_POST — Re-runs
-
CONT_REM — Aligns the trimmed reads against a contaminant reference with
omicsbox cont-remand partitions them by whether they map to it, which is how host and other known non-target DNA is taken out of the library before assembly. The reference is either one of the built-in indexes or an index built from a user-supplied genome, according to the configured target index. Emits the contaminant-free reads consumed byMEGAHITand, when the configured result mode retains them, the reads that did align, together with a decontamination report and its charts. -
MEGAHIT — Assembles the decontaminated reads de novo with
omicsbox megahit, building a succinct de Bruijn graph over the configured range of k-mer sizes under the configured graph simplification and contig filtering settings. All read files are handed to a single job, so the whole community is co-assembled rather than assembled sample by sample. Emits the contigs consumed byPRODIGAL, plus an assembly report and a contiguity chart. -
PRODIGAL — Predicts protein-coding genes directly on the assembled contigs with
omicsbox prodigal, under the configured procedure, translation table and gene-model settings. The procedure setting is what adapts the prediction to a metagenomic assembly, where the contigs come from many different organisms rather than from one genome. Emits the predicted gene sequences consumed by bothPFAM_SCANandEGGNOG_MAPPER, together with the predicted proteins, the gene coordinates, a report and its distribution charts. -
PFAM_SCAN — Annotates the predicted genes against the Pfam database with
omicsbox pfam-scan, assigning the protein families and domains they contain. Emits the domain annotation project and its report; its results are terminal. -
EGGNOG_MAPPER — Annotates the same predicted genes with
omicsbox eggnog-mapper, transferring function from precomputed EggNOG orthology groups according to the configured input sequence type, taxonomic scope, ortholog selection, GO evidence filter and search threshold. Emits the annotated project and its report; its results are terminal.PFAM_SCANandEGGNOG_MAPPERare independent branches over the same input and neither consumes the other.
A run needs only the sequencing reads of the community to analyse. Setting both read parameters, or neither, aborts the run before any OmicsBox job is launched. Every other file input is optional and is read only by the step that consumes it.
| Parameter | Format | Required | Description |
|---|---|---|---|
input_single_end / input_paired_end
|
FASTQ (.fastq / .fq / .fastq.gz / .fq.gz) |
✅ | Glob matching the shotgun read files of the 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. |
fastqc.adapters |
FASTA (.fasta / .fsa / .fa / .fna / .fas) |
⬜ | Named adapter sequences screened for by FASTQC_RAW and FASTQC_POST, replacing the built-in adapter list. Supplying the file enables adapter screening in those steps. |
fastqc.contaminants |
FASTA (.fasta / .fsa / .fa / .fna / .fas) |
⬜ | Named contaminant sequences the overrepresented-sequence check is screened against, consumed by both FASTQC_RAW and FASTQC_POST, replacing the built-in contaminant list. |
trimmomatic.adapters |
FASTA (.fasta / .fa / .faa / .fsa / .ffn / .fnn / .fna / .txt) |
⬜ | Custom adapter and contaminant sequences to clip in TRIMMOMATIC, used instead of one of the built-in adapter lists and read only when that step is configured to remove adapters. For paired-end palindrome clipping the sequence names have to be matched pairs ending in /1 and /2. |
cont_rem.target_genome |
FASTA (.fasta / .fa / .fn / .fna / .fasta.gz / .fa.gz) |
⬜ | Genome of the contaminant to remove, consumed by CONT_REM to build the alignment index on the fly. Read only when that step is configured to create its database from a supplied genome rather than to use one of the built-in indexes; unused otherwise. |
Note
Only the read layout is validated before any OmicsBox job is launched: exactly one of
input_paired_end and input_single_end must be set — neither both nor neither — and the run
stops immediately with an explanatory message otherwise. Three further constraints are not checked
at start-up, so a mismatch surfaces later as a failing step instead:
-
cont_rem.target_genomeand the target index setting ofCONT_REMhave to agree. Supplying the genome requires selecting the option that builds the database from it, and selecting that option without supplying the file fails the step. -
CONT_REMmust be configured to keep the reads that did not align to the contaminant reference, because those are the onesMEGAHITassembles. A result mode that discards them does not raise an error: the decontamination succeeds and the run then ends there, silently producing no assembly and no annotation. - Several
TRIMMOMATICoptions apply to paired-end input only and make OmicsBox fail if they are enabled for a single-end run. The configuration file marks every one of them inline.
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/metagenomics_analysis/metagenomics_analysis.nf --dump_configThis copies the self-documenting template to ./metagenomics_analysis.config in your current directory and exits. No OmicsBox job is launched.
Step 2 — Customise it
Open the generated metagenomics_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/metagenomics_analysis/metagenomics_analysis.nf \
-c metagenomics_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/metagenomics_analysis/metagenomics_analysis.nf \
--dump_configThe template is written to your current directory exactly as in Option A.
Step 2 — Customise it
Edit the generated metagenomics_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/metagenomics_analysis/metagenomics_analysis.nf \
-c metagenomics_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 and charts of the raw reads
├── 02_trimmomatic/ # Trimmed reads and the trimming report
├── 03_fastqc_post/ # Quality control report and charts of the trimmed reads
├── 04_contaminant_removal/ # Partitioned reads with the decontamination report and charts
├── 05_megahit/ # Assembled contigs with the assembly report and chart
├── 06_prodigal/ # Predicted genes, proteins and coordinates with the report and charts
├── 07_pfam_scan/ # Project with the Pfam domain annotations, plus the report
└── 08_eggnog_mapper/ # Project with the EggNOG functional annotation, plus the report
-
Nextflow
-
Snakemake