Add HUMAnN 4 database generation protocols

PROTOCOLS.yaml

@@ -1,5 +1,201 @@
 spec_version: 1.0.0
 repository: waldronlab/ai-agent-protocols
-generated_at: '2026-08-18T13:24:45Z'
-protocols: []
+generated_at: '2026-08-18T13:25:22Z'
+protocols:
+- name: humann4-augmented-clustering
+  description: Predict ORFs and perform augmented UniRef-compatible protein clustering.
+  version: 1.0.0
+  authors:
+  - name: Levi Waldron
+    orcid: 0000-0003-2725-0694
+  date: '2026-08-08'
+  status: draft
+  license: CC-BY-4.0
+  type: atomic
+  protocol_doi: ~
+  repository_doi: ~
+  publication_doi: ~
+  citation: 10.1016/j.cell.2019.01.001
+  upstream_repositories:
+  - https://github.com/biobakery/humann
+  - https://github.com/biobakery/metaphlan
+  database_urls:
+  - http://huttenhower.sph.harvard.edu/humann_data/uniprot/uniref_annotated/
+  - ftp://ftp.uniprot.org/pub/databases/uniprot/uniref/
+  protocols_used: []
+  key_packages: []
+  category: metagenomics
+  tags:
+  - humann
+  - chocophlan
+  - database
+  - uniref
+  - clustering
+  - mmseqs2
+  - diamond
+  protocol_url: https://raw.githubusercontent.com/waldronlab/ai-agent-protocols/main/protocols/humann4-augmented-clustering/protocol.md
+- name: humann4-chocophlan-build
+  description: Construct the HUMAnN 4 ChocoPhlAn nucleotide pangenome database.
+  version: 1.0.0
+  authors:
+  - name: Levi Waldron
+    orcid: 0000-0003-2725-0694
+  date: '2026-08-08'
+  status: draft
+  license: CC-BY-4.0
+  type: atomic
+  protocol_doi: ~
+  repository_doi: ~
+  publication_doi: ~
+  citation: 10.7554/eLife.65088
+  upstream_repositories:
+  - https://github.com/biobakery/humann
+  - https://github.com/biobakery/metaphlan
+  database_urls:
+  - http://huttenhower.sph.harvard.edu/humann_data/chocophlan/
+  - http://cmprod1.cibio.unitn.it/databases/chocophlan/
+  protocols_used: []
+  key_packages: []
+  category: metagenomics
+  tags:
+  - humann
+  - chocophlan
+  - database
+  - pangenome
+  - bowtie2
+  protocol_url: https://raw.githubusercontent.com/waldronlab/ai-agent-protocols/main/protocols/humann4-chocophlan-build/protocol.md
+- name: humann4-database-build
+  description: End-to-end composite pipeline for constructing HUMAnN 4 reference databases
+    from MetaPhlAn 4.2 SGBs.
+  version: 1.0.0
+  authors:
+  - name: Levi Waldron
+    orcid: 0000-0003-2725-0694
+  date: '2026-08-18'
+  status: draft
+  license: CC-BY-4.0
+  type: composite
+  protocol_doi: ~
+  repository_doi: ~
+  publication_doi: ~
+  citation: 10.7554/eLife.65088
+  upstream_repositories:
+  - https://github.com/biobakery/humann
+  - https://github.com/biobakery/metaphlan
+  database_urls:
+  - http://huttenhower.sph.harvard.edu/humann_data/chocophlan/
+  - http://huttenhower.sph.harvard.edu/humann_data/uniprot/uniref_annotated/
+  - http://huttenhower.sph.harvard.edu/humann_data/mapping/
+  protocols_used:
+  - name: humann4-sgb-aggregation
+    repository: waldronlab/ai-agent-protocols
+    version: 1.0.0
+  - name: humann4-augmented-clustering
+    repository: waldronlab/ai-agent-protocols
+    version: 1.0.0
+  - name: humann4-chocophlan-build
+    repository: waldronlab/ai-agent-protocols
+    version: 1.0.0
+  - name: humann4-translated-search-build
+    repository: waldronlab/ai-agent-protocols
+    version: 1.0.0
+  - name: humann4-utility-mapping
+    repository: waldronlab/ai-agent-protocols
+    version: 1.0.0
+  key_packages: []
+  category: metagenomics
+  tags:
+  - humann
+  - chocophlan
+  - database
+  - pipeline
+  - composite
+  protocol_url: https://raw.githubusercontent.com/waldronlab/ai-agent-protocols/main/protocols/humann4-database-build/protocol.md
+- name: humann4-sgb-aggregation
+  description: Aggregate and subsample isolate genomes and MAGs for MetaPhlAn 4.2
+    SGBs.
+  version: 1.0.0
+  authors:
+  - name: Levi Waldron
+    orcid: 0000-0003-2725-0694
+  date: '2026-08-08'
+  status: draft
+  license: CC-BY-4.0
+  type: atomic
+  protocol_doi: ~
+  repository_doi: ~
+  publication_doi: ~
+  citation: 10.1016/j.cell.2019.01.001
+  upstream_repositories:
+  - https://github.com/biobakery/metaphlan
+  - https://github.com/biobakery/panphlan
+  database_urls:
+  - http://cmprod1.cibio.unitn.it/databases/MetaPhlAn/
+  - http://cmprod1.cibio.unitn.it/databases/PanPhlAn/
+  protocols_used: []
+  key_packages: []
+  category: metagenomics
+  tags:
+  - humann
+  - chocophlan
+  - database
+  - sgb
+  - metaphlan
+  protocol_url: https://raw.githubusercontent.com/waldronlab/ai-agent-protocols/main/protocols/humann4-sgb-aggregation/protocol.md
+- name: humann4-translated-search-build
+  description: Compile the HUMAnN 4 translated search database.
+  version: 1.0.0
+  authors:
+  - name: Levi Waldron
+    orcid: 0000-0003-2725-0694
+  date: '2026-08-08'
+  status: draft
+  license: CC-BY-4.0
+  type: atomic
+  protocol_doi: ~
+  repository_doi: ~
+  publication_doi: ~
+  citation: 10.7554/eLife.65088
+  upstream_repositories: https://github.com/biobakery/humann
+  database_urls: http://huttenhower.sph.harvard.edu/humann_data/uniprot/uniref_annotated/
+  protocols_used: []
+  key_packages: []
+  category: metagenomics
+  tags:
+  - humann
+  - database
+  - translated-search
+  - diamond
+  - uniref
+  protocol_url: https://raw.githubusercontent.com/waldronlab/ai-agent-protocols/main/protocols/humann4-translated-search-build/protocol.md
+- name: humann4-utility-mapping
+  description: Generate HUMAnN 4 utility mapping databases for functional annotation.
+  version: 1.0.0
+  authors:
+  - name: Levi Waldron
+    orcid: 0000-0003-2725-0694
+  date: '2026-08-08'
+  status: draft
+  license: CC-BY-4.0
+  type: atomic
+  protocol_doi: ~
+  repository_doi: ~
+  publication_doi: ~
+  citation: 10.7554/eLife.65088
+  upstream_repositories:
+  - https://github.com/biobakery/humann
+  - https://github.com/eggnogdb/eggnog-mapper
+  database_urls:
+  - http://huttenhower.sph.harvard.edu/humann_data/mapping/
+  - http://huttenhower.sph.harvard.edu/humann_data/legacy_dbs/
+  protocols_used: []
+  key_packages: []
+  category: metagenomics
+  tags:
+  - humann
+  - database
+  - functional-annotation
+  - eggnog-mapper
+  - uniprot
+  protocol_url: https://raw.githubusercontent.com/waldronlab/ai-agent-protocols/main/protocols/humann4-utility-mapping/protocol.md
 

