3 Allele Similarity Cluster
3.1 Introduction
The term Allele similarity clusters (ASC), defines alleles that have a degree of germline proximity. The proximity is defined as the Levenshtein distance between the coding region of the alleles’ germline sequences. A distance matrix of all alleles’ Levenshtein distance is constructed and the hierarchical tree is calculated. The tree leaves are then clustered by 95% similarity which creates the alleles clusters.
3.1.1 Library amplicon length
Even though, we wish that all repertoires data available will cover the entire V region this is not always the case. Hence, we adapted our protocols to fit partial V coverage libraries. For the beginning we chose two library amplicon length, BIOMED-2 primers and Adaptive region coverage. The table below summaries the naming for each of the amplicon lengths and see Fig. 3.1 for coverage illustration:
| Library amplicon length | Coverage | Similar known protocol |
|---|---|---|
| S1 | Full length - 1 to 318 (IMGT numbering) | 5’ Race |
| S2 | Starting within the framework 1 region | BIOMED-2 |
| S3 | End of the V region | Adaptive |
Figure 3.1: V library amplicon length. Each row is a different V coverage, S1 for full length, S2 for BIOMED-2 primers, and S3 for adaptive coverage. The colors indicates the V regions according to IMGT numbering, where dark gray represents the IMGT gaps.
3.2 Inferring Allele Similarity Clusters
The main function in this section inferAlleleClusters returns an S4
object that includes the ASC allele cluster table alleleClusterTable
with the new names and the default thresholds, the renamed germline set
alleleClusterSet, and the germline set hierarchical clustering
hclustAlleleCluster, and the similarity threshold parameters
threshold. Further by using the plot function on the returned object,
a colorful visualization of the allele clusters dendrogram and threshold
is received.
The function receives as an input a germline reference set of allele sequences, the filtration parameters for the 3’ and 5’ regions, and two similarity thresholds for the ASC clusters and families.
To create the clusters we will first load data from the package:
- The IGHV germline reference - this reference set was download from IMGT in July 2022.
library(piglet)
#> PIgLET version: 1.0.7 New feature was added! A confidence level to the genotype inference. Check the news for more details To cite package 'piglet' in publications use:
#>
#> Peres A, Lees W, Rodriguez O, Lee N, Polak P, Hope R, Kedmi M,
#> Collins A, Ohlin M, Kleinstein S, Watson C, Yaari G (2023). "IGHV
#> allele similarity clustering improves genotype inference from
#> adaptive immune receptor repertoire sequencing data." _Nucleic Acid
#> Research_, E86. doi:10.1093/nar/gkad603
#> <https://doi.org/10.1093/nar/gkad603>.
#>
#> A BibTeX entry for LaTeX users is
#>
#> @Article{,
#> title = {IGHV allele similarity clustering improves genotype inference from adaptive immune receptor repertoire sequencing data},
#> author = {Ayelet Peres and William Lees and Oscar Rodriguez and Noah Lee and Pazit Polak and Ronen Hope and Meirav Kedmi and Andrew Collins and Mats Ohlin and Steven Kleinstein and Corey Watson and Gur Yaari},
#> year = {2023},
#> doi = {10.1093/nar/gkad603},
#> journal = {Nucleic Acid Research},
#> number = {51},
#> pages = {E86},
#> }
data(HVGERM)- The allele functionality table - the table contains functionality information for each of the alleles. Download from IMGT in July 2022
Before clustering the germline set, we will remove non functional alleles, alleles that do not start on the first 5’ nucleotide, and those that are shorter than 318 bases.
germline <- HVGERM
## keep only functional alleles
germline <- germline[hv_functionality$allele[hv_functionality$functional=="F"]]
## keep only alleles that start from the first position of the V sequence
germline <- germline[!grepl("^[.]", germline)]
## keep only alleles that are at minimum 318 nucleotide long
germline <- germline[nchar(germline) >= 318]
## keep only localized alleles (remove NL)
germline <- germline[!grepl("NL", names(germline))]germline <- HVGERM
## keep only functional alleles
germline <- germline[hv_functionality$allele[hv_functionality$functional=="F"]]
## keep only alleles that start from the first position of the V sequence
germline <- germline[!grepl("^[.]", germline)]
## keep only alleles that are at minimum 318 nucleotide long
germline <- germline[nchar(germline) >= 318]
## keep only localized alleles (remove NL)
germline <- germline[!grepl("NL", names(germline))]Then we will create the ASC clusters using the inferAlleleClusters
function. For better clustering results with the human IGHV reference
set, it is recommended to set the trim_3prime_side parameter to 318.
Here, we will use the default similarity thresholds 75% for the family
and 95% for the clusters.
asc <- inferAlleleClusters(
germline_set = germline,
trim_3prime_side = 318,
mask_5prime_side = 0,
family_threshold = 75,
allele_cluster_threshold = 95)The output of inferAlleleClusters is an S4 object of type
GermlineCluster that contains several slots:
| Slot | Description |
|---|---|
| germlineSet | The input germline set with the 3’ and 5’ modifications (If defined) |
| alleleClusterSet | The input germline set with the ASC name scheme, if exists without duplicated sequences |
| alleleClusterTable | The allele similarity cluster with the new names and the default thresholds |
| threshold | The input family and allele cluster similarity thresholds |
| hclustAlleleCluster | Germline set hierarchical clustering, an hclust object |
We can use the S4 plot method to plot the hierarchical clustering of the germline set as seen below in Fig. 3.2.
Figure 3.2: Allele similarity clusters. The out most circle is the allele names, the second layer are the ASC groups, each group is labeled and colored. The third circle is the clustering dendrogram, the branches are colored by the ASC families. The blue and orange dashed lines are the 95% and 75% similarity ASC threshold.
3.2.1 Artificial framework 1 reference set
As described in section 3.1.1, not all repertoires data available covers the entire V region. Hence, a modified reference set for the sequenced region can help us further understand the results we can obtain from certain library protocols.
Hence, we created the function artificialFRW1Germline, to mimic the
seen coding region of targeted framework 1 (FRW1) primers for a given
reference set. The primers were obtained from BIOMED-2 protocol
[2].
Essentially the function matches the primer to each of the germline set sequences and either mask or trim the region. The returned object is a character vector with the named sequence in the desire length (Trimmed/Masked).
To demonstrate the use of the function, we can use the cleaned germline
set from above (block 1).
In this case we will mask the FRW1 region, this will return the sequences with the Ns instead of DNA
nucleotide. The function output a log of the process, this output can be
repressed using the quiet=TRUE flag.
germline_frw1 <- artificialFRW1Germline(germline, mask_primer = T)
#> 282/286 germline sequences have passed
#> Counts by primers:
#> VH1-FR1:53,VH2-FR1:25,VH3-FR1:122,VH4-FR1:69,VH5-FR1:10,VH6-FR1:3We can use the artificial germline set to infer the ASC clusters in the same fashion as in section 3.2.
