Skip to contents

Convert Gene Identifiers in an Expression Matrix

Source: R/convert_id.R
convert_id.Rd

Maps the row names of a gene expression matrix from one gene identifier system to another using the org.Hs.eg.db annotation database. Supports flexible aggregation strategies for many-to-one mappings, and optionally retains unmapped genes with NA row names.

Usage

convert_id(
  expr,
  from = "ENSEMBL",
  to = "SYMBOL",
  agg_fun = c("max", "mean", "median"),
  drop_unmapped = TRUE,
  show_stats = TRUE
)

Arguments

expr

A numeric gene expression matrix (or data frame) with genes in rows and samples in columns. Row names must be valid identifiers of the type specified by from.

from

Character string specifying the current gene identifier type. One of "SYMBOL", "ENSEMBL", "ENTREZID", or "REFSEQ". Default: "ENSEMBL".

to

Character string specifying the target gene identifier type. One of "SYMBOL", "ENSEMBL", "ENTREZID", or "REFSEQ". Default: "SYMBOL".

agg_fun

Character string specifying how to aggregate expression values when multiple source IDs map to the same target ID: "max" (default), "mean", or "median".

drop_unmapped

Logical. If TRUE (default), genes that cannot be mapped are removed from the output. If FALSE, unmapped genes are retained with their original row names.

show_stats

Logical. If TRUE (default), prints a mapping summary to the console showing the number of genes mapped, removed, and the mapping rate.

Value

A numeric matrix with the same columns as expr and row names converted to the target identifier type.

Details

Supported identifier types:

"SYMBOL"

Official HGNC gene symbols (e.g. TP53, EGFR).

"ENSEMBL"

Ensembl gene IDs (e.g. ENSG00000141510).

"ENTREZID"

NCBI Gene IDs (e.g. 7157).

"REFSEQ"

RefSeq mRNA accessions (e.g. NM_000546).

ENSEMBL version suffix handling: Row names with an Ensembl version suffix (e.g. "ENSG00000141510.11") are automatically stripped before lookup.

Aggregation strategy: When multiple source IDs map to the same target identifier (common when converting from transcript-level to gene-level), one of three strategies is used:

  • "max": keep the row with the highest expression value per sample (default, conservative for expression).

  • "mean": average expression across all source IDs per sample.

  • "median": median expression across all source IDs per sample.

Dependencies

This function requires the Bioconductor packages org.Hs.eg.db and AnnotationDbi. Install them with:


BiocManager::install(c("org.Hs.eg.db", "AnnotationDbi"))

Examples

if (FALSE) { # \dontrun{
# ENSEMBL to SYMBOL (most common use case)
data(TCGA_LUSC_ENSEMBL)
expr_symbol <- convert_id(TCGA_LUSC_ENSEMBL, from = "ENSEMBL", to = "SYMBOL")
head(rownames(expr_symbol))

# SYMBOL to ENTREZID, using mean for aggregation
data(TCGA_LUSC)
expr_entrez <- convert_id(TCGA_LUSC,
                           from = "SYMBOL",
                           to = "ENTREZID",
                           agg_fun = "mean")

# Keep unmapped genes
expr_keep <- convert_id(TCGA_LUSC_ENSEMBL,
                         from = "ENSEMBL",
                         to = "SYMBOL",
                         drop_unmapped = FALSE)
} # }