gAIRR-wgs: high-resolution T cell receptor allele typing in biobank-scale whole-genome sequencing data

Abstract

T cell receptor (TR) genes are essential components of the adaptive immune receptor repertoire, and growing evidence links TR germline variants to immune-related diseases. However, their highly allelic diversity and sequence homology make them challenging dark regions of the human genome. Current TR genotyping tools have limited support for population-scale studies using standard-depth (30×) whole-genome sequencing (WGS), leaving a critical gap. We present germline Adaptive Immune Receptor Repertoire (gAIRR)-wgs, the first highly resource-efficient workflow specifically designed for high-resolution TR allele typing from short-read WGS. Benchmarking against 44 assembly-validated Human Pangenome Reference Consortium Release 1 subjects showed high overall accuracy performance across TR loci (mean F1/accuracy: 0.996/0.997), with comparable results in an independent cohort of 182 Release 2 individuals (0.984/0.988). Applying gAIRR-wgs to 1492 Taiwan Biobank (TWB) participants, we identified 450 novel TR alleles absent from the international ImMunoGeneTics (IMGT) information system database, accounting for 57.5% of all identified TR alleles and representing an ~102% expansion of the current IMGT TR repertoire—277 of which were cross-validated in non-East Asian cohorts—and 109 novel TR V alleles with allele frequencies >1% in the TWB. Notably, the tool uncovered population-specific structural polymorphisms, including T cell receptor gamma variable (TRGV) genes (TRGV4/TRGV5 deletions) and T cell receptor beta variable (TRBV) genes (TRBV3-2/TRBV4-3 insertion/deletion), which were overlooked by Illumina Dynamic Read Analysis for GENomics (DRAGEN). Furthermore, we identified 34 TR genes exhibiting significant allelic divergence between Taiwanese and global populations. By enabling accurate TR genotyping from 30× WGS data, gAIRR-wgs effectively unlocks the immunogenomic potential of massive biobank resources, bridging the gap between standard genomic surveys and adaptive immune repertoire analysis.

Graphical Abstract

Graphical Abstract.

Introduction

T cell receptors (TCRs), together with immunoglobulins which include both membrane-bound B cell receptors and soluble antibodies, form the adaptive immune receptor repertoires, the foundation of adaptive immunity. TCRs enable T cells to recognize antigens presented by human leukocyte antigens, driving cell-mediated immune responses. TCRs consist of α:β or γ:δ peptide chains, encoded by T cell receptor (TR) genes, including T cell receptor alpha (TRA), T cell receptor beta (TRB), T cell receptor gamma (TRG), and T cell receptor delta (TRD), which are located at distinct genomic loci: TRA and TRD are co-located on chromosome 14, TRB and TRG reside on chromosome 7, and an additional orphan TRB locus is located on chromosome 9. Each TR locus is composed of multiple gene segments: variable (V), diversity (D), and joining (J), which undergo somatic recombination to form functional TR genes during T cell development in the thymus. All TR loci contain V and J gene segments, while TRB and TRD additionally possess D gene segments. Within each locus, multiple copies of V, D, and J genes are arranged either in clusters or interspersed along the chromosome, and each gene can exist as multiple allelic variants. The germline TR (gTR) repertoire refers to the set of unrearranged V, D, and J gene segments that collectively generate TR diversity through recombination. The international ImMunoGeneTics (IMGT) information system database serves as the nomenclature authority and central repository for gTR genes, providing curated reference sequences based primarily on core coding regions [1]. In this study, we classify gTR genes by segment type, given that genes within each segment category share similar lengths and intrinsic sequence complexity: TR_V refers to all variable genes across all TR loci, while TR_D and TR_J represent the diversity and joining genes, respectively. The functional diversity arising from gTR recombination manifests as the expressed adaptive immune receptor repertoire (exprAIRR), which has been widely associated with disease susceptibility, clinical progression, and prognosis. Non-randomly selected gTR gene combinations have been observed across a wide range of diseases, including autoimmune diseases [2–9], infectious diseases [10–19], severe cutaneous adverse reactions [20], and various cancers [5, 21–25]. Despite growing evidence for the role of exprAIRR in diseases, the impact of gTR allele variation remains insufficiently studied. Distinct gTR allelic forms of the same gene can lead to altered V(D)J recombination outcomes, including the production of nonfunctional transcripts or pseudogenes, thereby directly affecting gene availability, contributing to non-random gene usage, and ultimately shaping immune responses and disease susceptibility [26, 27]. Current approaches for gTR allele identification can be broadly categorized into two methodologies: inference from rearranged transcripts (exprAIRR) and direct calling from germline DNA sequences. While transcript-based methods capture expressed repertoires, they cannot comprehensively assess the complete germline allelic diversity, as not all alleles are necessarily expressed or detectable in a given sample. Direct germline calling from whole-genome sequencing (WGS) data offers a more complete view of gTR variation; however, the high sequence similarity among TR gene segments poses substantial challenges for accurate allele identification from short-read technologies. Existing gTR-calling tools include gAIRR-Suite and ImmunoTyper2. The gAIRR-Suite has demonstrated promising performance but is primarily optimized for targeted panel sequencing at ultra-high depth (>500×), making it incompatible with standard WGS data (~30×) [28]. This limitation is particularly significant given that biobanks offer an unprecedented opportunity to explore population-level gTR diversity, with most containing individual short-read WGS data at moderate sequencing depth (~30×) [29–35]. While individual-level gTR variants impact immune function, population-level variation provides essential biological context—not only establishing the baseline diversity against which individual deviations are interpreted, but also revealing patterns shaped by evolutionary selection and population-specific immune pressures. However, accurate TR allele identification from standard-depth short-read WGS remains challenging, particularly at biobank scale. Although ImmunoTyper2 was recently introduced for short-read WGS genotyping, its support is limited to TR_V genes, and scalability for large population studies remains constrained by computational demands and dependence on a commercial solver [36]. To address this critical gap, we developed gAIRR-wgs, a WGS-compatible module for gAIRR-Suite, to bring high-accuracy TR allele identification to standard-depth biobank data.

