MetaflowX User Manual

MetaflowX is a scalable and modular metagenomics analysis pipeline powered by Nextflow. It supports both short-read and contig-based inputs and automates key analyses such as taxonomic profiling, functional annotation, gene catalog construction, and MAG recovery.

Contents

• 1. Pipeline Summary
• 2. Getting Started
  • 2.1 Quick Start
  • 2.2 Prerequisites
  • 2.3 Installation
  • 2.4 Environment & Database Check
• 3. How to Run
  • 3.1 Basic Usage
  • 3.2 Advanced Usage
• 4. Output
• 5. Support
• 6. Credits
• 7. Citations

1. Pipeline Summary

The MetaflowX pipeline consists of the following steps:

1. Quality control ( fastp Trimmomatic Bowtie2)
2. Contig assembly ( SPAdes MEGAHIT )
3. Microbial taxonomy and metabolic function analysis ( MetaPhlAn HUMAnN Kraken2 )
4. Gene catalog construction ( Prodigal CD-HIT eggNOG-mapper antiSMASH BiG-MAP )
5. MAG binning and evaluation ( MetaBAT2 CONCOCT SemiBin2 MaxBin2 MetaBinner COMEBin binny MetaDecoder Vamb DAS_Tool MAGScoT Checkm2 dRep Galah GTDB-Tk CoverM Deepurify COBRA )
6. Report generation ( Jinja MultiQC )

For module-level details, see Module Description.

2. Getting Started

2.1 Quick Start

If Nextflow is already installed, you can quickly validate MetaflowX using demo tests:

1. Clone the repository:

bash git clone https://github.com/01life/MetaflowX.git

2. Run either of the following tests:

1️⃣ Test 1: Full pipeline dry run using stub mode (no Docker or Conda required)

This test runs the full pipeline structure with small input and stubbed commands (logic is tested, but real computation is skipped).

It requires only Nextflow, no Docker or Conda.

bash nextflow run MetaflowX -stub -profile test_stub --outdir stub_remote

2️⃣ Test 2: Run a single module (nf-core/fastp only, requires Docker)

This test runs the built-in nf-core/fastp module with a demo input. It requires Docker.

bash nextflow run MetaflowX -profile test --outdir remote

💡 Both tests finish in a few minutes and produce logs and outputs under the specified --outdir.

[!NOTE] If you want to run the Nextflow pipeline in the background, you can add the -bg option:

bash nextflow run -bg MetaflowX -profile test --outdir remote > remote.out

⚠️ These are functional tests only, not for biological analysis.

2.2 Prerequisites

We recommend preparing all software environments and databases in advance:

• See Environment Guide for setting up Conda and required tools.
• See Database Guide for downloading and configuring necessary reference data.

2.3 Installation

1. Clone the repository: bash git clone https://github.com/01life/MetaflowX.git

2.4 Environment & Database Check

[!NOTE] If you are new to Nextflow and nf-core, check the Nextflow installation guide. Ensure your setup passes the -profile test before processing real data.

After installation, validate your full environment using built-in paired-end test data under test/data/:

• Sample1_R1.fq.gz, Sample1_R2.fq.gz
• Sample2_R1.fq.gz, Sample2_R2.fq.gz

First, prepare an input file samplesheet.csv (see Basic Usage), then run:

bash nextflow run MetaflowX \ -profile <docker/singularity/conda/.../institute> \ --input samplesheet.csv \ --outdir full_test

This run will:

• Check tool availability
• Verify database paths
• Execute major pipeline steps

[!IMPORTANT] ⚠️ Before running, ensure that the following configuration files are properly set:

• nextflow.config: general defaults, database paths
• conf/modules.config: tool environments and options
• conf/base.config: compute resources (CPU, memory)

✅ Match the -profile flag to your local compute environment.

💡 You can use -profile slurm, -profile docker, -profile local, etc.

⏱️ This test may take several minutes depending on system specs.

3. How to run

3.1 Basic usage

1. Prepare a samplesheet samplesheet.csv with your input data that looks as follows:

csv id,raw_reads1,raw_reads2 S1,/path/to/Sample1_R1.fastq.gz,/path/to/Sample1_R2.fastq.gz S2,/path/to/Sample2_R1.fastq.gz,/path/to/Sample2_R2.fastq.gz

1. Now, you can run the pipeline using:

bash nextflow run MetaflowX \ -profile <docker/singularity/conda/.../institute> \ --input samplesheet.csv \ --outdir <OUTDIR>

[!WARNING] Please provide pipeline parameters via the CLI or Nextflow -params-file option. Custom config files including those provided by the -c Nextflow option can be used to provide any configuration except for parameters; see docs.

For more details and further functionality, please refer to the usage documentation. You can use the following command to see all the parameters of the pipeline.

bash nextflow run MetaflowX --help

[!NOTE] MetaflowX relies on plenty of tools and their databases. For detailed installation and configuration instructions, please refer to the dependencies guide, database guide and version documentation.

3.2 Advanced Usage

MetaflowX supports:

• Single-end and paired-end reads
• Selective module execution using --mode and --skip parameters
• Custom database paths and tool options

📖 For a full overview of available parameters and advanced configuration, see the Usage Guide.

📘 For practical examples of common execution modes and corresponding commands, refer to the Execution Guide.

4. Output

The results generated by MetaflowX include the following sections:

✤ Quality control - 01.CleanData/

✤ Contig assembly - 02.Contig

✤ Microbial taxonomy and metabolic function analysis - 101.MetaPhlAn
- 102.HUMAnN

✤ Gene catalog construction - 03.Geneset
- 04.GenesetProfile

✤ Automated binning analysis - 05.BinSet
- 06.BinsetProfile

✤ Report generation - 07.MultiQC - MetaflowXReport*.html

✤ Pipeline information - pipeline_info

See Output Documentation for details.

5. Support

• Visit the MetaflowX tutorial for examples and explanations.
• Check the Changelog for version history.
• Report issues via the GitHub Issues page.

6. Credits

❤️ MetaflowX was developed with support from 01Life. ️

MetaflowX is developed by:

👩‍💻 Yang Ying

👩‍💻 Liang Lifeng

With contributions and feedback from:

👨 Xie Hailiang

👨‍💻 Long Shibin

7. Citations

If you use MetaflowX in your research, please cite:

MetaflowX: A Scalable and Resource-Efficient Workflow for Multi-Strategy Metagenomic Analysis

For all third-party tools used, refer to CITATIONS.md.