tidytcells.tr

Functions to manage TR gene data.

Functions

tidytcells.tr.get_aa_sequence(gene: str, species: str = 'homosapiens') → Dict[str, str]

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

Supported species

• "homosapiens"

Note

This function currently only supports V genes. Support for J genes is planned for the future.

Parameters:

• gene (str) – Standardized gene name. The gene must be specified to the level of the allele. Note that some genes, notably the non-functional ones, 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".

Returns:

A dictionary with keys corresponding to names of different sequence regions within the gene, 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'}

tidytcells.tr.query(species: str = 'homosapiens', precision: str = 'allele', functionality: str = 'any', contains_pattern: str | None = None) → FrozenSet[str]

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(gene: str | None = None, species: str = 'homosapiens', enforce_functional: bool = False, precision: str = 'allele', on_fail: str = 'reject', suppress_warnings: bool = False) → str

Attempt to standardize a TR gene name to be IMGT-compliant.

Supported species

• "homosapiens"

• "musmusculus"

Parameters:

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

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

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

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

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 behaviour as set by on_fail.

Return type:

Union[str, None]

Example usage

Input strings will intelligently be corrected to IMGT-compliant gene 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)
UserWarning: 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 gene symbol without modification

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

        IF gene symbol is a known deprecated symbol:
            overwrite gene 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 gene symbol is now in IMGT-compliant form:
            set standardization status as successful
            skip rest of standardization


        add "TR" to the beginning of the gene symbol if necessary   //e.g. AV1-1 -> TRAV1-1
        IF gene 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 gene 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 gene symbol //e.g. TRAV1 -> TRAV1-1
        IF gene 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 gene symbol

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