Materials and methods

gAIRR-wgs pipeline development

We developed gAIRR-wgs as a new algorithmic workflow within gAIRR-Suite for TR genotyping from standard short-read WGS data. Distinct from the panel-oriented module gAIRR-call [28], gAIRR-wgs was designed under a substantially different algorithmic framework tailored for WGS; key methodological differences are summarized in Supplementary Method S1.

Read extraction

WGS reads were first aligned to the Genome Reference Consortium Human Build 38 (GRCh38) reference genome with decoy sequences and human leukocyte antigen sequences (hs38DH) using the Burrows–Wheeler Aligner Maximal Exact Matches (BWA-MEM) algorithm (v.0.7.17) [37]. Target reads covering TR gene loci were extracted, including both mapped reads from target regions and unmapped reads to account for potential reference genome discrepancies. Note that the runtime reported for gAIRR-wgs refers to the allele calling module following read extraction and does not include the initial whole-genome BWA-MEM alignment step.

Reference database construction

The TR allele reference database was constructed based on the IMGT database, with TR gene sequences last updated in 2025 (accessed on October 2025) [38]. The database was then expanded by incorporating 335 novel TR alleles previously identified and validated from 47 Human Pangenome Reference Consortium (HPRC) personal genome assemblies, with 50 bp consensus-based flanking sequences appended to each allele [39].

Allele calling and depth calculation

gAIRR-wgs follows a two-step BWA-MEM alignment process: candidate novel alleles identified in the first round are incorporated into the reference database before a second alignment to prevent hybridized artifact formation. Allele depth is calculated using a weighted minimum-coverage model integrating both single-end and paired-end reads across core gene regions, with paired-end support additionally required to validate structurally complex alleles. Full implementation details and parameter optimization are described in Supplementary Method S1.

Benchmark study

The gAIRR-wgs pipeline was benchmarked using short-read WGS data from 44 HPRC individuals (Supplementary Method S2). TR allele annotations derived from validated haplotype-resolved personal genome assemblies were used as the ground truth, encompassing both IMGT-documented and novel alleles absent from the IMGT database [39]. To assess generalizability, the pipeline was additionally evaluated on 182 individuals from HPRC Release 2, with ground-truth annotations derived computationally using the gAIRR-annotate pipeline (Supplementary Method S2).

For each subject, a predicted allele was counted as a true positive (TP) if it matched a ground-truth allele; an unmatched predicted allele was counted as a false positive (FP); a ground-truth allele without a corresponding prediction was counted as a false negative (FN); and a true negative (TN) was defined as an allele that was neither present in the subject’s ground truth nor predicted by the pipeline. Novel alleles were compared based on core sequence identity, with specific exclusions for allele pairs indistinguishable by short-read sequencing (Supplementary Method S2). Recall, precision, F1 score, and accuracy were computed as follows:

Population study

Study cohort and data processing

The population analysis included 1492 individuals from the Taiwan Biobank (TWB) with Illumina-based WGS data [paired-end 150 bp reads, sequenced using HiSeq 2500 (n = 555), HiSeq 4000 (n = 634), and NovaSeq 6000 (n = 303)] derived from peripheral blood mononuclear cell DNA samples [35]. Short-read and alignment data and the variant callset for the TWB cohort were accessed under ethical approval TWBR11106-05.

Raw data were provided in Compressed Reference-oriented Alignment Map (CRAM) format and processed using our read extraction pipeline to obtain TR-specific reads prior to gAIRR-wgs analysis. The GRCh38 Browser Extensible Data (BED) reference used for targeted TR allele analysis is publicly available at https://github.com/maojanlin/gAIRRsuite.

Variant validation and database comparisons

For variant-based validation, all novel alleles were aligned to the GRCh38 reference genome (hs38DH) using BWA-MEM with secondary alignments excluded. Novel allele sequences were converted to variant format relative to GRCh38, various Concise Idiosyncratic Gapped Alignment Report (CIGAR) operations including matches (M), insertions (I), deletions (D), substitutions, and clipping events (S, H) were processed alongside MD tags, which records mismatching positions relative to the reference genome, to accurately identify sequence differences and generate reference allele (REF) and alternative allele (ALT) variant calls for comparison with the TWB DRAGEN variant callset (version 4.0.3). Variants were validated based on concordance in genomic positions, allele sequences, and genotype calls with adequate coverage depth (detailed validation criteria in Supplementary Method S3). For reference blocks (regions marked with <NON_REF > in ALT field representing sequences identical to the reference genome), validation was performed by confirming the absence of variant calls within the corresponding genomic intervals.

Structural variant (SV) analysis was conducted using results generated by the DRAGEN pipeline (version 4.0.3) on the TWB WGS dataset. For regions with potential structural variants identified through gene absence patterns, corresponding genomic intervals were systematically queried in the DRAGEN SV callset to identify overlapping or similar-length structural variants. SV calls were considered concordant when: (i) genomic coordinates showed substantial overlap with predicted deletion/insertion regions, and (ii) variant sizes were within reasonable similarity ranges of the expected structural changes based on gene absence frequencies and genomic context.

