Workflow schematics

Simple workflow schematics help outline the main functionality and steps of a pipeline. Most nf-core pipelines use a metro-map diagram, where each analysis route is a coloured line running through the processes it uses.

There are two ways to make one: generate it from a text file with nf-metro, or draw it by hand in a vector editor. Either way, declare the result in nextflow.config.

Declare your diagram in the pipeline config

Set manifest.diagram in nextflow.config to a relative path to your diagram, so that Nextflow and other tools can find it:

manifest {
    // ...
    diagram = 'docs/images/metro_map.svg'
}

Nextflow accepts SVG, PNG, JPEG, GIF and WebP files. Use an SVG if you can: it scales to any size and a single file can work on both light and dark backgrounds.

nf-core pipelines lint warns if manifest.diagram is not set. It fails if the value is a URL rather than a relative path, is not one of the supported image formats, or points at a file that is not in the repository.

Use nf-metro

nf-metro renders a metro map from a text file, so the diagram lives in the pipeline repo as source and can be re-rendered whenever the workflow changes.

Describe the pipeline as a Mermaid graph, with %%metro directives to declare the lines. NB: PIPELINE is a placeholder for your pipeline’s name.

%%metro title: nf-core/PIPELINE
%%metro logo: ../docs/images/nf-core-PIPELINE_logo_light.png | ../docs/images/nf-core-PIPELINE_logo_dark.png
%%metro style: dark
%%metro line: main | Main | #4CAF50
%%metro line: qc | Quality Control | #2196F3 | dashed
%%metro legend: bl

graph LR
    input[Input]
    trim[Trimming]
    fastqc[FastQC]

    input -->|main| trim
    input -->|qc| fastqc
    trim -->|qc| fastqc

Then render it and commit the SVG:

nf-metro render assets/metro_map.mmd -o docs/images/metro_map.svg

Light and dark mode

Colours in the SVG are written as CSS light-dark() pairs, so one file works on both light and dark backgrounds - there’s no need for a _light / _dark SVG pair.

However, you may want _light and _dark pairs for PNG outputs for convenience for users. You can also generate animated versions with little circles that move along the tracks.

A typical set of commands to generate these variants is as follows:

pip install 'nf-metro>=2.0.0'

# Static SVG + dark-mode PNG
nf-metro render assets/metro_map.mmd \
    -o docs/images/metro_map.svg \
    -o docs/images/metro_map_dark.png

# Static light-mode PNG
nf-metro render assets/metro_map.mmd --mode light \
    -o docs/images/metro_map_light.png

# Animated SVG
nf-metro render assets/metro_map.mmd --animate \
    -o docs/images/metro_map_animated.svg

Additional features

If you like, nf-metro can also export interactive HTML, light up stations in real time as a run progresses, and import a Nextflow -with-dag diagram as a starting point.

• Playground - edit and preview in the browser, nothing to install
• Guide - directives, lines, sections and layout options
• nf-core pipelines and gallery - rendered maps with their .mmd source
• Theming - brand palettes (nfcore is the default), light/dark handling and logos
• CI and automation - a GitHub Action that flags a committed SVG that is out of date

Draw one by hand

Prior to nf-metro, most workflow schematics were made with vector image editors, such as the open-source tool Inkscape or commercial suite Adobe Illustrator. This remains one of the best ways to generate a metro map, though it requires some patience and effort.

Useful tools for collaborative prototyping include Google Drawings and LucidChart.

The components and examples below can be opened in these editors, and various parts can be borrowed and/or modified. Components are also available on bioicons, which has direct import extensions for Inkscape and draw.io.

Components

Object	Description	Link	Source
	Components for a metro-map style pipeline workflow	SVG PDF DRAW.IO	James A. Fellows Yates, Maxime Garcia, Louis Le Nézet & nf-core; under a CC0 license (public domain)

Using draw.io

The web app draw.io helps you create, render and export different diagrams including metro-maps. For even more convenience, you can use the asset library nf-core xml item library. It contains all of the components from the components above. To open the nf-core component library:

1. Download the library file
2. Go to draw.io
3. Click File → Open Library from → Device
4. Select the downloaded the file

This will load the nf-core shapes into the sidebar without any CORS issues.

Examples

See below for examples of nf-core workflow schematics that can be re-used and modified for your own pipeline.

Select the schematic image to see the original.

Workflow Example	nf-core Pipeline	License/Publication	Suggested attribution
	nf-core/sarek	From Garcia et al. (2020, F1000 Research) under a CC-BY 4.0 license.
	nf-core/eager	From Fellows Yates et al. (2021, PeerJ) under a CC-BY 4.0 license	CC-BY 4.0. Design originally by Zandra Fagernäs
	nf-core/eager	From Fellows Yates et al. (2021, PeerJ) under a MIT license
	nf-core/dualrnaseq	By Regan Hayward under MIT license
	nf-core/circrna	By Barry Digby under MIT license
	nf-core/mag	By Sabrina Krakau under MIT license	CC-BY 4.0. Design originally by Zandra Fagernäs
	nf-core/bactmap	By Anthony Underwood under MIT license
	nf-core/cutandrun	By Chris Cheshire under MIT license
	nf-core/sarek	By Maxime U Garcia under MIT license
	nf-core/rnaseq	By Sarah Guinchard under MIT license
	nf-core/isoseq	By Sébastien Guizard under MIT license