API reference: c4.hla

For a walkthrough with examples, see HLA calls.

HLA alleles and genotypes, and converting tables of HLA calls.

Library functions return HLAallele / HLAgenotype objects; turn them into text with HLAallele.allele(format=...) or HLAgenotype.genotype(format=...) when printing or writing a file.

HLAgenotype

A pair of HLA alleles for one gene, e.g. A*02:01/A*24:02.

This is what every c4 HLA loader puts in a table's gene columns. Alleles are stored in sorted order (unless unphased=False), with a missing allele last. It prints as A*02:01/A*24:02.

Parameters:

Name	Type	Description	Default
genotype	str	"A*02:01/24:02", "A*02:01/A*24:02" or "02:01/24:02". A "." allele, or a blank or NaN genotype, is missing.	required
gene	str	Gene name, used when the text has no prefix.	None
unphased	bool	Sort the two alleles (default True).	True
hypen_is_homoz	bool	Read "02:01/-" as homozygous 02:01/02:01.	True
digits	int	Keep at most this many digits (4 = 2-field).	None

Attributes:

Name	Type	Description
a1		The first HLAallele (a missing allele is always second).
a2		The second HLAallele.
gene		Gene name.
fields		Resolution of the lower-resolution allele, in fields.
missing_alleles		0, 1 or 2.
prob		HIBAG posterior probability, on genotypes loaded from HIBAG output only.

Examples:

>>> gt = HLAgenotype("A*24:02/02:01:01")
>>> gt
HLAgenotype('A*02:01:01/A*24:02')
>>> gt.genotype(format="standard_no_gene", digits=4)
'02:01/24:02'
>>> gt.copies_of("A*02:01")
1

from_alleles(a1, a2, gene=None, **kwargs) classmethod

Convenience constructor from separate alleles.

Parameters:

Name	Type	Description	Default
a1	str	First allele (e.g., "01:01")	required
a2	str	Second allele (e.g., "02:01")	required
gene	str	Gene name (e.g., "A")	None
**kwargs		Passed on to HLAgenotype, e.g. digits	{}

Examples:

>>> HLAgenotype.from_alleles("01:01", "02:01", "A")
HLAgenotype('A*01:01/A*02:01')

add_attr(attr_name, attr)

Set an attribute, e.g. gt.add_attr("prob", 0.97).

update_digits(digits)

Lower this genotype's resolution in place (4 = 2-field).

genotype(format=None, digits=None)

The genotype as text, or its two alleles.

Parameters:

Name	Type	Description	Default
format	str	One of: "standard": A*02:01/24:02 "standard2": A*02:01/A*24:02 (what str(gt) gives) "standard_no_gene": 02:01/24:02 "tuple", "colon", "array": a pair, e.g. (("02", "01"), ("24", "02")) None (default): the two HLAallele objects	None
digits	int	Resolution (4 = 2-field). Default: all fields.	None

concordance(gt2, digits=None, filter_lower_resolution=False)

Compare this genotype to another genotype.

The two are compared at the lower of their resolutions, and no higher than digits, so A*11:01:01 vs A*11:01:02 compares as 11:01.

Parameters:

Name	Type	Description	Default
gt2		The other HLAgenotype.	required
digits	int	Highest resolution to compare at (4 = 2-field).	None
filter_lower_resolution	bool	Return NaN instead of comparing when either genotype has fewer than digits digits.	False

Returns:

Type	Description
	2 when both alleles match, 1 when one does, 0 when neither does,
	and NaN when either genotype is missing an allele (or is
	filtered out).

copies_of(allele)

How many of the two alleles match allele: 0, 1 or 2 (NaN if both are missing).

Matching uses the resolution of allele, so copies_of("A*02:01") also counts A*02:01:01, and copies_of("A*02") counts every A*02 allele. Useful as an allele dosage for association tests.

Parameters:

Name	Type	Description	Default
allele	str	Text such as "A*02:01" or "02:01", or an HLAallele.	required

HLAallele

One HLA allele, e.g. A*02:01:01.

Parameters:

Name	Type	Description	Default
allele	str	The allele as text, with or without the gene prefix ("A*02:01" or "02:01"), at any resolution from 1 field ("A*02"). ".", "", "nan" and NaN mean missing. Anything else that isn't an allele raises ValueError.	required
digits	int	Keep at most this many digits (2 per field, so 4 = 2-field).	None
gene	str	Gene name, used when the text has no prefix.	None

