Get started

In TCRconvertR: Convert TCR Gene Names

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

Installation

Install from CRAN:

install.packages("TCRconvertR")

Basic usage

1. Load TCRs into a data frame

Examples of files you may want to load:

• 10X: filtered_contig_annotations.csv
• Adaptive: Sample_TCRB.tsv
• IMGT: Output from MiXCR or other tools

library(TCRconvertR)

tcr_file <- get_example_path("tenx.csv") # Using built-in example file
tcrs <- read.csv(tcr_file)[c("barcode", "v_gene", "j_gene", "cdr3")]
tcrs

2. Convert

new_tcrs <- convert_gene(tcrs, frm = "tenx", to = "adaptive")
new_tcrs

Tip: Suppress messages by setting verbose = FALSE. Warnings and errors will still appear.

Tip: If your Adaptive data lacks x_resolved/xMaxResolved columns, create them yourself by combining the x_gene/xGeneName and x_allele/xGeneAllele columns. See the FAQs.

AIRR data

Supply the standard AIRR gene column names to frm_cols:

new_airr <- convert_gene(airr, frm = "imgt", to = "adaptive", 
                         frm_cols = c('v_call', 'd_call', 'j_call', 'c_call'))

Custom column names

By default, TCRconvertR assumes these column names based on the input nomenclature (frm):

• frm = 'imgt' : c('v_gene', 'd_gene', 'j_gene', 'c_gene')
• frm = 'tenx' : c('v_gene', 'd_gene', 'j_gene', 'c_gene')
• frm = 'adaptive' : c('v_resolved', 'd_resolved', 'j_resolved')
• frm = 'adaptivev2' : c('vMaxResolved', 'dMaxResolved', 'jMaxResolved')

You can override these columns using frm_cols:

1. Load 10X data with custom column names

custom_file <- get_example_path("customcols.csv")

custom <- read.csv(custom_file)
custom

2. Specify names using frm_cols and convert to IMGT

custom_new <- convert_gene(
  custom,
  frm = "tenx",
  to = "imgt",
  verbose = FALSE,
  frm_cols = c("myVgene", "myDgene", "myJgene", "myCgene"),
)
custom_new

Rhesus or mouse data

Use species = "rhesus" or species = "mouse"

new_tcrs <- convert_gene(
  tcrs,
  frm = "tenx",
  to = "imgt",
  species = "rhesus", # or 'mouse'
  verbose = FALSE
)
new_tcrs

TCRconvertR documentation built on June 8, 2025, 10:43 a.m.