tidytcells.mhc

Functions to clean and standardize MHC gene data.

Functions

tidytcells.mhc.classify(*args, **kwargs)

Caution

This will be deprecated soon in favour of tidytcells.mhc.get_class().

Alias for tidytcells.mhc.get_class().

tidytcells.mhc.get_chain(gene: str | None = None, suppress_warnings: bool = False, gene_name: str | None = None) → str

Given a standardized MHC gene name, detect whether it codes for an alpha or a beta chain molecule.

Note

This function currently only recognises HLAs, and not MHCs from other species.

Parameters:

• gene (str) – Standardized MHC gene name

• suppress_warnings (bool) – Disable warnings that are usually emitted when chain classification fails. Defaults to False.

• gene_name (str) –

  Alias for the parameter gene.

  Caution

  This will be deprecated soon in favour of gene.

Returns:

'alpha' or 'beta' if gene is recognised and its chain is known, else None.

Return type:

Union[str, None]

Example usage

>>> tt.mhc.get_chain("HLA-A")
'alpha'
>>> tt.mhc.get_chain("HLA-DRB2")
'beta'
>>> tt.mhc.get_chain("B2M")
'beta'

tidytcells.mhc.get_class(gene: str | None = None, suppress_warnings: bool = False, gene_name: str | None = None) → int

Given a standardized MHC gene name, detect whether it comprises a class I or II MHC receptor complex.

Note

This function currently only recognises HLAs, and not MHCs from other species.

Parameters:

• gene (str) – Standardized MHC gene name

• suppress_warnings (bool) – Disable warnings that are usually emitted when classification fails. Defaults to False.

• gene_name (str) –

  Alias for the parameter gene.

  Caution

  This will be deprecated soon in favour of gene.

Returns:

1 or 2 if gene is recognised and its class is known, else None.

Return type:

Union[int, None]

Example usage

>>> tt.mhc.get_class("HLA-A")
1
>>> tt.mhc.get_class("HLA-DRB2")
2
>>> tt.mhc.get_class("B2M")
1

tidytcells.mhc.query(species: str = 'homosapiens', precision: str = 'allele', contains: str | None = None) → FrozenSet[str]

Query the list of all known MHC genes/alleles.

Supported species

• 'homosapiens'

• 'musmusculus'

Note

tidytcells’ knowledge of MHC alleles is limited, especially outside of humans. tidytcells will allow you to query HLA alleles up to the level of the protein (first two allele designators), but that is the highest resolution available. For Mus musculus, there is currently only support for gene-level querying.

Parameters:

• species (str) – Species to query (see above for supported species). Defaults to 'homosapiens'.

• precision (str) – The level of precision to query. allele will query from the set of all possible alleles. gene will query from the set of all possible genes. Defaults to allele.

• contains (str) – An optional regular expression string which will be used to filter the query result. If supplied, only genes/alleles which contain the regular expression will be returned. Defaults to None.

Returns:

The set of all genes/alleles that satisfy the given constraints.

Return type:

FrozenSet[str]

Example usage

List all known HLA-G variants.

>>> tt.mhc.query(species="homosapiens", contains="HLA-G")
frozenset({'HLA-TAP1*03:01', 'HLA-TAP1*01:02', 'HLA-TAP1*06:01', 'HLA-TAP1*04:01', 'HLA-TAP1*02:01', 'HLA-TAP1*05:01', 'HLA-TAP1*01:01'})

List all known Mus musculus MH1-Q genes.

>>> tt.mhc.query(species="musmusculus", precision="gene", contains="MH1-Q")
frozenset({'MH1-Q3', 'MH1-Q9', 'MH1-Q1', 'MH1-Q2', 'MH1-Q6', 'MH1-Q10', 'MH1-Q5', 'MH1-Q8', 'MH1-Q7', 'MH1-Q4'})

tidytcells.mhc.standardise(*args, **kwargs)

Alias for tidytcells.mhc.standardize().

tidytcells.mhc.standardize(gene: str | None = None, species: str = 'homosapiens', precision: str = 'allele', on_fail: str = 'reject', suppress_warnings: bool = False, gene_name: str | None = None) → tuple

Attempt to standardize an MHC gene name to be IMGT-compliant.

Supported species

• 'homosapiens'

• 'musmusculus'

Note

This function will only verify the validity of an MHC gene/allele up to the level of the protein. Any further precise allele designations will not be verified, apart from the requirement that the format (colon-separated numbers) look valid. The reasons for this is firstly because new alleles at that level are added to the IMGT list quite often and so accurate verification is difficult, secondly because people rarely need verification to such a precise level, and finally because such verification costs more computational effort with diminishing returns.

Parameters:

• gene (str) – Potentially non-standardized MHC gene name.

• species (str) – Species to which the MHC gene belongs (see above for supported species). Defaults to 'homosapiens'.

• precision (str) – The maximum level of precision to standardize to. 'allele' standardizes to the maximum precision possible. 'protein' keeps allele designators up to the level of the protein. 'gene' standardizes only to the level of the gene. Defaults to 'allele'.

• on_fail (str) – Behaviour when standardization fails. If set to "reject", returns None on failure. If set to "keep", returns the original input. Defaults to "reject".

• suppress_warnings (bool) – Disable warnings that are usually emitted when standardisation fails. Defaults to False.

• gene_name (str) –

  Alias for the parameter gene.

  Caution

  This will be deprecated soon in favour of gene.

Returns:

If the specified species is supported, and gene could be standardized, then return the standardized gene name. If species is unsupported, then the function does not attempt to standardize, and returns the unaltered gene string. Else follows the behvaiour as set by on_fail.

Return type:

Union[str, None]

Example usage

Input strings will intelligently be corrected to IMGT-compliant gene symbols.

>>> tt.mhc.standardize("A1")
'HLA-A*01'

The precision setting can truncate unnecessary information.

>>> tt.mhc.standardize("HLA-A*01", precision="gene")
'HLA-A'

Mus musculus is a supported species.

>>> tt.mhc.standardize("CRW2", species="musmusculus")
'MH1-M5'