Shannon’s diversity index calculation

We calculated Shannon’s diversity index for each TR gene locus across all populations to quantify allelic richness and evenness within populations using the formula:

where p_i represents the proportion of individuals carrying allele i, and S is the total number of alleles for a given gene. The Shannon’s diversity index ranges from 0 ≤ H′ ≤ ln(S), where H′ = 0 indicates a population dominated by a single allele (no diversity), and higher values indicate greater allelic diversity. We used the first quartile (Q1) value of 0.4793 across all gene-population combinations as a threshold to define high-diversity genes.

Hellinger distance calculation

To quantify differences in allele frequency distributions between populations for each TR gene, we calculated Hellinger distance using the formula:

where P and Q represent allele frequency distributions for a given gene in two different populations, p_i and q_i are the frequencies of allele i in populations P and Q, respectively, and k is the total number of unique alleles observed across both populations. The Hellinger distance ranges from 0 to 1, where 0 indicates identical allele distributions between populations and 1 indicates completely different distributions. We used a threshold of H > 0.5 to identify genes with significantly different allele distributions between population pairs.

Statistical analysis and visualization

The core tool, gAIRR-wgs was primarily developed in Python (version 3.7.13). All the downstream analyses, including benchmark study and population study, were performed using Python (version 3.10.14) and R (version 4.4.0).

Read alignment visualization and validation were conducted using the Integrative Genomics Viewer (version 2.10.3; IGV) [40]. To ensure reproducibility and maintain environment consistency, all computational tools were managed using conda (version 24.11.3), with separate virtual environments created for each major component of the analysis pipeline.

Results

Development of the gAIRR-wgs pipeline for T cell receptor genotyping using whole-genome sequencing data

Accurate TR allele calling from WGS data faces three key challenges: lower read depth (~30×) compared to targeted sequencing, shorter read lengths (150 bp), and limited paired-end information utilization within TR gene structures (Supplementary Fig. S1). gAIRR-wgs incorporates four design innovations targeting these challenges (Fig. 1 and Supplementary Method S1).

Figure 1.

Overview of the gAIRR-wgs pipeline for TR allele calling from WGS data; TR-related reads were extracted from WGS data (top left; ①), and the allele reference database was expanded by incorporating novel alleles from HPRC release 1 subjects (top; ②) and appending consensus-based flanking sequences (top right; ③); reads were then aligned to the expanded database to identify both candidate novel alleles and IMGT-documented alleles (top; ④); allele support was quantified using a weighted depth model that integrates both single-end and paired-end reads, with depths calculated either within customized depth-defining regions for each allele (bottom left; ⑤); hybridized-structured alleles were further validated by requiring proper paired reads to support all key distinguishing variants (bottom right; ⑥).

First, a targeted read extraction strategy improves computational efficiency, enabling per-sample analysis in 12–15 min with ~5 gb memory usage (Supplementary Fig. S2). Second, the TR reference database was expanded with 335 HPRC-validated novel alleles and 50 bp consensus-based flanking sequences derived from HPRC assemblies, improving read mapping specificity while retaining flexibility for individual-specific flanking variants [39] (Supplementary Figs S1 and S3). Third, variants supported by ≥25% of reads and located within IMGT-defined core gene regions were used to infer candidate novel alleles, which were subsequently appended to the expanded TR reference database [41]. Fourth, to suppress FP calls arising from two classes of structurally complex alleles—hybridized-structured alleles (where reads from the 5′ and 3′ regions map preferentially to different alleles of the same gene; Supplementary Table S1) and nested-structured alleles (where the core sequence of one allele is identical to a subsequence of another; Supplementary Table S2)—allele depth was quantified using customized depth-defining regions that assign higher weight to core-region variants, which are allele-deterministic, while retaining flanking-region reads with reduced weight to accommodate inter-individual variation; paired-end concordance across key distinguishing variants was additionally required to confirm hybridized alleles.

Benchmarking demonstrates high accuracy of the gAIRR-wgs pipeline

The gAIRR-wgs pipeline was benchmarked against 44 HPRC subjects with validated TR annotations from personal genome assemblies. When gAIRR-call, originally designed for targeted sequencing, was directly applied to WGS data, it achieved suboptimal performance, demonstrating limitations of panel-optimized algorithms on WGS data (Table 1 and Supplementary Table S3). In contrast, gAIRR-wgs achieved excellent overall performance across all TR loci (mean F1 = 0.996, mean accuracy = 0.997), with recall/precision/accuracy of 1.000/1.000/1.000 for TR_D, 0.999/0.999/0.999 for TR_J, and 0.992/0.996/0.996 for TR_V genes. These allele calls were further corroborated by orthogonal high-depth targeted sequencing data (Supplementary Fig. S4). Performance remained robust for both IMGT-documented alleles (recall ≥0.997, precision ≥0.981) and novel alleles (recall ≥0.983, precision ≥0.939), and even exceeded the performance of gAIRR-call on high-depth targeted sequencing data. To further assess generalizability, gAIRR-wgs was independently evaluated on 182 individuals from HPRC Release 2. Performance remained consistently high across all TR gene categories with a mean F1 of 0.984 and mean accuracy of 0.988 (Table 1 and Supplementary Table S3). Together, these results across 226 individuals from two independent cohorts confirm the robustness and generalizability of gAIRR-wgs.

Table 1.

Benchmarking performance of gAIRR-wgs across sequencing platforms and independent cohorts.

