tidytcells.tr

Functions to manage TR gene data.

Functions

tidytcells.tr.query(species=None, 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().

Return type:

ReceptorGene

tidytcells.tr.standardize(symbol=None, species=None, enforce_functional=None, allow_subgroup=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) –

  Can be specified to standardize 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 standardization for Homo sapiens, then Mus musculus. Defaults to "homosapiens".

  Note

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

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

• allow_subgroup (bool) – If True, allows valid subgroups (as well as more specific gene/allele symbos) to pass standardization. If False, the supplied symbol must point to at least a specific gene. Defaults to False.

• log_failures (bool) – Report standardization 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 standardization fails. Deprecated in favour of log_failures.

Returns:

A standardized receptor gene wrapped in a ReceptorGene object. For details on how to use this output, please refer to the class documentation.

Return type:

ReceptorGene

Example usage

TR standardized results will be returned as a ReceptorGene. When standardization is a success, attributes ‘allele’, ‘gene’ and ‘subgroup’ can be used to retrieve the corrected information.

>>> result = tt.tr.standardize("TRAV1-1*01")
>>> result.is_standardized
True
>>> result.allele
'TRAV1-1*01'
>>> result.gene
'TRAV1-1'
>>> result.subgroup
'TRAV1'

Attributes ‘allele’, ‘gene’ and ‘subgroup’ only return a result if the symbol could be standardized up to that level. Attribute ‘symbol’ is never None for a successful standardization, and always returns the most detailed available result between ‘allele’, ‘gene’ and ‘subgroup’.

>>> tt.tr.standardize("TRAV1-1*01").symbol
'TRAV1-1*01'
>>> tt.tr.standardize("TRAV1-1").allele
None
>>> tt.tr.standardize("TRAV1-1").gene
'TRAV1-1'
>>> tt.tr.standardize("TRAV1-1").symbol
'TRAV1-1'

Non-standardized input strings will intelligently be corrected to IMGT-compliant gene / allele symbols.

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

The enforce_functional setting will cause non-functional genes or alleles to be rejected. For failed standardizations, the ‘error’ attribute explains why the standardization failed, and the ‘attempted_fix’ attribute contains the best attempted result found during standardization.

>>> result = tt.tr.standardize("tcrBV1", enforce_functional=True)
>>> result.is_standardized
False
>>> result.error
'Gene has no functional alleles'
>>> result.attempted_fix
'TRBV1'

Known synonyms are included in the standardization

>>> tt.tr.standardize("V4P").symbol
'TRGV11'

Mus musculus is a supported species.

>>> tt.tr.standardize("TRBV1", species="musmusculus").gene
'TRBV1'

Other available properties are ‘original_input’, ‘species’, ‘receptor_type’, ‘locus’ and ‘gene_type’.

>>> result = tt.tr.standardize("TRAV01-01")
>>> result.symbol
'TRAV1-1'
>>> result.original_input
'TRAV01-01'
>>> result.species
'homosapiens'
>>> result.receptor_type
'TR'
>>> result.locus
'TRA'
>>> result.gene_type
'V'

Utility method ‘get_all_alleles’ can be used to retrieve all (functional) alleles for a given symbol.

>>> result = tt.tr.standardize("TRAV1-1")
>>> result.get_all_alleles()
['TRAV1-1*01', 'TRAV1-1*02']

>>> result = tt.tr.standardize("TRAV15")
>>> result.get_all_alleles(enforce_functional=True)
[]
>>> result.get_all_alleles(enforce_functional=True)
['TRAV15*02', 'TRAV15*03', 'TRAV15*01']

Utility method ‘get_aa_sequences’ can be used to retrieve known amino acid sequences per allele. Using sequence_type ‘ALL’ shows all available sequence data for each allele.

>>> result = tt.tr.standardize("TRAV1-1*01")
>>> result.get_aa_sequences(sequence_type="CDR1")
{'TRAV1-1*01': 'TSGFYG'}
>>> result.get_aa_sequences(sequence_type="CDR2")
{'TRAV1-1*01': 'NALDGL'}
>>> result = tt.tr.standardize("TRAJ15")
>>> result.get_aa_sequences(sequence_type="ALL")
{
'TRAJ15*01': {
    'J-MOTIF': 'FGKG', 'J-REGION': 'NQAGTALIFGKGTTLSVSS', 'functionality': 'F'
    },
'TRAJ15*02': {
    'J-MOTIF': 'FGKG', 'J-REGION': 'NQAGTALIFGKGTHLSVSS', 'functionality': 'F'
    }
}

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.

0. sanity-check input
Skip standardization if invalid parameters are passed (invalid amino acids in sequence, invalid species, etc)

1. attempt standardization
IF symbol is already in IMGT-compliant form:
    set standardization status as successful, skip to step 2

IF symbol is a known deprecated symbol:
    overwrite symbol with current IMGT-compliant symbol
    set standardization status as successful, skip to step 2.

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 to step 2


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 to step 2

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 status as successful, skip to step 2

try removing "-1" from the end of the symbol                //e.g. TRAV1-1 -> TRAV1
IF symbol is now a valid IMGT-compliant *gene* (do not correct to subgroup):
    set standardization status as successful, skip to step 2

set standardization status as failed

2. finalisation
IF standardization has not failed:
    consider standardization a success

RETURN :py:class:`~tidytcells.result.ReceptorGene`