DOCSEARCHbyAlgolia
Submit Docs

HUMAnN (HMP Unified Metabolic Analysis Network)

repository·master·Indexed 42 days ago

https://github.com/biobakery/humann

A pipeline for functional profiling of microbial communities that estimates the presence and abundance of microbial pathways from metagenomic or metatranscriptomic sequencing data. It utilizes MetaPhlAn, ChocoPhlAn, UniRef, and MetaCyc to describe the metabolic potential of communities, featuring accelerated mapping via Bowtie2 and Diamond.

Tokens
12.4K
Snippets
31
Records
51
Agent score
4%

What's inside HUMAnN

  1. Key features of HUMAnN

    master

    HUMAnN provides several core capabilities for functional profiling:

    1. Stratified Community Profiles: Profiles are stratified by known and unclassified organisms using MetaPhlAn and the ChocoPhlAn pangenome database (covering Archaea, Bacteria, Eukaryotes, and Viruses).
    2. Expanded Databases: Uses UniRef for gene family definitions, MetaCyc for pathway definitions, and MinPath to identify minimum pathway sets.
    3. Simple Interface: A single-command driven flow that accepts quality-controlled metagenomes or metatranscriptomes.
    4. Accelerated Mapping: Uses Bowtie2 for nucleotide-level searches and Diamond for translated protein-level searches.

  2. What is HUMAnN and what does it do?

    master

    HUMAnN (HMP Unified Metabolic Analysis Network) is a pipeline for functional profiling of microbial communities. It estimates the presence/absence and abundance of microbial pathways from metagenomic or metatranscriptomic sequencing data (typically millions of short DNA/RNA reads).

    It answers the question: "What are the microbes in my community-of-interest doing (or capable of doing)?" by describing the metabolic potential of the community and its members.

  3. Select a scope for translated search

    master

    When reads fail to align to a known pangenome, HUMAnN performs a translated search. You can tune the scope of this search using the following modes:

    • Bypass translated search: Use the --bypass-translated-search flag. Reads that fail to map to a pangenome are saved but not searched at the protein level. No unclassified strata will appear in the output.
    • Filtered translated search: Uses an EC-filtered protein database (UniRef90 or UniRef50). These databases only include proteins with level-4 enzyme commission (EC) annotations. This provides comprehensive metabolic reconstruction for the unclassified stratum but limits the number of unclassified protein families to those with EC annotations. Recommended default for most users.
    • Comprehensive translated search: Uses a full, unfiltered protein database. This aims to explain as many reads as possible but is approximately 5x slower than filtered search and has higher memory requirements.

  4. How HUMAnN workflows vary by input file type

    master

    HUMAnN automatically determines the starting point of its workflow based on the input file type. Providing processed files allows you to bypass earlier, computationally expensive steps.

    File TypeDescriptionSupported Formats
    Type 1Quality-controlled metagenome/metatranscriptomefastq, fastq.gz, fasta, fasta.gz
    Type 2Alignment results from Type 1sam, bam
    Type 3Alignment results from Type 2blast-like tsv
    Type 4Gene tabletsv, biom

  5. Choose a level of gene family resolution

    master

    HUMAnN uses UniRef protein clusters as its gene families system. You can choose between different levels of clustering to balance redundancy and resolution:

    • UniRef100: No clustering (highest redundancy).
    • UniRef90: Clusters proteins at 90% identity.
    • UniRef50: Clusters UniRef90 representative sequences at 50% identity (broader clusters).

    The representative of a cluster is typically the best-annotated member.

  6. Resume a previously interrupted workflow

    master

    The --resume option allows you to restart a workflow from a specific point by bypassing steps that have already been completed. This is particularly useful if a run was interrupted or if you previously used a bypass option and now want to complete the full pipeline.

    When using --resume, the following steps are automatically bypassed if they are already present:

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

  7. Analyze metatranscriptomes (RNA)

    master

    The protocol depends on whether you have paired metagenomic (DNA) data:

    • With paired metagenome: Analyze the metagenome first. Then, run HUMAnN on the RNA data using the metagenome's taxonomic profile via --taxonomic-profile. This ensures RNA reads map to species pangenomes detected in the DNA. You can then normalize RNA-level outputs by DNA-level outputs.
    • Isolated metatranscriptome: Analyze RNA reads like DNA reads (FASTQ/FASTA).

    Caveats for RNA:

    1. Species quantification relies on marker gene recruitment; relative abundance reflects contributions to the transcript pool, not the overall pool.
    2. Transcript abundance is confounded by gene copy number (higher abundance could mean higher expression OR more gene copies).

  8. Basic usage of the HUMAnN CLI

    master

    Run HUMAnN on a single input file by specifying the --input file and the --output directory.

    Supported Input Types:

    • Filtered shotgun sequencing metagenome files (fastq, fastq.gz, fasta, or fasta.gz).
    • Alignment files (sam, bam, or blastm8).
    • Gene table files (tsv or biom).

    Output Files: For each sample, HUMAnN creates several files in the output directory. Note that in HUMAnN v3, the log file and taxonomic profile are located in the intermediate temp folder, and filenames do not include numeric suffixes. The main outputs are:

    • [SAMPLENAME]_metaphlan_profile.tsv (Taxonomic profile)
    • [SAMPLENAME]_genefamilies.tsv (Gene families)
    • [SAMPLENAME]_reactions.tsv (Pathways/Reactions)
    • [SAMPLENAME]_pathabundance.tsv (Pathway abundance)

    Note: The gene families file is not created if the input is a gene table.

    You can customize the prefix of the output files using the --output-basename <$NEWNAME> option.

    $ humann --input $SAMPLE --output $OUTPUT_DIR

  9. Software requirements for HUMAnN

    master

    To run HUMAnN, the following software must be installed and available in your $PATH (or provided via CLI arguments):

    • MetaPhlAn
    • Bowtie2 (version >= 2.2.9)
    • Diamond (version >= 0.9.24)
    • Python (version >= 3.7)
    • MinPath
    • SAMtools (only if using .bam input files)
    • Biom-format (only if using .biom input/output files)

    Note on automatic installation: Bowtie2, Diamond, and MinPath are automatically installed when installing HUMAnN via pip or setup.py. If you have already installed these tools manually, you can bypass the automatic installation during the HUMAnN setup.

    Note on bypass modes: If you only use specific input file types (types 2, 3, or 4) or use bypass options, some dependencies like MetaPhlAn, Bowtie2, or Diamond may not be required.

  10. Use a custom taxonomic profile

    master

    You can bypass MetaPhlAn by providing a custom tab-delimited taxonomic profile. The file must contain two columns: taxon (genus and species) and percent abundance.

    Example format:

    g__Bacteroides|s__Bacteroides_thetaiotaomicron	12.16326