Gene	HPRC cohort	Data type	Tool	Recall		Precision		F1 score
				AV	SD	AV	SD	AV	SD
TR_D	Release 1 (n = 44)	Panel 300	call	92.8	9.2	98.7	4.8	95.4	6.0
		Panel 150	call	94.2	9.0	98.7	4.8	96.2	6.0
		WGS	call	72.5	17.6	100.0	0.0	82.9	12.0
		WGS	wgs	100.0	0.0	100.0	0.0	100.0	0.0
	Release 2 (n = 182)	WGS	wgs	99.9	1.2	99.9	1.2	99.9	0.9
TR_J	Release 1 (n = 44)	Panel 300	call	100.0	0.2	96.6	2.0	98.3	1.0
		Panel 150	call	99.9	0.2	93.3	2.3	96.5	1.2
		WGS	call	96.2	2.2	99.3	0.8	97.7	1.3
		WGS	wgs	99.9	0.3	99.9	0.4	99.9	0.2
	Release 2 (n = 182)	WGS	wgs	99.6	0.8	99.7	0.7	99.7	0.6
TR_V	Release 1 (n = 44)	Panel 300	call	100.0	0.1	83.3	3.9	90.9	2.3
		Panel 150	call	100.0	0.2	78.9	6.9	88.0	4.4
		WGS	call	75.4	4.2	91.4	1.9	82.6	2.9
		WGS	wgs	99.2	0.9	99.6	0.4	99.4	0.5
	Release 2 (n = 182)	WGS	wgs	97.0	1.6	98.5	0.9	97.7	1.0

Abbreviations: AV = average value; SD = standard deviation, both calculated across 44 HPRC subjects and reported as percentages (%). Panel 150 and Panel 300 refer to targeted sequencing data with paired-end 150 and 300 bp reads, respectively; both were analyzed using gAIRR-call (a pipeline for targeted sequencing). WGS (call) indicates WGS data (paired-end 150 bp) analyzed using gAIRR-call, while WGS (wgs) indicates the same WGS data analyzed using the gAIRR-wgs pipeline.

To assess robustness under incomplete databases, we evaluated performance after randomly removing 10%, 30%, 50%, 70%, or 100% of TR_V and TR_J novel alleles from the individual reference database. TR_J genes maintained stable performance under 30% removal, while TR_V genes showed greater vulnerability, with recall dropping substantially when ˃10% of novel alleles were removed (Supplementary Fig. S5 and Supplementary Table S4). These findings confirm that incorporating previously discovered novel alleles is essential for robust allele calling, and highlight that incomplete databases critically constrain performance, particularly for highly diverse gene families like TR_V.

To verify robustness across sequencing depths, we performed downsampling analysis on 15 HPRC Release 2 samples with TR locus coverage ≥50× (median depth 52–63). Precision remained at or near 1.000 across all coverage levels for all gene segments, confirming that gAIRR-wgs maintains high specificity regardless of sequencing depth. As expected, recall decreased progressively with lower coverage, reflecting reduced availability of uniquely informative reads. A recall threshold of ≥0.95 was achieved at ~10× for TR_D, 15× for TR_J, and 30× for TR_V. At standard biobank WGS depth (~30×), all three segments maintained robust performance: TR_D achieved perfect recall, precision, and F1 (1.000), TR_J maintained recall of 0.996, precision of 0.998, and F1 of 0.997, and TR_V achieved recall of 0.951, precision of 0.990, and F1 of 0.970 (Supplementary Fig. S6 and Supplementary Table S5).

Comparative analysis against ImmunoTyper2 across 44 HPRC subjects revealed several advantages of gAIRR-wgs [36] (Fig. 2 and Supplementary Table S6). Novel alleles were excluded from this comparison as ImmunoTyper2 reports novel variants without haplotype-level allele assignment. For IMGT-documented alleles, while recall was broadly comparable between the two tools, gAIRR-wgs achieved substantially higher precision across all TR_V loci (0.98 versus 0.82 overall), resulting in fewer FP calls. In addition, gAIRR-wgs provides comprehensive genotype analysis of all TR gene segments (TR_V, TR_D, and TR_J), whereas ImmunoTyper2 is restricted to TR_V. Finally, gAIRR-wgs was ~28-fold faster in processing all 44 HPRC samples, requiring a total of 06:42:50 versus 7–19:51:01 central processing unit (CPU) time.

Figure 2.

Comparative performance of gAIRR-wgs and ImmunoTyper2 across TR_V gene types; F1 score, recall, and precision were evaluated for gAIRR-wgs using either the extended reference database (new_db) or the original IMGT database (IMGT_db), and compared with ImmunoTyper2; results are shown for overall performance and stratified by gene type (TRAV, TRBV, TRGV, and TRDV); bar plots display mean values across 44 HPRC subjects; both tools achieved high recall, but gAIRR-wgs demonstrated consistently higher precision, particularly when using our expanded database.

gAIRR-wgs reveals the comprehensive T cell receptor allele landscape of the Taiwan Han Chinese population using Taiwan biobank whole-genome sequencing data

