ATTENTION

Before opening a new issue here, please check the appropriate help channel on the bioBakery Support Forum (https://forum.biobakery.org) and consider opening or commenting on a thread there.

---

HUMAnN 3.0 User Manual

HUMAnN 3.0 is the next generation of HUMAnN (HMP Unified Metabolic Analysis Network).

---

If you use HUMAnN 3.0 in your work, please cite the HUMAnN 3.0 paper:

Francesco Beghini¹ ,Lauren J McIver² ,Aitor Blanco-Mìguez¹ ,Leonard Dubois¹ ,Francesco Asnicar¹ ,Sagun Maharjan^2,3 ,Ana Mailyan^2,3 ,Andrew Maltez Thomas¹ ,Paolo Manghi¹ ,Mireia Valles-Colomer¹ ,George Weingart^2,3 ,Yancong Zhang^2,3 ,Moreno Zolfo¹ ,Curtis Huttenhower^2,3 ,Eric A Franzosa^2,3 ,Nicola Segata^1,4

Integrating taxonomic, functional, and strain-level profiling of diverse microbial communities with bioBakery 3

eLife 2021;10:e65088

1 Department CIBIO, University of Trento, Italy
2 Harvard T. H. Chan School of Public Health, Boston, MA, USA
3 The Broad Institute of MIT and Harvard, Cambridge, MA, USA
4 IEO, European Institute of Oncology IRCCS, Milan, Italy

And feel free to link to HUMAnN 3.0 in your Methods:

http://huttenhower.sph.harvard.edu/humann

---

For additional information, read the HUMAnN Tutorial

HUMAnN is a pipeline for efficiently and accurately profiling the presence/absence and abundance of microbial pathways in a community from metagenomic or metatranscriptomic sequencing data (typically millions of short DNA/RNA reads). This process, referred to as functional profiling, aims to describe the metabolic potential of a microbial community and its members. More generally, functional profiling answers the question "What are the microbes in my community-of-interest doing (or capable of doing)?"

---

Contents

• Features
• Workflows
  • Main workflow
  • Workflow by input file type
  • Workflow by bypass mode
  • Workflow of the resume option
• Requirements
  • Software
  • Other
• Initial Installation
  1. Download HUMAnN
  2. Install HUMAnN
  3. Test the install
  4. Try out a demo run
  5. Download the databases
     • Download the ChocoPhlAn database
     • Download a translated search database
• Installation Update
• How to run
  • Basic usage
  • Demo runs
  • Standard workflow
• Output files
  1. Gene families file
  2. Pathway abundance file
  3. Pathway coverage file
  4. Intermediate temp output files
     1. Bowtie2 alignment results
     2. Bowtie2 reduced alignment results
     3. Bowtie2 index files
     4. Unaligned reads after Bowtie2
     5. Custom ChocoPhlAn database
     6. MetaPhlAn Bowtie2 output
     7. MetaPhlAn bugs list
     8. Translated alignment results
     9. Translated alignment unaligned reads
     10. Log
• Databases
• Configuration
• Guides to HUMAnN 3.0 utility scripts
  • humann_barplot
  • humann_config
  • humann_databases
  • humann_gene_families_genus_level
  • humann_infer_taxonomy
  • humann_join_tables
  • humann_reduce_table
  • humann_regroup_table
  • humann_rename_table
  • humann_renorm_table
  • humann_split_stratified_table
  • humann_split_table
  • humann_test
  • humann_unpack_pathways
• Other HUMAnN 3.0 guides
  • Selecting a level of gene family resolution
  • Selecting a scope for translated search
  • Paired-end reads
  • PICRUSt output
  • Joint taxonomic profile
  • Custom taxonomic profile
  • Custom nucleotide reference database
  • Custom protein reference database
  • Custom reference database annotations
  • Custom pathways database
  • Core diversity analysis with QIIME
  • Metatranscriptome analysis with HUMAnN 3.0
  • Genus level gene families and pathways
• FAQs
• Complete option list

---

Features

1. Community functional profiles stratified by known and unclassified organisms

   • MetaPhlAn and ChocoPhlAn pangenome database are used to facilitate fast, accurate, and organism-specific functional profiling
   • Organisms included are Archaea, Bacteria, Eukaryotes, and Viruses

2. Considerably expanded databases of genomes, genes, and pathways

   • UniRef database provides gene family definitions
   • MetaCyc provides pathway definitions by gene family
   • MinPath is run to identify the set of minimum pathways

3. A simple user interface (single command driven flow)

   • The user only needs to provide a quality-controlled metagenome or metatranscriptome

4. Accelerated mapping of reads to reference databases (including run-time generated databases tailored to the input)

   • Bowtie2 is run for accelerated nucleotide-level searches
   • Diamond is run for accelerated translated searches

---

Workflows

Main workflow

Workflow by input file type

There are four different types of files that can be provided as input to HUMAnN 3.0 . By default HUMAnN 3.0 will determine the type of the file. As shown in the figure below, the type of input file will determine where HUMAnN 3.0 will start the workflow. Files of type 2, 3, and 4 will begin the workflow after the alignment steps.

File Types:

• File Type 1 (a quality-controlled metagenome or metatranscriptome)
  • fastq (fastq.gz)
  • fasta (fasta.gz)
• File Type 2 (alignment results type 1)
  • sam
  • bam
• File Type 3 (alignment results type 2)
  • blast-like tsv
• File Type 4 (gene table)
  • tsv
  • biom

---

Workflow by bypass mode

There are multiple bypass options that will allow you to adjust the standard workflow.

Bypass options:

• --bypass-translated-search
  • runs all of the alignment steps except the translated search
• --bypass-nucleotide-search
  • bypasses all of the alignment steps before the translated search
• --bypass-prescreen
  • bypasses the taxomonic profiling step and uses the full ChocoPhlAn database
• --taxonomic-profile bugs_list.tsv
  • bypasses the taxomonic profiling step and creates a custom ChocoPhlAn database of the species included in the list provided
• --bypass-nucleotide-index
  • starts the workflow with the nucleotide alignment step using the indexed database from "--nucleotide-database $DIR"

---

Workflow of the resume option

HUMAnN 3.0 includes a "--resume" option which will allow you to bypass alignment steps which have already been completed. For example, if you originally ran with a bypass option you can run just the step you bypassed with "--resume". This will only run the alignment step you bypassed and then recompute the gene families and pathways.

When using the "--resume" option, the following steps will be bypassed if they have already been completed:

1. Taxomonic profiling step
2. Nucleotide alignment step
3. Custom ChocoPhlAn database creation (merge and index)
4. Translated alignment step

---

Requirements

Software

1. MetaPhlAn 3.0
2. Bowtie2 (version >= 2.2) (automatically installed)
3. Diamond (version >= 0.9.24) (automatically installed)
4. Python (version >= 3.7)
5. MinPath (automatically installed)
6. Xipe (optional / included)
7. Rapsearch2 (version >= 2.21) (only required if using rapsearch2 for translated search)
8. Usearch (version >= 7.0) (only required if using usearch for translated search)
9. SAMtools (only required if bam input files are provided)
10. Biom-format (only required if input or output files are in biom format)

Please install the required software in a location in your $PATH or provide the location with an optional argument to HUMAnN 3.0. For example, the location of the Bowtie2 install ($BOWTIE2_DIR) can be provided with "--bowtie2 $BOWTIE2_DIR".

Some of the required dependencies are installed automatically when installing HUMAnN 3.0 with pip. If these dependencies do not appear to be installed after installing HUMAnN 3.0 with pip, it might be that your environment is setup to use wheels instead of installing from source. HUMAnN 3.0 must be installed from source for it to also be able to install dependencies. To force pip to install HUMAnN 3.0 from source add one of the following options to your install command, "--no-use-wheel" or "--no-binary :all:".

If you always run with input files of type 2, 3, and 4 (for information on input file types, see section Workflow by input file type), MetaPhlAn2, Bowtie2, and Diamond are not required. Also if you always run with one or more bypass options (for information on bypass options, see section Workflow by bypass mode), the software required for the steps you bypass does not need to be installed.

Other

1. Memory (>= 16 Gb)
2. Disk space (>= 15 Gb [to accommodate comprehensive sequence databases])
3. Operating system (Linux or Mac)

If always running with files of type 2, 3, and 4 (for information on file types, see section Workflow by input file type), less disk space is required.

---

Initial Installation

1. Download HUMAnN 3.0

You can download the latest HUMAnN 3.0 release or the development version. The source contains example files. If installing with pip, it is optional to first download the HUMAnN 3.0 source.

Option 1: Latest Release (Recommended)

• humann.tar.gz and unpack the latest release of HUMAnN 3.0

Option 2: Development Version

• Create a clone of the repository:

  $ git clone https://github.com/biobakery/humann

  Note: Creating a clone of the repository requires Github to be installed.

---

2. Install HUMAnN 3.0

Installing with pip

1. Install HUMAnN 3.0
   • $ pip install humann
   • This command will automatically install MinPath (and a new version of glpk) along with Bowtie2 and Diamond (if they are not already installed).
   • To bypass the install of Bowtie2 and Diamond, add the option "--install-option='--bypass-dependencies-install'" to the install command.
   • To build Diamond from source during the install, add the option "--install-option='--build-diamond'" to the install command.
   • To overwite existing installs of Bowtie2 and Diamond, add the option "--install-option='--replace-dependencies-install'" to the install command.
   • If you do not have write permissions