tidytcells.tr

Functions to manage TR gene data.

Functions

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

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

Supported species

• "homosapiens"

• "musmusculus"

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 TR 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 TRBV2*01.

>>> tt.tr.get_aa_sequence(gene="TRBV2*01", species="homosapiens")
{'CDR1-IMGT': 'SNHLY', 'CDR2-IMGT': 'FYNNEI', 'FR1-IMGT': 'EPEVTQTPSHQVTQMGQEVILRCVPI', 'FR2-IMGT': 'FYWYRQILGQKVEFLVS', 'FR3-IMGT': 'SEKSEIFDDQFSVERPDGSNFTLKIRSTKLEDSAMYFC', 'V-REGION': 'EPEVTQTPSHQVTQMGQEVILRCVPISNHLYFYWYRQILGQKVEFLVSFYNNEISEKSEIFDDQFSVERPDGSNFTLKIRSTKLEDSAMYFCASSE'}

Get amino acid sequence information about the Mus musculus J gene TRAJ32*02.

>>> tt.tr.get_aa_sequence(gene="TRAJ32*02", species="musmusculus")
{'FR4-IMGT': 'FGTGTLLSVKP', 'J-REGION': 'NYGGSGNKLIFGTGTLLSVKP'}

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

Query the list of all known TR genes / alleles.

Supported species

• "homosapiens"

• "musmusculus"

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 TR gene TRBV6-1.

>>> tt.tr.query(species="homosapiens", contains_pattern="TRBV6-1")
frozenset({'TRBV6-1*01'})

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

>>> tt.tr.query(species="musmusculus", precision="gene", functionality="ORF", contains_pattern="TRAV")
frozenset({'TRAV21/DV12', 'TRAV14D-1', 'TRAV13-3', 'TRAV9D-2', 'TRAV5D-4', 'TRAV12D-3', 'TRAV12-1', 'TRAV18', 'TRAV11D'})

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

Alias for tidytcells.tr.standardize().

tidytcells.tr.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 TR gene / allele symbol to be IMGT-compliant.

Supported species

• "homosapiens"

• "musmusculus"

Parameters:

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

• species (str) – Species to which the TR gene / allele belongs (see above for supported species). Defaults to "homosapiens".

• enforce_functional (bool) – If True, disallows TR 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:

Union[str, None]

Example usage

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

>>> tt.tr.standardize("aj1")
'TRAJ1'

The precision setting can truncate unnecessary information.

>>> tt.tr.standardize("TRBV6-4*01", precision="gene")
'TRBV6-4'

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

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

Mus musculus is a supported species.

>>> tt.tr.standardize("TCRBV22S1A2N1T", species="musmusculus")
'TRBV2'

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 "TCR" with "TR"                                     //e.g. TCRAV1-1 -> TRAV1-1
        replace "S" with "-"                                        //e.g. TRAV1S1 -> TRAV1-1
        replace "." with "-"                                        //e.g. TRAV1.1 -> TRAV1-1
        add back any missing backslashes                            //e.g. TRAV14DV4 -> TRAV14/DV4
        remove any unnecessary trailing zeros                       //e.g. TRAV1-01 -> TRAV1-1
        IF symbol is now in IMGT-compliant form:
            set standardization status as successful
            skip rest of standardization


        add "TR" to the beginning of the symbol if necessary   //e.g. AV1-1 -> TRAV1-1
        IF symbol is now in IMGT-compliant form:
            set standardization status as successful
            skip rest of standardization

        resolve compound TRAV/TRDV designation if necessary         //e.g. TRDV4 -> TRAV14/DV4 or TRAV14 -> TRAV14/DV4
        IF symbol is now in IMGT-compliant form:
            set standardization as successful
            skip rest of standardization

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