We applied gAIRR-wgs to analyze TR alleles from 1492 TWB individuals, revealing comprehensive TR diversity in the Han Chinese population. Our analysis identified numerous high quality novel alleles, supported by high-quality reads [mapping quality (MAPQ) ≥20, alignment score (AS) ≥150], not present in the IMGT database (Fig. 3 and Supplementary Fig. S7). In total, 450 novel alleles were identified, accounting for 57.5% (450/782) of all TR genotypes observed in the cohort and representing an ~102% expansion (450/441) relative to the current IMGT database. All novel alleles were systematically renamed using the IgLabel tool to ensure standardized nomenclature [42]. On average, each individual carried 185.9 (±9.4) TR_V alleles including 34.6 (±5.5) novel TR_V alleles, 88.5 (±1.9) TR_J alleles with 2.6 (±1.2) novel TR_J alleles, and either 5 (64.1%) or 6 (35.9%) TR_D alleles with minimal novel variants (Table 2 and Supplementary Table S7). Notably, 109 novel TR_V alleles and 15 novel TR_J alleles exhibited cohort frequencies exceeding 1%, indicating substantial prevalence rather than rare variants. Among high-frequency alleles (>1%), novel alleles accounted for 18.39% of the TR_V repertoire and 2.77% of the TR_J repertoire.

Figure 3.

Cohort frequency distribution of TR_J and TR_V alleles in the TWB; cohort frequency distributions of TR_J (left) and TR_V (right) alleles identified in TWB subjects; the Y-axis represents the cohort frequency, defined as the proportion of individuals carrying each specific allele; the X-axis lists individual alleles, sorted in descending order by cohort frequency. Bars are categorized according to discovery status and are displayed using distinct colors and symbols: IMGT-documented alleles (blue, no symbol); alleles previously discovered in HPRC subjects (green, *); and alleles identified only in the TWB (red, ○).

Table 2.

Summary of TR_V and TR_J alleles identified in the TWB cohort.

		Total (IMGT + novel)	Novel
			Proportion	Novel  TWB	Novel  HPRC
TR_J	Allele type	167	44.31% (74)	26.95% (45)	17.37% (29)
	Weighted	131 995	2.90% (3823)	0.18% (239)	2.72% (3584)
TR_V	Allele type	608	61.68% (375)	20.89% (127)	40.79% (248)
	Weighted	277 306	18.62% (51 642)	0.11% (307)	18.51% (51 335)

“Allele type” represents 1D analysis based solely on allele type. “Weighted” analysis incorporates both allele type and cumulative carrier count across TWB subjects. Values in parentheses indicate the absolute number of alleles or total carriers contributing to each category. “Total” includes both IMGT-annotated alleles and novel alleles. Novel alleles refer to those not present in the current IMGT database, encompassing alleles observed exclusively in TWB as well as those previously identified in the 47 HPRC subjects [39].

Validation through IGV visualization and DRAGEN variant calling confirmed these findings. Remarkably, many novel alleles were not detected by DRAGEN, highlighting the necessity for specialized approaches to address the unique challenges of TR loci, consistent with DRAGEN’s locus-specific algorithms developed for complex genes, such as human leukocyte antigen (HLA) and cytochrome P450 family 2 subfamily D member 6 (CYP2D6) (Supplementary Fig. S8 and Supplementary Table S8) [43]. Frequency-based categorization revealed substantial database incompleteness: in the 10%–50% frequency group, 42.4% of TR_V genes were dominated by novel alleles rather than IMGT-documented variants, with ^*01 and ^*02 alleles each representing only ~20% (Fig. 4 and Supplementary Fig. S9). This pattern indicates that many common TR genes lack proper reference documentation.

Figure 4.

Distribution of star alleles across TR gene segments grouped by cohort frequency; (A), (B), and (C) show TR_D, TR_J, and TR_V genes, respectively; proportional distributions of dominant star alleles across TR gene segments in the TWB cohort, grouped by cohort frequency; each gene was assigned to one of six frequency intervals as shown along the X-axis; the Y-axis represented the proportion of genes within each frequency category that were dominated by a given star allele type; each bar was colored by star allele type, with allele assignments based on either direct IMGT annotation or novel allele grouping (e.g. ^*01_novel was used to represent novel alleles most similar to the canonical ^*01); these plots illustrated how allelic composition shifted across frequency categories, revealing evolutionary patterns of conservation and diversification in different TR segments; while high-frequency groups were dominated by conserved alleles such as ^*01, lower-frequency groups increasingly featured novel alleles, particularly ^*01_novel, reflecting ongoing diversification and potential adaptive emergence within the population.

Among common alleles (>1% cohort frequency), 34.17% of TR_V genes (109/319) and 14.02% of TR_J genes (15/107) were dominated by novel alleles (Fig. 5A and Supplementary Table S7). Most high-frequency novel alleles were validated in HPRC subjects representing diverse global ancestries (Supplementary Table S9), confirming they reflect broader human TR diversity missing from databases rather than population-specific variants. Extended analysis of 232 HPRC subjects revealed that some novel alleles were present in East Asian (EAS) and South Asian (SAS) populations (Fig. 5B and C and Supplementary Table S10). This progression from apparent population specificity to broader presence underscores historical underrepresentation of Asian populations in immunogenomic resources and emphasizes the importance of diverse population sampling for comprehensive TR characterization.

Figure 5.

Distribution of novel TR alleles across populations; novel alleles were identified from the TWB cohort using the gAIRR-wgs genotyping pipeline; each bar in the upper panel represents the number of genes carrying novel alleles observed across specific population combinations, with colors indicating gene categories (e.g. AV, AJ, BV, etc.); the lower panel is an UpSet plot summarizing population sharing patterns for these novel alleles across cohorts including TWB, AFR, North American, South American, EAS, SAS, and EUP; the left margin indicates the total number of novel alleles and sample size per cohort; (A) novel alleles in TWB were compared against 47 HPRC subjects based on high-confidence annotations from the first HPRC assembly release, using the gAIRR-annotate pipeline with manual validation by long-read alignments; (B) novel alleles in TWB were compared against 232 HPRC subjects from the second HPRC assembly release, annotated by gAIRR-annotate without long-read-based manual validation; (C) common novel alleles (>1% frequency) initially appearing to be TWB-specific in the first HPRC release were identified in EAS and SAS populations within the larger set of 232 HPRC subjects from the second release.