README.md

@@ -2,6 +2,26 @@
 
 This repository serves as both the central federation registry and a host for AI agent-compatible scientific protocols for the Waldron Lab.
 
+## What is an AI Agent Protocol?
+
+An "AI Agent Protocol" is related to but different than an [AI Skill](https://github.com/bioconductor/ai-agent-skills).
+
+*   **AI Skill**: A specific capability given to an AI agent (e.g., how to query a specific biological database, or how to use a particular R package). Skills teach the AI *how* to perform specific actions.
+*   **AI Agent Protocol**: A scientific workflow, experimental plan, or analytical pipeline designed to be executed by or in collaboration with an AI agent. Protocols in this registry are **designed around provenance to published methods**. Protocols:
+    - are formal records providing citation both to primary scientific literature and to publication of protocols (#4). Atomic protocols have a single purpose with a single citation to primary literature; composite protocols may be composed of multiple atomic protocols.
+    - will record **human reviews** (#2)
+    - will support **formal unit tests/benchmarks** (#3) to verify correct execution by different AI agents and models. 
+
+## Utility and Core Use Cases
+
+Some likely use cases include:
+
+1. **Constraining Coding Agents to Established Methods**: Forces AI agents to adhere strictly to vetted, peer-reviewed analytical protocols rather than drifting, inventing parameters, or inventing plausible but untested methodology during automated script generation. Protocols are expected to create more uniform behavior by different AI agents and models.
+2. **Cross-Language and Pipeline Translation**: Serves as an unambiguous English-language specification for translating computational workflows across programming languages and pipeline frameworks (e.g., Nextflow ↔ Snakemake, R ↔ Python) without losing domain-specific logic or parameter integrity.
+3. **Discrepancy Auditing (Paper vs. Code vs. Protocol)**: Acts as an explicit benchmark to systematically detect inconsistencies between high-level descriptions in published manuscript Methods sections, formal protocol documentation, and actual codebase implementations. Protocols should be easier for people with domain expertise to review than codebase or even Methods sections which are less structured, can be split across main manuscript and supplementary materials, and may lack necessary details for full implementation.
+4. **Filling the Methodological Reproducibility Gap**: Provides the granular operational, environment, and parameter-level details that traditional journal Methods sections often omit, facilitating computational reproducibility with less susceptbility to bitrot or dependency issues.
+5. **A federated registry of AI agent-compatible protocols**: This repository serves as a central registry for AI agent-compatible protocols, designed to allow researchers to independently create their own protocol repositories and federate them into this central registry. 
+
 ## License
 
 This repository is dual-licensed:

protocols/humann4-augmented-clustering/protocol.md

@@ -0,0 +1,75 @@
+---
+name: humann4-augmented-clustering
+description: Predict ORFs and perform augmented UniRef-compatible protein clustering.
+version: 1.0.0
+authors:
+  - name: Levi Waldron
+    orcid: 0000-0003-2725-0694
+date: 2026-08-08
+status: draft
+license: CC-BY-4.0
+type: atomic
+
+protocol_doi: ~
+repository_doi: ~
+publication_doi: ~
+
+citation: "10.1016/j.cell.2019.01.001"
+
+upstream_repositories:
+  - "https://github.com/biobakery/humann"
+  - "https://github.com/biobakery/metaphlan"
+
+database_urls:
+  - "http://huttenhower.sph.harvard.edu/humann_data/uniprot/uniref_annotated/"
+  - "ftp://ftp.uniprot.org/pub/databases/uniprot/uniref/"
+
+protocols_used: []
+key_packages: []
+category: metagenomics
+tags: [humann, chocophlan, database, uniref, clustering, mmseqs2, diamond]
+---
+
+# HUMAnN 4 Augmented Protein Clustering
+
+This protocol outlines how to process the representative genomes for MetaPhlAn 4.2 SGBs to predict proteins and cluster them in compatibility with the UniRef90/UniRef50 ontologies.
+
+## Materials
+
+- **Software & Repositories:**
+  - `Prodigal` ([hyattpd/Prodigal](https://github.com/hyattpd/Prodigal)) — Fast prokaryotic gene recognition and ORF prediction.
+  - `DIAMOND` ([bbuchfink/diamond](https://github.com/bbuchfink/diamond)) — Accelerated protein alignment against UniRef.
+  - `MMseqs2` ([soedinglab/MMseqs2](https://github.com/soedinglab/MMseqs2)) — Ultra-fast de novo protein clustering.
+  - `humann` ([biobakery/humann](https://github.com/biobakery/humann)) — Upstream database utilities and configurations.
+- **Databases & Reference Data:**
+  - Previous UniRef Database Builds ([HUMAnN Data Server](http://huttenhower.sph.harvard.edu/humann_data/uniprot/uniref_annotated/)) — Baseline UniRef50/UniRef90 releases used in HUMAnN 3.
+  - UniProt UniRef Releases ([UniProt FTP](ftp://ftp.uniprot.org/pub/databases/uniprot/uniref/)) — Official UniRef90 and UniRef50 FASTA releases.
+
+## Steps
+
+### Step 1: Open Reading Frame (ORF) Prediction
+
+Run `Prodigal` on all representative SGB genomes (as output by `humann4-sgb-aggregation`) to predict ORFs. Extract both the nucleotide and translated amino acid sequences.
+
+### Step 2: Intermediate UniRef Alignment
+
+Use `DIAMOND` to align all predicted protein sequences against the standard `UniRef90` and `UniRef50` databases.
+
+For any ORF that matches an existing UniRef90 cluster (meeting the minimum thresholds of ≥90% identity and ≥80% coverage), assign it to that established cluster.
+
+### Step 3: De Novo Clustering of Unmapped ORFs
+
+For ORFs that fail to map to standard UniRef clusters, perform *de novo* clustering using `MMseqs2`. Cluster these sequences at a 90% identity threshold to create novel protein families.
+
+Name these newly generated clusters using the convention: `SGB_Ref90_XXXX` (where XXXX is a unique identifier).
+
+### Step 4: Generate ORF Mapping File
+
+Compile a comprehensive TSV mapping file linking every original ORF ID (from all SGBs) to its assigned `UniRef90` ID or its novel `SGB_Ref90` ID.
+
+## Notes
+
+- **HPC Cluster Scalability:** Predicting ORFs and performing all-against-UniRef alignment across millions of SGB genes requires high-memory cluster nodes and multi-threaded MMseqs2/DIAMOND jobs.
+- This protocol bridges the gap between characterized UniProt proteins and novel ORFs discovered via large-scale MAG assembly in MetaPhlAn 4.2.
+
+

protocols/humann4-chocophlan-build/protocol.md

@@ -0,0 +1,67 @@
+---
+name: humann4-chocophlan-build
+description: Construct the HUMAnN 4 ChocoPhlAn nucleotide pangenome database.
+version: 1.0.0
+authors:
+  - name: Levi Waldron
+    orcid: 0000-0003-2725-0694
+date: 2026-08-08
+status: draft
+license: CC-BY-4.0
+type: atomic
+
+protocol_doi: ~
+repository_doi: ~
+publication_doi: ~
+
+citation: "10.7554/eLife.65088"
+
+upstream_repositories:
+  - "https://github.com/biobakery/humann"
+  - "https://github.com/biobakery/metaphlan"
+
+database_urls:
+  - "http://huttenhower.sph.harvard.edu/humann_data/chocophlan/"
+  - "http://cmprod1.cibio.unitn.it/databases/chocophlan/"
+
+protocols_used: []
+key_packages: []
+category: metagenomics
+tags: [humann, chocophlan, database, pangenome, bowtie2]
+---
+
+# HUMAnN 4 ChocoPhlAn Build
+
+This protocol constructs the ChocoPhlAn 4 nucleotide pangenome database, formatting it for `bowtie2` mapping in the HUMAnN 4 pipeline.
+
+## Materials
+
+- **Software & Repositories:**
+  - `bowtie2` ([BenLangmead/bowtie2](https://github.com/BenLangmead/bowtie2)) — Ultrafast nucleotide aligner and index builder.
+  - `humann` ([biobakery/humann](https://github.com/biobakery/humann)) — Primary consumer and database management scripts (`humann/tools/`).
+- **Databases & Reference Data:**
+  - Previous ChocoPhlAn Database Builds ([HUMAnN Data Server](http://huttenhower.sph.harvard.edu/humann_data/chocophlan/)) — Full and demo nucleotide pangenome releases for HUMAnN 3.
+  - Segata Lab ChocoPhlAn Database ([Segata Lab Server](http://cmprod1.cibio.unitn.it/databases/chocophlan/)) — Upstream microbial pangenome repository.
+
+## Steps
+
+### Step 1: Pan-proteome Compilation
+
+For each MetaPhlAn 4.2 SGB, identify its pan-proteome: the comprehensive set of all unique `UniRef90` and `SGB_Ref90` protein families present across the SGB's representative genomes.
+
+### Step 2: Nucleotide Sequence Selection
+
+For every protein family present in a given SGB's pan-proteome, select one representative nucleotide ORF sequence from the SGB's member genomes.
+
+### Step 3: FASTA Concatenation and Indexing
+
+Concatenate the representative nucleotide sequences into a single SGB-specific pangenome FASTA file.
+
+Build a `bowtie2` index for each SGB pangenome FASTA to finalize the ChocoPhlAn database structure.
+
+## Notes
+
+- **Run-Time Dynamic Indexing:** The resulting `bowtie2` indexes are the primary mapping targets for the initial nucleotide-level search step in HUMAnN. At runtime, HUMAnN extracts and combines only the pangenomes of species identified in the sample's MetaPhlAn profile.
+- Databases generated by this protocol can be installed locally or configured using `humann_config --update database_folders chocophlan <path>`.
+
+