Metatranscriptomic Pathway Analysis with HUMAnN 3

HUMAnN estimates microbial gene-family and pathway abundances from metagenomic or metatranscriptomic reads. This walkthrough follows quality-controlled, rRNA-depleted reads through per-sample profiling, table joining, normalization, and interpretation. It is a computational profile of transcript evidence, not a direct measurement of enzyme activity or metabolic flux.

What you need and what you will produce

Start with one quality-controlled, rRNA-depleted FASTQ/FASTA file per sample; the run example uses compressed FASTQ. This walkthrough assumes basic shell use plus an installed HUMAnN 3 environment with compatible nucleotide and translated-search databases configured. For a clean setup, follow the official HUMAnN installation and database instructions and the Huttenhower Lab HUMAnN 3 guide. The official installation includes small demo databases; run humann_test as an installation check, then humann --version and save its output alongside the exact database names/releases and configuration used. HUMAnN and database releases affect mappings, so do not substitute versions silently. A demo/test run checks software wiring, not the suitability of an installation for study-scale analysis or biological validity. The commands below illustrate the workflow; they do not report a run performed for this page.

Before profiling, confirm each path exists and each compressed FASTQ can be read without a gzip integrity error (for example, test -s data/sampleA_mRNA.fastq.gz && gzip -t data/sampleA_mRNA.fastq.gz). Stop if either check fails; do not rename files to hide a format mismatch. Keep a sample manifest linking each sample ID to its input and processing history. These checks establish file availability and compression integrity only, not read quality, rRNA depletion, sample identity, or biological suitability.

For each sample HUMAnN writes gene-family, pathway-abundance, pathway-coverage, and log/output files. The feature tables can include community-level rows and taxon-stratified rows. After this exercise you will have joined pathway abundance and coverage matrices, plus a copies-per-million (CPM) abundance table for descriptive visualization.

Run HUMAnN for each sample

1. Prepare the input. Use reads after quality control and rRNA depletion appropriate to the study. Keep sample IDs consistent and avoid reusing an output directory containing another sample's results.
2. Profile the sample. Replace the example path and sample ID. An optional MetaPhlAn profile can be supplied with --taxonomic-profile; it is an input profile used to select taxa for the custom pangenome search. It is not a raw-reads shortcut and must correspond to the sample or a deliberate joint profile.

   humann \
     --input data/sampleA_mRNA.fastq.gz \
     --output humann_out/sampleA \
     --threads 12
   

   Without a supplied profile, HUMAnN runs its own taxonomic prescreen as part of its workflow. The required reference databases must already be installed/configured. For a multi-sample analysis, repeat with a distinct input and output directory for each sample.

3. Check the run before aggregating. Inspect the HUMAnN log for errors, save the command and software/database versions, and confirm non-empty sampleA_genefamilies.tsv, sampleA_pathabundance.tsv, and sampleA_pathcoverage.tsv files in the output directory (HUMAnN uses the output basename as the sample prefix). Confirm the tables have a feature-name column and abundance/coverage values, then compare names and sample IDs with your manifest. Stop and investigate missing, empty, malformed, or unexpected files rather than treating them as zero-valued biology. A structurally valid table is not proof that mapping or biological interpretation is sound.

Join per-sample pathway tables

HUMAnN's join utility selects files by a filename substring. Use a suffix common to all samples, not one sample's full filename, or the command may join only one table. From the project directory:

humann_join_tables \
  --input humann_out \
  --file_name _pathabundance.tsv \
  --output merged_pathabundance.tsv

humann_join_tables \
  --input humann_out \
  --file_name _pathcoverage.tsv \
  --output merged_pathcoverage.tsv

The input directory is searched for matching HUMAnN tables; the output is a multi-sample table with features and sample columns. Review the joined header and confirm every intended sample appears once. For gene families, use the corresponding _genefamilies.tsv suffix. Do not include a previous merged output in the input directory if its filename also matches the selected substring.

Normalize for descriptive plots

HUMAnN reports gene-family and pathway abundance in RPK units. CPM in HUMAnN means copies per million, a total-sum-scaled abundance, not raw sequencing counts per million. Convert the joined pathway table when CPM is useful for visualization:

humann_renorm_table \
  --input merged_pathabundance.tsv \
  --output merged_pathabundance_cpm.tsv \
  --units cpm

CPM is not a raw count matrix and should not be passed to count-based differential-expression methods as if it were counts. Choose a statistical method and input representation appropriate to the study and method; normalization alone does not address compositionality, covariates, or batch effects. Keep the unnormalized HUMAnN output and document any downstream transformation.

Separate community and taxon-stratified rows

Rows with a taxonomic suffix (for example, a pathway followed by |taxon) report stratified contributions; an unstratified pathway row summarizes the community-level estimate. To write these into separate tables, pass an output directory to HUMAnN's split utility:

humann_split_stratified_table \
  --input merged_pathabundance.tsv \
  --output split_pathabundance

The utility writes two tables in that directory, one stratified and one unstratified. Check the generated filenames and inspect the rows before analysis. This is a file split, not a transformation into separate taxon columns. Apply the same operation to coverage only if separate stratified and unstratified coverage tables are needed.

Interpret abundance and coverage together

• Pathway abundance summarizes mapped gene-family evidence assigned to a MetaCyc pathway. A larger estimate indicates more mapped abundance under the chosen profiling and normalization context; it is not a direct rate of pathway operation.
• Pathway coverage is a pathway completeness/coverage estimate based on detected pathway components. Interpret its scale and calculation in the HUMAnN version and output format used; do not describe it as a direct assay of every enzymatic step.
• Gene-family rows help trace which UniRef families contribute to a pathway estimate. Shared or ambiguously mapped functions can contribute to multiple interpretations.
• Stratification attributes contributions using the taxonomic profile and reference mappings. Treat small or uncertain taxon contributions cautiously, especially for conserved gene families.

Troubleshoot before drawing conclusions

• Run is slow: translated search can be computationally demanding, particularly when many reads remain after nucleotide search. Check logs, available threads, storage/I/O, and database configuration. Any sensitivity or bypass option changes what is searched; consult the installed version's help and document the change rather than applying an undocumented speed tweak.
• Few reads map or coverage is low: check read quality and length, rRNA depletion, database versions and configuration, and logs for failed search stages. Novel organisms or functions absent from references can also limit mapping. Low mapping is not by itself evidence that the biological function is absent.
• Unexpected taxon attribution: inspect stratified and unstratified rows, contributing gene families, and the taxonomic profile supplied to HUMAnN. Shared families and profile errors can complicate attribution. A second taxonomic profile on the same reads is a useful diagnostic, not independent confirmation of function.
• Samples differ after normalization: review library depth, sample processing, study design, and compositional effects. CPM rescales totals; it does not make absolute transcript abundance comparable or replace a statistical model.

Report the analysis reproducibly

Keep the exact HUMAnN version, database identities/releases, commands and options, input processing steps, sample metadata, and any filtering or normalization decisions with the results. Database releases can change mappings. For important biological claims, use complementary evidence such as metaproteomics, metabolomics, targeted assays, or activity measurements, selected to answer the specific claim.

References

• HUMAnN official documentation and utility reference
• Huttenhower Lab HUMAnN 3 overview and release information
• MetaCyc Pathway/Genome Database
• MetaPhlAn documentation
• Beghini et al. (2021), bioBakery 3 profiling framework