metagenome-functional-profiling

Files (10)

• SKILL.md
• README.md · agents/
• claude.yaml · agents/
• openai.yaml · agents/
• .gitkeep · assets/
• config.yaml
• README.md · references/
• humann-prokka-eggnog.md · references/
• batch_run.sh · scripts/
• run.sh · scripts/

SKILL.md (first lines)

# Skill: metagenome-functional-profiling

## Use When

- The user wants to know what metabolic functions are present in a metagenome.
- The user needs pathway-level abundance profiles (MetaCyc, KEGG).
- The user wants to annotate predicted genes from MAGs or assembled contigs.
- The user needs gene family and ortholog group assignments.

## Inputs

- Required:
  - Host-depleted FASTQ file(s) for HUMAnN, OR assembled contigs/MAGs FASTA for Prokka/eggNOG.
- Optional:
  - `--tool STR` — Tool to use: `humann`, `prokka`, or `eggnog` (default: `humann`).
  - `--db PATH` — HUMAnN databases (ChocoPhlAn, UniRef) or eggNOG database path.
  - `--taxonomic-profile FILE` — Taxonomic profile from `metagenome-taxonomic-profiling` to speed up HUMAnN.
  - `--kingdom STR` — Prokka kingdom (default: `Bacteria`).
  - `--threads N` — Number of threads (default: 4).
  - `--outdir DIR` — Output directory (default: `functional_profiling_results`).

## Workflow

1. If HUMAnN: run `humann` with `--input` FASTQs, optionally with `--taxonomic-profile` for guided search.
2. HUMAnN produces: gene families (RPK), pathway abundance, pathway coverage.
3. Normalize HUMAnN output with `humann_renorm_table` (CPM or relative abundance).
4. If Prokka: run on contigs/MAGs for gene prediction and annotation.
5. If eggNOG-mapper: run `emapper.py` on predicted protein sequences for COG/KEGG/GO annotation.
6. Report: number of gene families, pathways detected, top abundant pathways, functional category distribution.

## Output Contract

- **HUMAnN gene family table** — Gene families with RPK values (`<outdir>/<sample>_genefamilies.tsv`).
- **HUMAnN pathway abundance table** — Pathway abundances (`<outdir>/<sample>_pathabundance.tsv`).
- **HUMAnN pathway coverage table** — Pathway coverage scores (`<outdir>/<sample>_pathcoverage.tsv`).
- **Prokka annotations** — GFF, GBK, FAA, FFN files (`<outdir>/prokka/`).
- **eggNOG annotation table** — COG, KEGG, GO annotations (`<outdir>/eggnog/<sample>.emapper.annotations`).
- **Functional summary** — Top pathways, gene family counts, functional category distribution (`<outdir>/functional_summary.txt`).

## Limits

- HUMAnN 3 requires ChocoPhlAn (approximately 15 GB) and UniRef90 (approximately 20 GB) databases.
- Prokka is designed for prokaryotic genomes; use appropriate `--kingdom` for archaea.
- eggNOG database is approximately 45 GB.
- HUMAnN is computationally intensive and may take hours per sample; for large cohorts, consider running on HPC.
- HUMAnN, Prokka, and eggNOG-mapper must be installed and available on `$PATH`.
- Prokka and eggNOG-mapper operate on contigs/proteins, not raw reads.
- Common failure cases:
  - HUMAnN ChocoPhlAn or UniRef databases not downloaded or path misconfigured.
  - Prokka failing on non-prokaryotic contigs when `--kingdom` is set incorrectly.
  - eggNOG-mapper database version mismatch with the installed emapper version.

From Scientific-Tooling/structured-intelligence, MIT.

More from Scientific-Tooling/structured-intelligence