bulkrna-geneid-mapping

name	bulkrna-geneid-mapping
description	Gene identifier conversion between Ensembl, Entrez, HGNC symbols, and UniProt for bulk RNA-seq count matrices.
version	0.3.0
author	OmicsClaw
license	MIT
tags	["bulkrna","gene-id","mapping","Ensembl","Entrez","HGNC","annotation"]
requires	["numpy","pandas"]
metadata	{"omicsclaw":{"domain":"bulkrna","emoji":"🏷️","trigger_keywords":["gene ID","Ensembl","Entrez","gene symbol","ID mapping","gene annotation","convert IDs"],"allowed_extra_flags":["--from","--mapping-file","--on-duplicate","--species","--to"],"legacy_aliases":["bulk-geneid"],"saves_h5ad":false}}

Bulk RNA-seq Gene ID Mapping

Convert gene identifiers in bulk RNA-seq count matrices between major ID systems: Ensembl Gene IDs, Entrez Gene IDs, HGNC Symbols, and UniProt accessions. Features built-in mapping tables with optional mygene API fallback.

Core Capabilities

• Convert between Ensembl, Entrez, HGNC symbol, and UniProt identifiers
• Strip Ensembl version suffixes (ENSG00000141510.12 → ENSG00000141510)
• Handle duplicate gene symbols by summing counts (standard practice)
• Built-in mapping for human (GRCh38) and mouse (GRCm39); extensible via mygene API
• Report unmapped genes with fallback strategies
• Apply mapping directly to count matrices

Why This Exists

• Without it: Researchers manually download BioMart tables, write custom scripts to handle version suffixes, resolve duplicates, and cross-reference multiple ID systems.
• With it: A single command converts the entire count matrix index to the desired ID system with proper duplicate handling and unmapped gene reporting.
• Why OmicsClaw: Integrated into the bulkrna pipeline so IDs are harmonized before DE analysis, enrichment, or cross-study comparison.

Algorithm / Methodology

ID Resolution Pipeline

1. Strip version suffixes from Ensembl IDs (if applicable)
2. Apply primary mapping from built-in tables or mygene API query
3. Handle unmapped genes: keep original ID, drop, or mark as unmapped
4. Resolve duplicate target IDs by summing read counts per gene

Supported ID Types

Type	Example	Common Use
Ensembl Gene	ENSG00000141510	RNA-seq quantification, GTF annotation
Entrez Gene	7157	NCBI databases, KEGG pathways
HGNC Symbol	TP53	Human-readable, publications
UniProt	P04637	Protein databases

Input Formats

Format	Extension	Description
Count matrix	.csv	Genes as rows (any ID type), samples as columns
Mapping table	.tsv