tidytcells.ig

Functions to manage IG gene data.

Functions

tidytcells.ig.get_aa_sequence(symbol=None, species=None, gene=None)

Look up the amino acid sequence of a given IG allele.

Supported species

• "homosapiens"

Parameters:

• symbol (str) – Standardized allele symbol. Note that the symbol must be specified to the level of the allele. Note that some alleles, notably those of non-functional genes, will not have resolvable amino acid sequences.

• species (str) – Species to which the IG gene in question belongs (see above for supported species). Defaults to "homosapiens".

• gene (str) – Alias for symbol.

Returns:

A dictionary with keys corresponding to names of different sequence regions within the allele, and values corresponding to their amino acid sequences.

Return type:

Dict[str, str]

Example usage

Get amino acid sequence information about the human V gene IGHV1-18*02.

>>> tt.ig.get_aa_sequence(gene="IGHV1-18*02", species="homosapiens")
{'CDR1-IMGT': 'GYTFTSYG', 'CDR2-IMGT': 'ISAYNGNT', 'FR1-IMGT': 'QVQLVQSGAEVKKPGASVKVSCKAS', 'FR2-IMGT': 'ISWVRQAPGQGLEWMGW', 'FR3-IMGT': 'NYAQKLQGRVTMTTDTSTSTAYMELRSLRSDDTA', 'V-REGION': 'QVQLVQSGAEVKKPGASVKVSCKASGYTFTSYGISWVRQAPGQGLEWMGWISAYNGNTNYAQKLQGRVTMTTDTSTSTAYMELRSLRSDDTA'}

Get amino acid sequence information about the human J gene IGLJ1*01.

>>> tt.ig.get_aa_sequence(gene="IGLJ1*01", species="homosapiens")
{'J-REGION': 'YVFGTGTKVTVL'}

tidytcells.ig.query(species=None, precision=None, functionality=None, contains_pattern=None)

Query the list of all known IG

genes / alleles.

Supported species

• "homosapiens"

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.

• functionality (str) – Gene/allele functionality to subset by. "any" queries from all possible genes/alleles. "F" queries from functional genes/alleles. "NF" queries from psuedogenes and ORFs. "P" queries from pseudogenes. "ORF" queries from ORFs. An allele is considered queriable if its functionality label matches the description. A gene is considered queriable if at least one of its alleles’ functionality label matches the description. Defaults to "any".

• 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 variants for the human IG gene IGLJ1.

>>> tt.ig.query(species="homosapiens", contains_pattern="IGLJ1")
frozenset({'IGL1*01'})

List all known IGLV genes that have at least one allele which is a non-functional ORF.

>>> tt.ig.query(species="homosapiens", precision="gene", functionality="ORF", contains_pattern="IGLV")
frozenset({'IGLV1-41', 'IGLV1-50', 'IGLV11-55', 'IGLV2-33', 'IGLV3-32', 'IGLV5-48', 'IGLV8/OR8-1'})

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

Alias for tidytcells.ig.standardize().

Return type:

str | None

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

Attempt to standardize a IG gene / allele symbol to be IMGT-compliant.

Supported species

• "homosapiens"

Parameters:

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

• species (str) – Can be specified to standardise to a IG symbol that is known to be valid for that species (see above for supported species). Currently, only Homo sapiens is supported, but this parameter has been kept to keep the interface compatible with that of its sister function in tidytcells.tr. Defaults to "homosapiens".

• enforce_functional (bool) – If True, disallows IG genes / alleles that are recognised by IMGT but are marked as non-functional (ORF or pseudogene). Defaults to False.

• precision (str) – The maximum level of precision to standardize to. "allele" standardizes to the maximum precision possible. "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 the parameter 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 name. If species is unsupported, then the function does not attempt to standardize , and returns the unaltered symbol string. Else follows the behaviour as set by on_fail.

Return type:

Optional[str]

Example usage

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

>>> tt.ig.standardize("lj1")
'IGLJ1'

The precision setting can truncate unnecessary information.

>>> tt.ig.standardize("IGHV1-18*02", precision="gene")
'IGHV1-18'

The enforce_functional setting will cause non-functional genes or alleles to be rejected.

>>> result = tt.ig.standardize("IGHV1-12", enforce_functional=True)
Failed to standardize "IGHV1-12" for species homosapiens: gene has no functional alleles. Attempted fix "IGHV1-12".
>>> print(result)
None

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 a TR 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

        replace "." with "-"                                        //e.g. IGHV1.2 -> IGHV1-2
        add back any missing backslashes                            //e.g. IGHV1OR15-1 -> IGHV1/OR15-1
        remove any unnecessary trailing zeros                       //e.g. IGHV1-02 -> IGHV1-2
        IF symbol is now in IMGT-compliant form:
            set standardization status as successful
            skip rest of standardization


        add "IG" to the beginning of the symbol if necessary   //e.g. HV1-18 -> IGHV1-18
        IF symbol is now in IMGT-compliant form:
            set standardization status as successful
            skip rest of standardization

        try adding or removing "-1" from the end of the symbol //e.g. IGHV6 -> IGHV6-1
        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