Step 6: Mapping File Usage Guidelines

Step 5 produces three output files representing increasing reaction coverage. All three share the same underlying logic: EC and Pfam determine when a reaction is resolved; UniProt-Accession (UniProtKB accession) gene families are pooled into the assignment at whichever stage that happens. Reactions with no EC and no Pfam hit exit last, carrying UniProtKB accession only assignments.

---

The Three Output Files

1. RXN_GF-ECbasedMapping.txt

Reactions resolved by EC number. UniProtKB accession gene families are pooled in where the reaction also has a UniProt accession match. EC-based assignments generalise broadly across organisms, making this the most consistent file for cross-sample comparisons.

Use when: cross-sample consistency matters more than coverage. Excludes: reactions with no EC annotation or no EC match in the database.

---

2. RXN_GF-ECplusExactPFAMsetbasedMapping.txt

Adds reactions resolved by exact Pfam set matching (EC residuals only). UniProtKB accession gene families are pooled in where applicable. Pfam matching is exact: a gene family is assigned only when its domain composition is identical to the query set — same domains, same count, any order.

Use when: EC-only coverage is insufficient and your reactions have well-defined Pfam signatures. Excludes: reactions with no EC and no exact Pfam match, even if they carry UniProtKB accession assignments.

---

3. RXN_GF-all.txt

Adds reactions resolved by UniProtKB accession only — those with no EC hit and no Pfam hit but with a direct UniProt accession link in BioCyc. These assignments are protein-specific rather than class-generalised, making them less portable across organisms but fully supported by BioCyc curation.

Use when: maximum coverage is required and protein-specific assignments are acceptable. Excludes: nothing within pipeline scope — reactions with no EC, Pfam, or PA link cannot be resolved.

---

At a Glance

File	Resolved by	PA pooled?	Coverage
RXN_GF-ECbasedMapping.txt	EC	Yes, where applicable	Lowest
RXN_GF-ECplusExactPFAMsetbasedMapping.txt	EC + Pfam	Yes, where applicable	Moderate
RXN_GF-all.txt	EC + Pfam + UniProtKB accession-only	Yes, where applicable	Highest

Each file is a strict superset of the one above it.

---

Using the mapping files with HUMAnN3

The aggregated RXN→gene-family (GF) files mentioned above are custom mapping files compatible with HUMAnN3. They can be supplied directly to (humann_regroup_table) with the -c/--custom flag to regroup a UniRef90 gene-family table into BioCyc/MetaCyc reactions. For example:

humann_regroup_table \
  -i sample_genefamilies.tsv \
  -c RXN_GF-all.txt \
  -o sample_rxn_all.tsv

Compatibility

These files map BioCyc/MetaCyc reactions to their corresponding UniRef90 gene families and are valid only when the gene-family table was generated against the UniRef90 2019_01 database (the uniref90_201901 / 201901b DIAMOND databases). This covers all HUMAnN 3.x releases (v3.0 through v3.9), which share the same UniRef90 2019_01 clustering and therefore produce gene families with matching UniRef90_* identifiers; the 201901b build is a re-annotation of the 2019_01 release and does not change cluster IDs or membership.

Previous: Step 5 — Aggregating Multi-Species Mappings