tidytcells.mh

Functions to manage MH gene data.

Functions

tidytcells.mh.get_chain(symbol=None, log_failures=None, gene=None, suppress_warnings=None)

Given a standardized MH gene / allele symbol, detect whether it codes for an alpha chain, beta chain, or beta-2 microglobulin (B2M) molecule.

Note

This function currently only recognises HLA (human leucocyte antigen or Homo sapiens MH), and not MH from other species.

Parameters:

• symbol (str) – Standardized MH gene / allele symbol

• log_failures (bool) – Report standardisation failures through logging (at level WARNING). Defaults to True.

• gene (str) – Alias for symbol.

• suppress_warnings (bool) – Disable warnings that are usually logged when standardisation fails. Deprecated in favour of log_failures.

Returns:

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

Return type:

Optional[str]

Example usage

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

tidytcells.mh.get_class(symbol=None, log_failures=None, gene=None, suppress_warnings=None)

Given a standardized MH gene / allele symbol, detect whether it comprises a class I (MH1) or II (MH2) receptor.

Note

This function currently only recognises HLA (human leucocyte antigen or Homo sapiens MH), and not MH from other species.

Parameters:

• symbol (str) – Standardized MH gene / allele symbol

• log_failures (bool) – Report standardisation failures through logging (at level WARNING). Defaults to True.

• gene (str) – Alias for symbol.

• suppress_warnings (bool) – Disable warnings that are usually logged when standardisation fails. Deprecated in favour of log_failures.

Returns:

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

Return type:

Optional[int]

Example usage

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

tidytcells.mh.query(species=None, precision=None, contains_pattern=None)

Query the list of all known MH genes / alleles.

Supported species

• "homosapiens"

• "musmusculus"

Note

tidytcells’ knowledge of MH 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_pattern (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-TAP1 variants.

>>> tt.mh.query(species="homosapiens", contains_pattern="HLA-TAP1")
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.mh.query(species="musmusculus", precision="gene", contains_pattern="MH1-Q")
frozenset({'MH1-Q3', 'MH1-Q9', 'MH1-Q1', 'MH1-Q2', 'MH1-Q6', 'MH1-Q10', 'MH1-Q5', 'MH1-Q8', 'MH1-Q7', 'MH1-Q4'})

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

Alias for tidytcells.mh.standardize().

Return type:

str | None

tidytcells.mh.standardize(symbol=None, species=None, precision=None, on_fail=None, log_failures=None, gene=None, suppress_warnings=None)

Attempt to standardize an MH gene / allele symbol to be IMGT-compliant.

Supported species

• "homosapiens"

• "musmusculus"

Note

This function will only verify the validity of an MH 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:

• symbol (str) – Potentially non-standardized MH gene / allele symbol.

• species (str) –

  Can be specified to standardise to a TR symbol that is known to be valid for that species (see above for supported species). If set to "any", then first attempts standardisation for Homo sapiens, then Mus musculus. Defaults to "homosapiens".

  Note

  From version 3, the default behaviour will change to "any".

• 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".

• log_failures (bool) – Report standardisation failures through logging (at level WARNING). Defaults to True.

• gene (str) – Alias for symbol.

• suppress_warnings (bool) – Disable warnings that are usually logged when standardisation fails. Deprecated in favour of log_failures.

Returns:

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

Return type:

Optional[str]

Example usage

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

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

The precision setting can truncate unnecessary information.

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

Mus musculus is a supported species.

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

Decision Logic

To provide an easy way to gauge the scope and limitations of standardization, below is a simplified overview of the decision logic employed when attempting to standardize an MH symbol. For more detail, please refer to the source code.

IF the specified species is not supported for standardization:
    RETURN original symbol without modification

ELSE:
    // attempt standardization
    {
        IF symbol is already in IMGT-compliant form:
            set standardization status as successful
            skip rest of standardization

        IF symbol is a known deprecated symbol:
            overwrite symbol with current IMGT-compliant symbol
            set standardization status as successful
            skip rest of standardization

        // the rest is only applicable when species is set to homo sapiens
        add "HLA-" to the beginning of the symbol if necessary                  //e.g. A -> HLA-A
        replace "Cw" with "C"                                                   //e.g. HLA-Cw -> HLA-C
        add back forgotten asterisks if necessary                               //e.g. HLA-A01 -> HLA-A*01
        add back forgotten colons if necessary                                  //e.g. HLA-A*0101 -> HLA-A*01:01
        If symbol is now in IMGT-compliant form:
            set standardization status as successful
            skip rest of standardization

        try adding or subtracting leading zeros from allele designation numbers //e.g. HLA-A*001 -> HLA-A*01
        If symbol is now in IMGT-compliant form:
            set standardization status as successful
            skip rest of standardization

        set standardization status as failed
    }

    IF standardization status is set to successful:
        RETURN standardized symbol

    ELSE:
        IF on_fail is set to "reject":
            RETURN None
        IF on_fail is set to "keep":
            RETURN original symbol without modification