Identification of structural deletion polymorphisms in T cell receptor gene loci

Analysis of TR gene presence across 1492 TWB subjects revealed four genes with missing rates >2%: TRGV5 (2.95%), TRGV4 (5.03%), TRBV3-2 (37.13%), and TRBV4-3 (38.50%) (Supplementary Fig. S9). These substantial missing rates suggested structural deletion polymorphisms rather than technical artifacts.

TRGV4 and TRGV5 are physically adjacent on chromosome 7, while TRBV3-2 and TRBV4-3 are located on alternative contig chr7_KI270803v1_alt. Validation through alignment data examination revealed complete absence of read support in affected individuals, with coverage dropouts spanning ~9 kb (TRGV4/TRGV5) and ~21 kb (TRBV3-2/TRBV4-3) (Fig. 6 and Supplementary Fig. S10). Identical patterns in Dynamic Read Analysis for GENomics Mapper (DRAGMAP)-generated alignments confirmed genuine deletion events.

Figure 6.

IGV visualization of structural variation at TRG and TRB loci in representative TWB WGS samples; (A) TRGV4/TRGV5 deletion polymorphism; read alignments from GATK-processed WGS data mapped to GRCh38 are shown; affected individuals exhibit complete absence of read coverage across the TRGV4 and TRGV5 region, with sharp dropouts in depth, indicating a homozygous deletion; genes TRGV4 and TRGV5 are physically adjacent on chr7, separated by ~4.1 kb; below, comparison with SV databases highlights the expected deletion interval (boxed region), with TWB carrier frequencies indicated (present: 97.7%, absent: 2.28%); (B) TRBV3-2/TRBV4-3 insertion/deletion polymorphism; in a representative deletion haplotype, no read coverage is observed at the positions of TRBV3-2 and TRBV4-3 (~21 kb span), while neighboring genes TRBV4-2 and TRBV7-2 retain full coverage, consistent with their stable presence; read alignment visualizations were generated using IGV; SV database comparison is shown below, with the predicted deletion interval indicated by the boxed region and TWB carrier frequencies annotated.

Our findings corroborate previous reports of genomic deletions in the TRGV4/TRGV5 region [44]. Using gAIRR-wgs, we identified a 2.28% homozygous carrier rate for absence of both genes in TWB, consistent with a ~9 kb deletion encompassing both loci (Fig. 6). Comparison with the Genome Aggregation Database (gnomAD) SVs (v4.1.0) revealed discrepancies, likely reflecting that TR regions fall outside high-confidence callable regions for conventional variant callers. The absence patterns of TRBV3-2 and TRBV4-3 align with previously described 21.5 kb insertion/deletion polymorphism in the TRBV locus [27, 45]. Our analysis revealed 38.20% of TWB individuals carried homozygous deletion (absence on both haplotypes), while 57.91% carried the insertion haplotype. HPRC analysis showed 34.48% homozygous deletion, with highest proportions in African (AFR, 12.93%), SAS (9.48%), and EAS (3.45%) populations (Supplementary Table S11). gnomAD comparison identified a 10.5 kb duplication in EAS (~54.72% frequency), though technical limitations prevent accurate sizing of the full ~21 kb insertion. Comparison with DRAGEN Manta SV caller on the same TWB dataset identified no corresponding structural variants (Supplementary Tables S12 and S13), underscoring the difficulty of resolving complex immune gene regions using conventional SV callers and highlighting the necessity for specialized approaches.

Population-specific T cell receptor allele distribution patterns and diversity analysis

To systematically characterize population-specific patterns of TR allele diversity, we analyzed allele distributions across TWB and 232 HPRC subjects representing six global populations: AFR (n = 70), North American (n = 16), South American (n = 28), EAS (n = 33), SAS (n = 54), and European (EUP, n = 31) (Supplementary Fig. S11).

We employed Hellinger distance calculations to quantify differences in allele frequency distributions between populations, with a threshold of >0.5 indicating significant distributional differences. Overall, 57 TR genes (56 TR_V and 1 TR_J) showed significant distributional differences in at least one population comparison (Supplementary Fig. S12 and Supplementary Table S14). The AFR population showed the most distinctiveness, with 50 genes exhibiting significant differences, while TWB exhibited 34 genes with significant differences compared to other global populations.

Among the TWB cohort, seven TR_V genes showed particularly pronounced differences: TRBV20-1, TRAV6, TRAV35, TRBV7-5, TRAV12-2, TRAV8-4, and TRBV5-5. When comparing TWB specifically with the EAS population, most TR genes showed similar allele distributions, reflecting shared ancestry. However, eight TR_V genes maintained significant distributional differences even within this regional comparison, including the seven genes mentioned above plus TRAV38-1, suggesting population-specific evolutionary pressures or founder effects within EAS subpopulations.

