Python package for dealing with HLA sequence data
Heavily inspired by and dependent on the fantastic pyARD package. The HLAGenie
package strives to streamline and standardize the bulk handling of HLA sequence data and provide functions to simplify matching analysis.
- Installation
- Using HLAGenie
- Using
hlagenie
from Python- Initialize
hlagenie
- Accessing sequence dictionaries for HLA alleles
- Retrieve amino acid or nucleotide position from mature protein sequence
- Retrieve amino acid substring from mature protein sequence
- Retrieve epitope from mature protein sequence
- Check if two alleles have a mismatch at a given position
- Count the number of amino acid mismatches at a position between donor and recipient
- Count the number of amino acid mismatches between donor and recipient at a given position given the alleles
- Get the antigen recognition domain sequence of an allele
- Get the extracellular domain sequence of an allele
- Initialize
- Using
hlagenie
from the command line
- Using
- Feature requests
- Contributing
pip install hlagenie
python3 -m venv venv
source venv/bin/activate
python setup.py install
hlagenie
is intended to simplify the handling of HLA sequence data.
Import hlagenie
package
import hlagenie
Initialize GENIE
object with a version of the IMGT/HLA database.
import hlagenie
genie = hlagenie.init("3510")
The default behavior is to use ungapped sequences for HLA alleles. If you would prefer the alleles to maintain the gaps that exist in the sequence alignment, pass ungap = False
to the init
function.
import hlagenie
genie = hlagenie.init("3510", ungap = False)
The first time an object is instantiated with a given IMGT/HLA database version, the package will download the appropriate MSF files from the IMGT/HLA GitHub repository and create a SQLite database in the /tmp
folder.
The GENIE
object contains dictionaries of amino acid and nucleotide sequences for each HLA allele. The keys for the dictionaries are the HLA allele names. The values are the genetic sequences.
All of the keys are two-field alleles given the shared protein sequence of these alleles.
genie.seqs # mature protein sequences
genie.full_seqs # full protein sequences
genie.nuc_seqs # full nucleotide sequences
To get a given amino acid (or nucleotide) position from a given HLA allele, you can use the getAA
or getNuc
functions. These functions are 1-indexed to match standard IMGT/HLA database nomenclature.
For this and following functions, if a three- or four-field allele name is passed, a call is made to py-ard
to reduce to the two-field level.
genie.getAA("A*01:01",1) # returns "G"
genie.getNuc("A*01:01",1) # returns "A"
To get a given amino acid substring from a given HLA allele, you can use the getPeptide
function. This function is 1-indexed as well and is inclusive of the start and end positions.
genie.getPeptide("A*01:01",1,10) # returns "GSHSMRYFFT"
If you pass an allele name and a list of positions to the getEpitope
function, hlagenie
will return a formatted epitope string.
genie.getEpitope("A*01:01",[1,2,3,4,5]) # returns "1G_2S_3H_4S_5M"
If you pass two allele names and a position to the isPositionMismatched
function, hlagenie
will return a boolean indicating whether or not the two alleles have a mismatch at that position.
genie.isPositionMismatched("A*01:01","A*01:02",1) # returns False (the amino acid is the same at position 1 for both alleles)
The countAAMismatches
function takes as input four amino acids, two from the donor and two from the recipient (in order). The function returns the number of mismatches between the donor and recipient at that position.
This uses the logic that if a recipient has the donor's amino acid as either of their two amino acids, it is not a mismatch.
genie.countAAMismatches("A","G","G","G") # returns 1
Count the number of amino acid mismatches between donor and recipient at a given position given the alleles
The countAAMismatchesAllele
function takes as input four alleles and an amino acid position. The input order is: Donor Allele 1, Donor Allele 2, Recipient Allele 1, Recipient Allele 2, amino acid position. The function returns the number of mismatches between the donor and recipient at that position, adjusting for donor homozygosity.
genie.countAAMismatchesAllele("A*02:01","A*02:01","A*01:01","A*01:01", 44) # returns 1
The getARD
function takes as input an allele name and returns the antigen recognition domain sequence of that allele.
genie.getARD("A*01:01")
The getXRD
function takes as input an allele name and returns the extracellular domain sequence of that allele.
genie.getXRD("A*01:01")
Some command-line functions are now available.
- Retrieval of specific amino acid positions
- Retrieval of ARD sequence
- Retrieval of XRD sequence
- Retrieval of mature protein sequence
Note that the gapped sequences can be retrieved for any of the following by passing the --gapped
flag.
Calling hlagenie
from the command line with an allele name and space-delimited list of positions will allow you to retrieve the amino acid at those positions.
hlagenie -a "A*01:01" -p 1 2 3 4 5 # returns 1G_2S_3H_4S_5M
Calling hlagenie
from the command line with an allele name and the --ard
flag will allow you to retrieve the ARD sequence of that allele.
hlagenie -a "A*01:01" --ard
Calling hlagenie
from the command line with an allele name and the --xrd
flag will allow you to retrieve the XRD sequence of that allele.
hlagene -a "A*01:01" --xrd
Calling hlagenie
from the command line with only an allele name will allow you to retrieve the mature protein sequence of that allele.
hlagenie -a "A*01:01"
Calling hlagenie-match
from the command line with two allele names and a position will allow you to check if the two alleles have a mismatch at that position. This is based on the mature protein sequence of the alleles. This uses the gapped sequences by default to best assess matching.
hlagenie-match --allele1 "A*01:01" --allele2 "A*01:02" --positions 1 # returns Matched
Supplying a space-delimited list of positions will provide a count of mismatches between the alleles.
hlagenie-match --allele1 "A*01:01" --allele2 "A*01:02" --positions 1 2 3 4 5 # returns 0
Calling hlagenie-match
from the command line with two allele names and no specified positions will allow you to count the total number of mismatches between the two alleles.
hlagenie-match --allele1 "A*01:01" --allele2 "A*01:02" # returns 2
Alternatively, you can use the --ard
or --xrd
flags to check for mismatches in the ARD or XRD sequences, respectively.
hlagenie-match --allele1 "A*01:01" --allele2 "A*68:02" --ard # returns 23
hlagenie-match --allele1 "A*01:01" --allele2 "A*68:02" --ard # returns 29
Calling hlagenie-match
from the command line with a recipient genotype and a donor genotype and a set of positions will allow you to retrieve the number of mismatches between the donor and recipient at those positions. This is based on the mature protein sequence of the alleles. This uses the gapped sequences by default to best assess matching. This value is adjusted for donor homozygosity.
hlagenie-match --recip-haplo "A*01:01+A*01:02" --donor-haplo "A*02:01+A*01:02" --positions 1 2 3 4 5 # returns 0
This can also be done with a single position.
hlagenie-match --recip-geno "A*01:01+A*01:02" --donor-geno "A*02:01+A*01:02" --positions 1 # returns 0
Supplying no positions gets the total number of mismatches between the donor and recipient, adjusted for donor homozygosity.
hlagenie-match --recip-geno "A*01:01+A*01:02" --donor-geno "A*02:01+A*01:02" # returns 32
Alternatively, you can use the --ard
or --xrd
flags to get the mismatches between the donor and recipient at the ARD or XRD level, respectively.
hlagenie-match --recip-geno "A*01:01+A*01:02" --donor-geno "A*02:01+A*01:02" --ard # returns 24
hlagenie-match --recip-geno "A*01:01+A*01:02" --donor-geno "A*02:01+A*01:02" --xrd # returns 29
If you have a feature request, please feel free to open a new discussion in the Ideas page of the Discussions tab. Doing so allows for a more open discussion of the feature and allows others to chime in with their thoughts.
Contributions are welcome. Please feel free to open a pull request with your changes. If you are unsure of how to do this, please feel free to open a discussion in the Q&A. If you are interested in contributing but are unsure of where to start, please check out the Issues tab.
Bug reporting is also welcome in the Issues tab. Please include as much information as possible, including the version of hlagenie
you are using, the version of Python you are using, and the operating system you are using. If you are able to provide a minimal reproducible example, that would be very helpful.