Skip to content

Nextflow Functional Annotation Workflow

rlopez edited this page Jul 31, 2026 · 2 revisions

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

This workflow assigns biological meaning to an unannotated set of sequences: given a multi-FASTA file of transcripts, CDS or proteins, it determines which Gene Ontology terms, protein domains, orthology groups and enzyme codes describe each sequence. It combines three independent lines of evidence — sequence homology against a curated protein database, protein signature detection, and orthology-based transfer — then reconciles them into a single curated annotation set. The pipeline orchestrates the OmicsBox BLAST2GO annotation suite end to end, from loading the sequences into an OmicsBox project through DIAMOND BLAST, GO mapping and annotation, InterProScan, EggNOG-Mapper, annotation validation, EC code mapping and GO-Slim reduction, to the final charts, GO graphs and gene-set exports.


Workflow Architecture

flowchart TD
    %% ---- Inputs ----
    IN1[/"Multi-FASTA sequences"/]:::input
    IN2[/"Custom GO-Slim<br/>OBO file"/]:::input

    %% ---- Processes ----
    P01["LOAD_FASTA"]:::omicsbox
    P02["DIAMOND_BLAST"]:::omicsbox
    P02C["BLAST_CHARTS"]:::chart
    P03["GO_MAPPING"]:::omicsbox
    P03C["GO_MAPPING_CHARTS"]:::chart
    P04["GO_ANNOTATION"]:::omicsbox
    P04C["BLAST2GO_ANNOTATION_<br/>CHARTS"]:::chart
    P05["INTERPROSCAN"]:::omicsbox
    P05C["IPS_CHARTS"]:::chart
    P06["EGGNOG_MAPPER"]:::omicsbox
    P07["COMBINE_PROJECTS"]:::omicsbox
    P08["MERGE_IPS_GOS_<br/>TO_ANNOTATION"]:::omicsbox
    P09["MERGE_EGGNOG_5_GOS"]:::omicsbox
    P10["VALIDATE_GO_<br/>ANNOTATION"]:::omicsbox
    P11["EC_CODE_MAPPING"]:::omicsbox
    P12A["FINAL_ANNOTATION_<br/>CHARTS"]:::chart
    P12P["PROJECT_CHARTS"]:::chart
    P12B["COMBINED_GO_GRAPH"]:::chart
    P12C["EXPORT_GENE_SETS"]:::omicsbox
    P13["GO_SLIM"]:::omicsbox
    P13C["GOSLIM_ANNOTATION_<br/>CHARTS"]:::chart

    %% ---- Data flow ----
    IN1 --> P01
    IN1 --> P06
    IN2 -.-> P13

    P01 --> P02
    P01 --> P05

    P02 --> P02C
    P02 --> P03
    P03 --> P03C
    P03 --> P04

    P04 --> P04C
    P04 --> P07

    P05 --> P05C
    P05 --> P07

    P07 --> P08 --> P09
    P06 --> P09

    P09 --> P10 --> P11

    P11 --> P12A
    P11 --> P12P
    P11 --> P12B
    P11 --> P12C
    P11 --> P13
    P13 --> P13C

    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

  • LOAD_FASTA — Imports the input multi-FASTA into a new OmicsBox sequence project via omicsbox load-sequences, applying the duplicate-ID and header-description policies set in the configuration. Emits the sequence project consumed by both DIAMOND_BLAST and INTERPROSCAN.
  • DIAMOND_BLAST — Runs a DIAMOND homology search against the configured protein database with omicsbox diamond, producing the BLAST hits that seed GO mapping. Emits the project carrying the hit tables.
    • BLAST_CHARTS — Generates the BLAST statistics charts enabled in the configuration with omicsbox statistics-blast.
  • GO_MAPPING — Retrieves candidate GO terms for every BLAST hit from the GOA database with omicsbox mapping-cloud. Emits the project with the mapping evidence attached.
    • GO_MAPPING_CHARTS — Generates the GO-mapping statistics charts enabled in the configuration with omicsbox statistics-mapping.
  • GO_ANNOTATION — Applies the BLAST2GO algorithm through omicsbox annotation, turning the candidate mappings into a functional annotation according to the configured annotation cut-off, GO weight and per-evidence-code reliability weights. Emits the first annotated project.
    • BLAST2GO_ANNOTATION_CHARTS — Generates the annotation statistics charts enabled in the configuration with omicsbox statistics-annotation.
  • INTERPROSCAN — Scans the loaded sequences against the InterPro member databases selected in the configuration with omicsbox ips, adding protein families, domains, sites and repeats. Emits the annotated project together with the raw InterProScan results in the configured export formats.
    • IPS_CHARTS — Generates the InterPro statistics charts enabled in the configuration with omicsbox statistics-interpro.
  • EGGNOG_MAPPER — Independently annotates the raw FASTA by orthology with omicsbox eggnog-mapper, bypassing the OmicsBox project entirely. Emits an annotation project and a run report; the annotation project is not consumed until MERGE_EGGNOG_5_GOS.
  • COMBINE_PROJECTS — Merges the BLAST2GO-annotated project and the InterProScan project into a single project with omicsbox combine-projects, following the per-data-type merge policies and the priority project set in the configuration.
  • MERGE_IPS_GOS_TO_ANNOTATION — Promotes the InterPro-derived GO terms into the functional annotation with omicsbox interproscan-join. Emits the integrated project and a merge-results chart.
  • MERGE_EGGNOG_5_GOS — Folds the EggNOG-Mapper orthology annotations into the same project with omicsbox merge-emapper5-annotations, subject to the configured alignment filters. Emits the unified three-evidence annotation and a merge-results chart.
  • VALIDATE_GO_ANNOTATION — Enforces the GO True-Path Rule over the merged annotation with omicsbox annotation-validate, removing terms whose ancestors are absent.
  • EC_CODE_MAPPING — Derives Enzyme Commission codes from the validated GO terms with omicsbox enzymecode. Emits the fully annotated master project that every reporting step consumes.
  • FINAL_ANNOTATION_CHARTS — Re-runs omicsbox statistics-annotation on the master project, so the annotation statistics reflect all three evidence lines and the EC codes.
  • PROJECT_CHARTS — Summarises the master project as a whole with omicsbox statistics-project, covering project-level distributions such as data content, analysis progress and sequence length. Because it consumes the EC-mapped project, its overview spans every evidence type the pipeline produced.
  • COMBINED_GO_GRAPH — Renders the directed acyclic GO graph for the ontology categories selected in the configuration with omicsbox graph-combined-make.
  • EXPORT_GENE_SETS — Writes the annotation out as gene sets with omicsbox export-genesets, ready for downstream enrichment analysis.
  • GO_SLIM — Reduces the annotation to a GO-Slim subset with omicsbox goslim, using either a built-in web subset or a user-supplied OBO file, as selected in the configuration.
    • GOSLIM_ANNOTATION_CHARTS — Re-uses the annotation statistics module on the GO-Slim project so the reduced annotation can be compared against the full one.