Shannon’s diversity index analysis identified 104 TR genes with high allelic diversity across the seven cohorts (Supplementary Fig. S13 and Supplementary Table S15). AFR populations exhibited the highest overall diversity with 84 high-diversity genes, consistent with established patterns of greater genetic diversity in AFR populations. In contrast, TWB showed the lowest diversity with only 47 high-diversity genes. Notably, 25 TR genes (24 TR_V and 1 TR_J) maintained consistently high diversity across all cohorts, representing core genes with universally preserved allelic richness. Conversely, six TR_V genes showed high diversity in other populations but reduced diversity in TWB, potentially indicating population-specific bottlenecks or selective pressures.

Consistent with earlier findings regarding limited allelic variation in TR_D segments, diversity analysis revealed that most TR_D genes were dominated by single prevalent alleles across populations (Supplementary Fig. S9). However, TRBD2 emerged as a notable exception, exhibiting the highest Shannon’s diversity index among all TR_D genes, suggesting that while most TR_D segments are highly conserved, TRBD2 maintains functional diversity that may be important for TR functionality.

Discussion

This study addresses a critical gap in immunogenomics by developing a specialized pipeline for accurate TR allele calling from standard biobank-scale WGS data. Our gAIRR-wgs pipeline overcomes fundamental limitations through targeted read extraction, enhanced reference databases incorporating population-specific diversity, and optimized algorithms that prevent hybridized artifacts while maintaining high sensitivity. Performance was robust across two independent HPRC cohorts; notably, the slight reduction in TR_V recall in the Release 2 cohort (0.970 versus 0.992 in Release 1) likely reflects the use of computational rather than experimentally validated annotations as ground truth, and may therefore underestimate true pipeline performance. The dramatic improvement in computational efficiency makes population-scale TR genotyping feasible for biobank-sized cohorts.

The performance differences observed between gAIRR-wgs and ImmunoTyper2 reflect fundamental differences in algorithmic design and database construction. ImmunoTyper2 employs an integer linear programming (ILP) formulation that resolves ambiguous short-read mappings by optimizing global read-to-allele assignment, using a reference database augmented with GRCh38-derived confounding sequences; however, its ILP optimization is solved via the Gurobi solver, a commercial package requiring a license that poses a barrier to adoption in academic and resource-limited settings. Moreover, ImmunoTyper2’s coverage is restricted to TR_V gene segments, omitting TR_D and TR_J, which limits its utility for comprehensive gTR repertoire characterization. Benchmarking on 44 HPRC subjects revealed that gAIRR-wgs consistently achieved higher precision across all TR_V loci (0.98 versus 0.82 overall), with particularly pronounced improvements at TRAV (0.98 versus 0.78), TRBV (0.97 versus 0.83), TRGV (0.98 versus 0.83), and TRDV (0.98 versus 0.94). We attribute this precision advantage primarily to the expanded reference database and the incorporation of flanking sequences, the variant-aware depth algorithm, and the paired-end validation on key variants in gAIRR-wgs, which together reduce the proportion of reads that cannot be confidently assigned to any allele and thereby suppress FP calls. This precision advantage carries direct practical consequences: in downstream association studies, FP allele calls inflate Type I error rates and can generate spurious genotype–phenotype associations, underscoring the importance of minimizing FPs in population-scale immunogenomic workflows.

Our analysis of 1492 TWB individuals reveals profound gaps in current immunogenetic reference databases, particularly for EAS populations. The finding that 42.4% of high-frequency TR_V genes are dominated by novel rather than IMGT-documented alleles represents systematic bias in global immunogenetic resources. Validation using the expanded HPRC dataset confirmed that most high-frequency novel alleles that initially appeared to be TWB-specific were indeed present in Asian populations, underscoring how limited sampling creates imperfect impressions of population uniqueness. This database incompleteness directly impacts our understanding of immune repertoire biases in disease contexts, potentially leading to misinterpretation of adaptive immune responses in non-EUP populations. The identification of population-specific high-frequency alleles emphasizes the critical need for population-specific immunogenomic studies. gAIRR-wgs demonstrates unique value by enabling systematic characterization of TR diversity from existing biobank WGS data, rapidly expanding reference databases and correcting population-specific biases.

We identified structural polymorphisms affecting contiguous TR genes, representing a previously underappreciated source of immune diversity. The TRBV3-2/TRBV4-3 insertion/deletion polymorphism and TRGV4/TRGV5 deletion polymorphism demonstrate that structural variants can dramatically alter the available gTR repertoire at the population level, with profound implications for understanding population-specific immune capabilities and disease susceptibilities. Notably, conventional structural variant callers failed to detect these immunologically relevant polymorphisms despite their high frequency and substantial genomic span, underscoring the necessity of specialized approaches for complex immune gene regions. The gene-centric approach employed by gAIRR-wgs proves essential for identifying functionally relevant structural variants that conventional genome-wide methods miss.

While gAIRR-wgs represents a significant advance, several limitations warrant consideration. Short-read sequencing (PE 150 bp) limits resolution of complex structural variants and haplotype phasing. Hybridized-structured alleles pose particular challenges that could be better resolved with longer reads (at least 300 bp). Additionally, gAIRR-wgs currently restricts novel allele calling to core coding regions following IMGT nomenclature, though future implementations should consider non-coding regions for comprehensive characterization, similar to other complex immune loci such as cytochrome P450 (CYP), killer-cell immunoglobulin-like receptor (KIR), and HLA.

