immuneML.encodings.reference_encoding package
Submodules
immuneML.encodings.reference_encoding.MatchedReceptorsEncoder module
- class immuneML.encodings.reference_encoding.MatchedReceptorsEncoder.MatchedReceptorsEncoder(reference: List[Receptor], max_edit_distances: dict, reads: ReadsType, sum_matches: bool, normalize: bool, name: str = None)[source]
Bases:
DatasetEncoder
Encodes the dataset based on the matches between a dataset containing unpaired (single chain) data, and a paired reference receptor dataset. For each paired reference receptor, the frequency of either chain in the dataset is counted.
This encoding can be used in combination with the Matches report.
When sum_matches and normalize are set to True, this encoder behaves similarly as described in: Yao, Y. et al. ‘T cell receptor repertoire as a potential diagnostic marker for celiac disease’. Clinical Immunology Volume 222 (January 2021): 108621. doi.org/10.1016/j.clim.2020.108621 with the only exception being that this encoder uses paired receptors, while the original publication used single sequences (see also: MatchedSequences encoder).
- Parameters:
reference (dict) – A dictionary describing the reference dataset file. Import should be specified the same way as regular dataset import. It is only allowed to import a receptor dataset here (i.e., is_repertoire is False and paired is True by default, and these are not allowed to be changed).
max_edit_distances (dict) – A dictionary specifying the maximum edit distance between a target sequence (from the repertoire) and the reference sequence. A maximum distance can be specified per chain, for example to allow for less strict matching of TCR alpha and BCR light chains. When only an integer is specified, this distance is applied to all possible chains.
reads (
ReadsType
) – Reads type signify whether the counts of the sequences in the repertoire will be taken into account. IfUNIQUE
, only unique sequences (clonotypes) are counted, and ifALL
, the sequence ‘count’ value is summed when determining the number of matches. The default value for reads is all.sum_matches (bool) – When sum_matches is False, the resulting encoded data matrix contains multiple columns with the number of matches per reference receptor chain. When sum_matches is true, the columns representing each of the two chains are summed together, meaning that there are only two aggregated sums of matches (one per chain) per repertoire in the encoded data.
:param To use this encoder in combination with the Matches report: :param sum_matches must be set to False. When sum_matches is set to True: :param this encoder behaves similarly to the encoder described by Yao: :param Y. et al. By default: :param sum_matches is False.: :param normalize: If True, the chain matches are divided by the total number of unique receptors in the repertoire (when reads = unique) or the total number of reads in the repertoire (when reads = all). :type normalize: bool
YAML Specification:
my_mr_encoding: MatchedReceptors: reference: format: VDJDB params: path: path/to/file.txt max_edit_distances: alpha: 1 beta: 0
- dataset_mapping = {'RepertoireDataset': 'MatchedReceptorsRepertoireEncoder'}
- encode(dataset, params: EncoderParams)[source]
immuneML.encodings.reference_encoding.MatchedReferenceUtil module
immuneML.encodings.reference_encoding.MatchedRegexEncoder module
- class immuneML.encodings.reference_encoding.MatchedRegexEncoder.MatchedRegexEncoder(motif_filepath: Path, match_v_genes: bool, reads: ReadsType, chains: list, name: str = None)[source]
Bases:
DatasetEncoder
Encodes the dataset based on the matches between a RepertoireDataset and a collection of regular expressions. For each regular expression, the number of sequences in the RepertoireDataset containing the expression is counted. This can also be used to count how often a subsequence occurs in a RepertoireDataset.
The regular expressions are defined per chain, and it is possible to require a V gene match in addition to the CDR3 sequence containing the regular expression.
This encoding can be used in combination with the Matches report.
- Parameters:
match_v_genes (bool) – Whether V gene matches are required. If this is True, a match is only counted if the
False. (V gene matches the gene specified in the motif input file. By default match_v_genes is) –
reads (
ReadsType
) – Reads type signify whether the counts of the sequences in the
:param repertoire will be taken into account. If
UNIQUE
: :param only unique sequences: :param (clonotypes) are counted: :param and ifALL
: :param the sequence ‘count’ value is: :param summed when determining the number of matches. The default value for reads is all.: :param motif_filepath: The path to the motif input file. This should be a tab separated file containing a :type motif_filepath: str :param column named ‘id’ and for every chain that should be matched a column containing the regex: :type column named ‘id’ and for every chain that should be matched a column containing the regex: <chain>_regex :param the V gene: :type the V gene: <chain>V :param The chains are specified by their three letter code: :param seeChain
.: :param In the simplest case: ==== ==========id TRB_regex ==== ========== 1 ACG 2 EDNA 3 DFWG ==== ==========
- Parameters:
sequences (when counting the number of occurrences of a given list of k-mers in TRB) –
id
TRB_regex
1
ACG
2
EDNA
3
DFWG
this (the contents of the motif file could look like) –
id
TRB_regex
1
ACG
2
EDNA
3
DFWG
example (It is also possible to test whether paired regular expressions occur in the dataset (for) – regular expressions
line. (matching both a TRA chain and a TRB chain) by specifying them on the same) –
specified (In a more complex case where both paired and unpaired regular expressions are) –
V (in addition to matching the) –
genes –
id
TRA_regex
TRAV
TRB_regex
TRBV
1
AGQ.GSS
TRAV35
S[APL]GQY
TRBV29-1
2
ASS.R.*
TRBV7-3
this –
id
TRA_regex
TRAV
TRB_regex
TRBV
1
AGQ.GSS
TRAV35
S[APL]GQY
TRBV29-1
2
ASS.R.*
TRBV7-3
YAML Specification:
my_mr_encoding: MatchedRegex: motif_filepath: path/to/file.txt match_v_genes: True reads: unique
- dataset_mapping = {'RepertoireDataset': 'MatchedRegexRepertoireEncoder'}
- encode(dataset, params: EncoderParams)[source]
immuneML.encodings.reference_encoding.MatchedRegexRepertoireEncoder module
- class immuneML.encodings.reference_encoding.MatchedRegexRepertoireEncoder.MatchedRegexRepertoireEncoder(motif_filepath: Path, match_v_genes: bool, reads: ReadsType, chains: list, name: str = None)[source]
Bases:
MatchedRegexEncoder
immuneML.encodings.reference_encoding.MatchedSequencesEncoder module
- class immuneML.encodings.reference_encoding.MatchedSequencesEncoder.MatchedSequencesEncoder(max_edit_distance: int, reference: List[ReceptorSequence], reads: ReadsType, sum_matches: bool, normalize: bool, name: str = None)[source]
Bases:
DatasetEncoder
Encodes the dataset based on the matches between a RepertoireDataset and a reference sequence dataset.
This encoding can be used in combination with the Matches report.
When sum_matches and normalize are set to True, this encoder behaves as described in: Yao, Y. et al. ‘T cell receptor repertoire as a potential diagnostic marker for celiac disease’. Clinical Immunology Volume 222 (January 2021): 108621. doi.org/10.1016/j.clim.2020.108621
- Parameters:
reference (dict) – A dictionary describing the reference dataset file. Import should be specified the same way as regular dataset import. It is only allowed to import a sequence dataset here (i.e., is_repertoire and paired are False by default, and are not allowed to be set to True).
max_edit_distance (int) – The maximum edit distance between a target sequence (from the repertoire) and the reference sequence.
reads (
ReadsType
) – Reads type signify whether the counts of the sequences in the repertoire will be taken into account. IfUNIQUE
, only unique sequences (clonotypes) are counted, and ifALL
, the sequence ‘count’ value is summed when determining the number of matches. The default value for reads is all.sum_matches (bool) – When sum_matches is False, the resulting encoded data matrix contains multiple columns with the number of matches per reference sequence. When sum_matches is true, all columns are summed together, meaning that there is only one aggregated sum of matches per repertoire in the encoded data.
:param To use this encoder in combination with the Matches report: :param sum_matches must be set to False. When sum_matches is set to True: :param this encoder behaves as described by Yao: :param Y. et al. By default: :param sum_matches is False.: :param normalize: If True, the sequence matches are divided by the total number of unique sequences in the repertoire (when reads = unique) or the total number of reads in the repertoire (when reads = all). :type normalize: bool
YAML Specification:
my_ms_encoding: MatchedSequences: reference: format: VDJDB params: path: path/to/file.txt max_edit_distance: 1
- encode(dataset, params: EncoderParams)[source]