immuneML.encodings.reference_encoding package

Submodules

immuneML.encodings.reference_encoding.MatchedReceptorsEncoder module

class immuneML.encodings.reference_encoding.MatchedReceptorsEncoder.MatchedReceptorsEncoder(reference: List[immuneML.data_model.receptor.Receptor.Receptor], max_edit_distances: dict, reads: immuneML.util.ReadsType.ReadsType, sum_matches: bool, normalize: bool, name: Optional[str] = None)

Bases: immuneML.encodings.DatasetEncoder.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. If UNIQUE, only unique sequences (clonotypes) are counted, and if ALL, 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:
            path: path/to/file.txt
            format: VDJDB
        max_edit_distances:
            alpha: 1
            beta: 0

static build_object(dataset=None, **params)

dataset_mapping = {'RepertoireDataset': 'MatchedReceptorsRepertoireEncoder'}

encode(dataset, params: immuneML.encodings.EncoderParams.EncoderParams)

immuneML.encodings.reference_encoding.MatchedReceptorsRepertoireEncoder module

class immuneML.encodings.reference_encoding.MatchedReceptorsRepertoireEncoder.MatchedReceptorsRepertoireEncoder(reference: List[immuneML.data_model.receptor.Receptor.Receptor], max_edit_distances: dict, reads: immuneML.util.ReadsType.ReadsType, sum_matches: bool, normalize: bool, name: Optional[str] = None)

Bases: immuneML.encodings.reference_encoding.MatchedReceptorsEncoder.MatchedReceptorsEncoder

immuneML.encodings.reference_encoding.MatchedReferenceUtil module

class immuneML.encodings.reference_encoding.MatchedReferenceUtil.MatchedReferenceUtil

Bases: object

Utility class for MatchedSequencesEncoder and MatchedReceptorsEncoder

static prepare_reference(reference_params: dict, location: str, paired: bool)

immuneML.encodings.reference_encoding.MatchedRegexEncoder module

class immuneML.encodings.reference_encoding.MatchedRegexEncoder.MatchedRegexEncoder(motif_filepath: pathlib.Path, match_v_genes: bool, reads: immuneML.util.ReadsType.ReadsType, chains: list, name: Optional[str] = None)

Bases: immuneML.encodings.DatasetEncoder.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 if ALL: :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 see Chain.: :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

static build_object(dataset=None, **params)

dataset_mapping = {'RepertoireDataset': 'MatchedRegexRepertoireEncoder'}

encode(dataset, params: immuneML.encodings.EncoderParams.EncoderParams)

static get_documentation()

immuneML.encodings.reference_encoding.MatchedRegexRepertoireEncoder module

class immuneML.encodings.reference_encoding.MatchedRegexRepertoireEncoder.MatchedRegexRepertoireEncoder(motif_filepath: pathlib.Path, match_v_genes: bool, reads: immuneML.util.ReadsType.ReadsType, chains: list, name: Optional[str] = None)

Bases: immuneML.encodings.reference_encoding.MatchedRegexEncoder.MatchedRegexEncoder

immuneML.encodings.reference_encoding.MatchedSequencesEncoder module

class immuneML.encodings.reference_encoding.MatchedSequencesEncoder.MatchedSequencesEncoder(max_edit_distance: int, reference: immuneML.data_model.receptor.receptor_sequence.ReceptorSequenceList.ReceptorSequenceList, reads: immuneML.util.ReadsType.ReadsType, sum_matches: bool, normalize: bool, name: Optional[str] = None)

Bases: immuneML.encodings.DatasetEncoder.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. If UNIQUE, only unique sequences (clonotypes) are counted, and if ALL, 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:
            path: path/to/file.txt
            format: VDJDB
        max_edit_distance: 1

static build_object(dataset=None, **params)

dataset_mapping = {'RepertoireDataset': 'MatchedSequencesRepertoireEncoder'}

encode(dataset, params: immuneML.encodings.EncoderParams.EncoderParams)

immuneML.encodings.reference_encoding.MatchedSequencesRepertoireEncoder module

class immuneML.encodings.reference_encoding.MatchedSequencesRepertoireEncoder.MatchedSequencesRepertoireEncoder(max_edit_distance: int, reference: immuneML.data_model.receptor.receptor_sequence.ReceptorSequenceList.ReceptorSequenceList, reads: immuneML.util.ReadsType.ReadsType, sum_matches: bool, normalize: bool, name: Optional[str] = None)

Bases: immuneML.encodings.reference_encoding.MatchedSequencesEncoder.MatchedSequencesEncoder

immuneML.encodings.reference_encoding.SequenceMatchingSummaryType module

class immuneML.encodings.reference_encoding.SequenceMatchingSummaryType.SequenceMatchingSummaryType(value)

Bases: enum.Enum

An enumeration.

CLONAL_PERCENTAGE = 1

COUNT = 0

PERCENTAGE = 2

Module contents