Beyond technical constraints, several study design limitations should be acknowledged. First, the TWB cohort is drawn exclusively from the Taiwanese population, and while our validation using HPRC confirmed that many novel alleles are shared across Asian populations, the generalizability of our reference database and population-frequency estimates to other ethnic groups remains to be established. Second, benchmarking relied on HPRC assemblies as ground truth; although these represent state-of-the-art references, assembly errors at highly repetitive immune loci cannot be entirely excluded, and may contribute to residual discordance in our performance estimates. Third, gAIRR-wgs was optimized at ~30× sequencing depth; as sequencing costs continue to decline and average coverage depth increases, future work should explore adaptive threshold strategies that leverage higher depth to more effectively filter FP allele calls. Finally, the expanded reference database was derived from annotation of 47 HPRC assemblies, which, while representing a diverse panel, remain limited in EAS representation. This creates a partial circularity in our benchmarking: the same HPRC assemblies used to construct the expanded database also serve as the ground truth for performance evaluation, which may lead to optimistic performance estimates. Prospective validation against independent cohorts with matched long-read assemblies, particularly from underrepresented populations, will be important to confirm the generalizability of these findings.

The gAIRR-wgs pipeline addresses fundamental challenges in population IMGT by enabling accurate TR allele calling from standard WGS data. Our analysis reveals extensive, previously uncharacterized TR diversity in Asian populations, identifies structural polymorphisms, and provides frameworks for database expansion. These advances lay the foundation for population-scale immunogenomic studies and precision approaches to immune-related diseases. Most importantly, this work demonstrates that advanced computational approaches can unlock the immunogenomic potential of existing biobank resources, accelerating translation of population genetic insights into clinical applications. As precision medicine increasingly recognizes the central role of immune system diversity in health and disease, tools like gAIRR-wgs will be essential for realizing the promise of personalized immunotherapy and population-specific medical interventions.

Key Points

• gAIRR-wgs is the first whole-genome sequencing (WGS)-compatible workflow enabling high-resolution T cell receptor (TR) allele typing from standard ~30× coverage data, achieving F1-scores of 1.000 for TR diversity genes (TR_D), 0.999 for TR joining genes (TR_J), and 0.994 for TR variable genes (TR_V) with minimal computational requirements.

• Analysis of 1492 Taiwan Biobank individuals identified 450 novel TR alleles absent from ImMunoGeneTics database (~102% expansion)—277 cross-validated in non-East Asian (EAS) Human Pangenome Reference Consortium cohorts—with 109 high-frequency (>1%) TR_V alleles, demonstrating systematic gaps in global immunogenetic databases.

• gAIRR-wgs detects functionally relevant structural polymorphisms involving T cell receptor gamma variable (TRGV) genes (TRGV4/TRGV5 deletion) and T cell receptor beta variable (TRBV) genes (TRBV3-2/TRBV4-3 insertion/deletion) that are systematically missed by standard variant callers, including Illumina Dynamic Read Analysis for GENomics (DRAGEN).

• Population-level analysis identified 34 TR genes with significant allelic divergence between Taiwanese and global populations, with eight genes showing fine-scale differentiation even within EAS subpopulations.

• By unlocking the immunogenomic potential of existing biobank WGS resources worldwide, gAIRR-wgs bridges the critical gap between standard genomic surveys and adaptive immune repertoire analysis for precision medicine applications.

Author contributions

Kuan-Ta Huang (Conceptualization [equal], Data curation [equal], Formal analysis [equal], Methodology [equal], Software [equal], Visualization, Writing—original draft, Writing—review & editing [equal]), Yu-Hsuan Yang (Formal analysis [equal], Investigation [equal]), Mao-Jan Lin (Methodology [equal], Software [equal], Resources [equal]), Yu-Hui Lin (Software [equal], Data curation [equal], Validation, Investigation [equal], Resources [equal], Writing—review & editing [equal]), Sheng-Kai Lai (Investigation [equal], Resources [equal]), Ting-Hsuan Chou and Chieh-Yu Lee (Formal analysis [equal], Resources [equal]), Tsung-Kai Hung (Resources [equal], Data curation [equal]), Chia-Lang Hsu, Ya-Chien Yang, and Chien-Yu Chen (Supervision [equal], Project administration [equal]), Pei-Lung Chen and Jacob Shu-Jui Hsu (Conceptualization [equal], Resources [equal], Writing—review & editing [equal], Supervision [equal], Project administration [equal], Funding acquisition)

Conflicts of interest

The authors declare no competing interests.

Funding

This study was supported by research grants (NSTC 111-2320-B-002-091-MY3, 114-2622-B-002-009) and industry–academia cooperative research program grants (NSTC 112-2622-B-002-012) from the National Science and Technology Council in Taiwan. This project was also supported by the Institute of Biomedical Sciences, Academia Sinica (IBMS-CRC115-P03), the Excellence in Key Advantages Program (NTU Core Consortiums and Competitiveness Programs) from National Taiwan University, and the Higher Education SPROUT Project (112L895201, 113L892901, 114L891101) from the Ministry of Education, Taiwan.

Data availability

The TR genotype data for 1492 TWB participants generated in this study have been deposited at Zenodo (DOI: 10.5281/zenodo.17596404) under restricted access. Data access requires approval from the TWB Data Release Committee and compliance with their regulations. Researchers interested in accessing the data or establishing collaborations may contact Dr Jacob Shu-Jui Hsu and Dr Pei-Lung Chen. The gAIRR-wgs pipeline is freely available at https://github.com/AnthonyDNA/gAIRR-wgs. IMGT database and HPRC data sources are detailed in the Materials and Methods and Supplementary Materials sections.

Availability and implementation

gAIRR-wgs is freely available at https://github.com/AnthonyDNA/gAIRR-wgs. The pipeline is implemented in Python (version 3.7+) and compatible with Linux/Unix systems.