EasyMetagenome: a shell-driven shotgun metagenomics pipeline in four numbered scripts

Four scripts and one environment file are the whole interface

EasyMetagenome is a user-friendly and flexible pipeline for shotgun metagenomic analysis in microbiome research, and the interface is unusually direct. Instead of a workflow engine, a config file and a scheduler, the pipeline is four shell scripts and a Conda environment file, named for the order you run them in.

There is 0Install.sh for software and database installation, 1Pipeline.sh for the analysis pipeline itself, 2StatPlot.sh for statistics and visualisation, and 3Init.sh for the initial setup. There is also a 2StatPlot_mac.sh variant for macOS. The environment.yml file holds the current version operating environment, so the whole tool chain is pinned in one place.

The project identifies itself as version v1.24, updated 2025/11/26, and the last push to the master branch was on 2026-06-14. Tagged releases follow a naming pattern that encodes the year and month, with v1.24 corresponding to 2025.12, v1.21 to 2024.5 and v1.20 to 2023.11, so the release tag tells you how old a given copy of the pipeline is without opening it.

The licence is GPL-3.0, and the primary language recorded for the repository is HTML, which is a reflection of the project being a website-shaped collection of documentation and scripts rather than a conventional software package.

The analysis is organised as four stages from raw reads to genomes

The pipeline figure caption describes the whole process as a path from raw data to taxonomic and functional tables, and the README breaks it into four steps.

Step one is data preprocessing, which includes the pre-analysis preparation of installing software and databases, setting environmental variables and checking metadata and sequence files, then Fastp quality control and Kneaddata host removal. The host removal step is the one that matters for microbiome work, since a sample from a human or an animal carries host reads that distort the community profile.

Step two is read-based analysis, built on HUMAnN, MetaPhlAn4 and Kraken2. It includes preparing the HUMAnN input files, calculating species and functional composition with HUMAnN, arranging the species composition tables, functional composition analysis, GraPhlAn map drawing, LEfSe differential analysis of species, and Kraken2 with Bracken for species annotation and abundance estimation.

Step three is assembly analysis, covering assembly, gene prediction and de-redundancy and quantification, functional gene annotation, and Kraken2 gene species annotation. Step four is binning and mining of single bacterial genomes, with MetaWRAP mixed sample binning, dRep de-redundant species and strain genome sets, CoverM genome quantification, GTDB-tk species annotation and an evolutionary tree.

The structure is worth noticing for a second reason. Read-based and assembly-based analysis are separate stages, and you can stop after stage two if that is all your question needs, or go all the way to bins if you are chasing a specific organism.

The install script is where the databases live

The 0Install.sh section is the longest part of the documentation, and its shape tells you where the effort goes. Almost every tool has at least two installation routes, an unpacked binary and a direct or conda install, and almost every tool has an installation test after it.

For quality control the tools are kneaddata, fastqc, multiqc and fastp, and kneaddata gets four sub-steps: a direct installation method, a download and decompress method, an installation test, and a database download, plus a step for building a custom reference genome index.

For read-based analysis, HUMAnN gets direct installation, unpacking and installation, an installation test, and the species and function database, with a separate entry for the MetaPhlAn4 species database. Kraken2 gets unpacking and install, installing a specified version, and database installation, with krakentools and krona alongside it in the species annotation step.

The same pattern repeats through the rest: megahit for assembly with an unpacked and a direct route and a post-installation test, eggNOG with a CAZy carbohydrate step, rgi for antibiotic resistance genes, metawrap for binning, dRep for genome redundancy removal with a database construction step, CoverM for quantification, and GTDB-Tk with a database installation step.

The databases are the real weight here, and the README acknowledges it in the frequently asked questions, with a section on domestic backup of software and database pointing at the National Microbial Science Data Center and a Baidu Cloud backup link. That is the question you will actually have, and it is answered in the document.

The directory layout is the pipeline's memory

The table of contents describes a working directory rather than a source tree, and the folders are organised around the run rather than around the code.