Inputs

The workflow takes a single multi-FASTA file. The remaining file input is optional and only comes into play for one step; every other setting is a value rather than a file and is documented inline in the configuration file.

Parameter Format Required Description
input_fasta FASTA (.fasta / .fa / .faa / .fsa / .ffn / .fnn / .fna / .txt) ✅ Multi-FASTA of the sequences to annotate — assembled transcripts, CDS or proteins. Sequence IDs and header descriptions are imported according to the LOAD_FASTA policies set in the configuration.
goslim.obo_file OBO (.obo) ⬜ Custom GO-Slim ontology subset, consumed by the GO_SLIM step. Consulted only when that step is configured to use a custom OBO file instead of a built-in web subset.

Note

The sequence type has to be consistent with the settings of the steps that read it: the DIAMOND_BLAST BLAST mode and the EGGNOG_MAPPER input type must both match nucleotide or protein input. Check both before launching a run.


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

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

Step 2 — Customise it

Open the generated functional_annotation.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/functional_annotation/functional_annotation.nf \
    -c functional_annotation.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/functional_annotation/functional_annotation.nf \
    --dump_config

The template is written to your current directory exactly as in Option A.

Step 2 — Customise it

Edit the generated functional_annotation.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/functional_annotation/functional_annotation.nf \
    -c functional_annotation.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_load_fasta/                  # Sequence project loaded from the input FASTA
    ├── 02_diamond_blast/               # Project with the DIAMOND BLAST hits
    ├── 02_blast_charts/                # BLAST statistics charts
    ├── 03_go_mapping/                  # Project with the candidate GO mappings
    ├── 03_go_mapping_charts/           # GO-mapping statistics charts
    ├── 04_go_annotation/               # BLAST2GO-annotated project
    ├── 04_blast2go_annotation_charts/  # Annotation statistics charts
    ├── 05_interproscan/                # Project with the InterPro signatures, plus the raw exports
    ├── 05_ips_charts/                  # InterPro statistics charts
    ├── 06_eggnog_mapper/               # EggNOG orthology annotations and the run report
    ├── 07_combine_projects/            # BLAST2GO project merged with InterProScan
    ├── 08_merge_ips/                   # InterPro GO terms merged into the annotation
    ├── 09_merge_eggnog/                # EggNOG GO terms merged into the annotation
    ├── 10_validate_go/                 # True-Path-Rule validated annotation
    ├── 11_ec_code_mapping/             # Fully annotated master project with EC codes
    ├── 12_final_annotation_charts/     # Annotation statistics charts of the master project
    ├── 12_project_charts/              # Project-level statistics charts
    ├── 12_combined_go_graph/           # Combined GO graph figures
    ├── 12_export_genesets/             # Exported gene sets
    ├── 13_go_slim/                     # GO-Slim reduced annotation project
    └── 13_goslim_charts/               # Annotation statistics charts of the GO-Slim project

Clone this wiki locally