Skip to content

Nextflow Metagenomics Analysis Workflow

rlopez edited this page Jul 31, 2026 · 2 revisions

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.


Workflow Architecture

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;
Loading

Pipeline Steps

  • 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 by FASTQC_POST and CONT_REM, along with a trimming report and, for paired-end runs, the reads whose mate did not survive filtering.
    • FASTQC_POST — Re-runs omicsbox fastqc on the trimmed reads, so the effect of the preprocessing can be read against the raw baseline before the assembly is attempted.
  • CONT_REM — Aligns the trimmed reads against a contaminant reference with omicsbox cont-rem and 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 by MEGAHIT and, 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 by PRODIGAL, 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 both PFAM_SCAN and EGGNOG_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_SCAN and EGGNOG_MAPPER are independent branches over the same input and neither consumes the other.

Inputs

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_genome and the target index setting of CONT_REM have 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_REM must be configured to keep the reads that did not align to the contaminant reference, because those are the ones MEGAHIT assembles. 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 TRIMMOMATIC options 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.

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/metagenomics_analysis/metagenomics_analysis.nf --dump_config

This 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 \
    -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/metagenomics_analysis/metagenomics_analysis.nf \
    --dump_config

The 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 \
    -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 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

Clone this wiki locally