The 01PPT folder holds the basic knowledge introduction and experience summary of metagenomic analysis, so the teaching material is part of the same download. The seq folder contains the fastq compressed files for testing, which means you can run the pipeline on the test data before you trust it with your own. The temp folder holds the intermediate files generated by the pipeline, and the result folder stores the results. There is a result12 folder with result files used to assist visual testing, and a binning folder for the binning analysis results.

The appendix folder has three parts. The history folder stores historical versions of the analysis process, the makefile folder holds a makefile version of EasyMetagenome, and the statplot_example folder contains two examples of visualising metagenomic analysis results.

Two details are worth calling out. The history folder means you can see what the pipeline looked like in earlier versions, which is invaluable when you are reproducing an analysis from two years ago. And the makefile variant gives you a way to run individual stages as make targets, which is the more conventional workflow engine arrangement, if a numbered shell script is not what you want to work with.

The repository also contains an EasyMetagenome.Rproj file, an RStudio project marker, which is the sign that the visualisation side of the pipeline is R based.

A shell pipeline inherits every weakness of the tools it wraps

The honest limitation of this design is that there is no isolation between the stages. The tools are wired together by a sequence of shell scripts and a Conda environment, and the pipeline is as reliable as the least tested link in that chain.

The first thing to expect is environment friction. The pipeline expects Conda, it expects a specific directory layout with seq, temp, result and binning folders, and it expects the databases to be in the place the install script put them. That is a workable arrangement for one person on one machine, and a poor fit for a cluster with a different scheduler, a container image, or a shared filesystem with different path conventions.

The second is version coupling. Because the tool versions live in environment.yml and the install script fetches specific versions, upgrading one tool means revisiting the whole chain, and the tool list is long enough that this is not a small job. The install documentation says the project is in Development, which is a fair signal that some of those steps will need revisiting.

The third is the fixed order. A numbered script pipeline runs the steps in the order it was written, and skipping a step or running one out of order means editing the script. The LEfSe differential analysis and the binning stage in particular assume upstream outputs exist.

What you get in exchange is the accumulated practical knowledge of people who have run this many times. The README includes an experience summary alongside the teaching material, and the kneaddata FAQ covers a specific failure, a Java version error, which is the kind of thing that only appears in a document written by someone who hit it.

Citing the pipeline is part of using it

One requirement stands out from the technical documentation, and it is in the first ten lines of the README. If you use the project, you are asked to cite the paper, which is given in full: Bai, Defeng, Tong Chen and others including Yong-Xin Liu, 2025, EasyMetagenome: A User-Friendly and Flexible Pipeline for Shotgun Metagenomic Analysis in Microbiome Research, in iMeta 4, e70001, with a DOI and a note that it is highly cited.

For a research pipeline this is a normal and reasonable request, and it is also a signal about what kind of project this is. The output of this pipeline is a set of scientific results, and the pipeline is the instrument that produced them. A reviewer who sees EasyMetagenome in your methods section will want to know which version you used, which is exactly why the release tags are named with their year and month.

The combination of a citation requirement, a paper in a peer reviewed journal and a document that includes a teaching folder and an experience summary tells you the intended audience. This is for a researcher who is doing real microbiome analysis and needs the whole chain to work, not for someone looking for a lightweight tool to call from a notebook.

The support model is implicit as well. There is a frequently asked questions section covering database mirrors and a specific software failure, and the fixes are in the document rather than in an issue tracker. The last push was on 2026-06-14 and the most recent release is v1.24 from late 2025, so the code is newer than the tagged release.

Editorial conclusion

Adopt EasyMetagenome if you run shotgun metagenomics on microbiome data, you work on Linux, and you would rather drive a documented set of tools than assemble and version the tool chain yourself. Do not adopt it if you need a pipeline that fits a different cluster scheduler, or if you want per-step software versions that are independently upgradeable, because the tool versions are pinned together in environment.yml and in the install script. Before you start, read 0Install.sh and 3Init.sh, since the database downloads are the long pole, and note that the project asks users to cite its iMeta paper.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. Releases
5. YongxinLiu/EasyMetagenome on GitHub