g__Dialister|s__Dialister_invisus	10.52287

    Use the --taxonomic-profile $FILE flag. Only taxa with abundance greater than the default prescreen threshold are considered. Adjust this with --prescreen-threshold $THRESHOLD.

  11. Run HUMAnN with PICRUSt output

    master

    You can use PICRUSt (version 1.0.0-dev) output from predict_metagenomes.py or metagenome_contributions.py as input. Follow these steps:

    1. Download legacy KEGG databases (from HUMAnN 1.0).
    2. Split the PICRUSt output (.biom or .tsv) into individual sample files using humann_split_table:
      $ humann_split_table --input picrust.biom --output $OUTPUT_DIR
      Use --taxonomy_index -1 if taxonomy info is in a .biom file with K0s at column -1.
    3. Run HUMAnN on each sample file:
      $ humann --input $SAMPLE.biom --output $OUTPUT_DIR2 --pathways-database humann1/data/keggc
      Options: --remove-stratified-output (no bug stratification), --output-format biom, or --pathways-database humann1/data/modulec for KEGG modules.
    4. Join the results using humann_join_tables:
      $ humann_join_tables --input $OUTPUT_DIR2 --output humann_4_pathabundance.tsv --file_name pathabundance
    $ humann_split_table --input picrust.biom --output $OUTPUT_DIR
$ humann --input $SAMPLE.biom --output $OUTPUT_DIR2 --pathways-database humann1/data/keggc
$ humann_join_tables --input $OUTPUT_DIR2 --output humann_4_pathabundance.tsv --file_name pathabundance

  12. Download HUMAnN databases

    master

    Downloading databases is required for processing filtered shotgun sequencing metagenome files (fastq, fastq.gz, fasta, or fasta.gz).

    1. Download ChocoPhlAn database

    This provides the nucleotide database (approx. 16.4 GB).

    humann_databases --download chocophlan full $INSTALL_LOCATION

    2. Download a translated search (protein) database

    Users can choose different databases based on resolution and performance requirements:

    • UniRef90 (Recommended): Full database (20.7 GB). humann_databases --download uniref uniref90_diamond $INSTALL_LOCATION
    • UniRef90 EC-filtered: (0.9 GB). humann_databases --download uniref uniref90_ec_filtered_diamond $INSTALL_LOCATION
    • UniRef50: Full database (6.9 GB). humann_databases --download uniref uniref50_diamond $INSTALL_LOCATION
    • UniRef50 EC-filtered: (0.3 GB). humann_databases --download uniref uniref50_ec_filtered_diamond $INSTALL_LOCATION

    Note: Ensure all databases in a single directory are of the same version. If you move databases later, use humann_config to update the paths.

    # Download ChocoPhlAn
humann_databases --download chocophlan full /path/to/install

# Download recommended UniRef90 database
humann_databases --download uniref uniref90_diamond /path/to/install