Attributes:

Name	Type	Description
gene		Gene name, or None if never given.
fields		Number of fields kept (02:01:01 has 3).
is_missing		True for a missing allele.

Examples:

>>> a = HLAallele("A*02:01:01")
>>> a.allele(digits=4)
'02:01'
>>> str(a)
'A*02:01:01'

allele(format='colon', digits=None)

The allele as text or a tuple.

Parameters:

Name	Type	Description	Default
format	str	"colon" (02:01, the default), "standard" or "standard2" (A*02:01), "standard_no_gene" (02:01), "tuple" (("02", "01")) or "array".	'colon'
digits	int	Resolution (4 = 2-field). Default: all fields.	None

get_self(digits=None)

Return this allele or a lower-resolution copy.

parse_hla_columns(df, gene_list=None)

Turn a table's HLA columns into one HLAgenotype column per gene.

A gene can be one genotype column (A with A*01:01/02:01) or two allele columns (A_1, A_2), which are merged into A. Genes in gene_list (default: config.hla_genes) that aren't in the table are skipped.

hibag_to_genotypes(df)

Turn HIBAG's allele1_<gene> / allele2_<gene> columns into one HLAgenotype column per gene. Each genotype gets a .prob attribute from prob_<gene>, which is also kept as a column.

load_hibag(file_name, sep=',', genotype_id_col='sample.id', panel='european')

Load a HIBAG output file as HLAgenotype columns, each with a .prob attribute.

For a cohort in the catalog, cohort(name).load("hla.hibag.raw", panel=...) does the same and adds patient_id.

Parameters:

Name	Type	Description	Default
file_name	Path	Path to the european-panel file. european in the path is replaced by panel.	required
sep	str	Not used; the file is always read as comma-separated.	','
genotype_id_col	str	Sample ID column, renamed to genotype_id.	'sample.id'
panel	str	Reference panel; also added as a panel column.	'european'

split_genotype(in_df, gene=None, gene_list=None, **kwargs)

Split genotype columns into separate allele columns.

Converts columns like DRB1 with values 01:01/02:02 into two columns of HLAallele objects: DRB1_1 (01:01) and DRB1_2 (02:02). Use HLAallele.allele to turn them into text.

Parameters:

Name	Type	Description	Default
in_df	DataFrame	DataFrame containing genotype columns (text or HLAgenotype)	required
gene	str	Gene name to split (e.g., "DRB1")	None
gene_list	list	Optional list of gene names to split. If None, uses single gene.	None
**kwargs		Additional arguments passed to HLAgenotype constructor (e.g., unphased, hypen_is_homoz, digits)	{}

Returns:

Type	Description
	DataFrame with HLAallele columns, original genotype columns removed

merge_genotype(in_df, gene=None, gene_list=None, **kwargs)

Merge separate allele columns back into genotype columns.

Converts columns like DRB1_1 with 01:01 and DRB1_2 with 02:02 into one DRB1 column of HLAgenotype objects (01:01/02:02). Use HLAgenotype.genotype to turn them into text.

Parameters:

Name	Type	Description	Default
in_df	DataFrame	DataFrame containing split allele columns (text or HLAallele)	required
gene	str	Gene name to merge (e.g., "DRB1")	None
gene_list	list	Optional list of gene names to merge. If None, uses single gene.	None
**kwargs		Additional arguments passed to HLAgenotype constructor (e.g., unphased, hypen_is_homoz, digits)	{}

Returns:

Type	Description
	DataFrame with HLAgenotype columns, split allele columns removed

genotype_concordance(gt1_1, gt1_2, gt2_1, gt2_2)

Compare two genotypes, given as allele tuples, for concordance.

Most code should use HLAgenotype.concordance, which handles missing alleles and resolution.

Parameters:

Name	Type	Description	Default
gt1_1	Tuple	First allele of genotype 1 (as tuple)	required
gt1_2	Tuple	Second allele of genotype 1 (as tuple)	required
gt2_1	Tuple	First allele of genotype 2 (as tuple)	required
gt2_2	Tuple	Second allele of genotype 2 (as tuple)	required

Returns:

Type	Description
int	2 when both alleles match, 1 when one does, 0 when neither does.