immuneML.simulation package¶

Subpackages¶

Submodules¶

immuneML.simulation.Implanting module¶

class immuneML.simulation.Implanting.Implanting(dataset_implanting_rate: float, signals: List[immuneML.simulation.implants.Signal.Signal], name: str = '', repertoire_implanting_rate: Optional[float] = None, is_noise: bool = False)[source]¶

Bases: object

When performing a Simulation, one or more implantings can be specified. An implanting represents a set of signals which are implanted in a RepertoireDataset with given rates.

Multiple implantings may be specified in one simulation. In this case, each implanting will only affect its own partition of the dataset, so each repertoire can only receive implanted signals from one implanting. This way, implantings can be used to ensure signals do not overlap (one implanting per signal), or to ensure signals always occur together (multiple signals per implanting).

Parameters

signals (list) – The list of Signal objects to be implanted in a subset of the repertoires in a RepertoireDataset.
multiple signals are specified (When) –
means that all of these signals are implanted in (this) –
same repertoires in a RepertoireDataset (the) –
they may not be implanted in the same sequences (although) –
those repertoires (within) –
dataset_implanting_rate (float) – The proportion of repertoires in the RepertoireDataset in which the
should be implanted. When specifying multiple implantings (signals) –
sum of all dataset_implanting_rates (the) –
not exceed 1. (should) –
repertoire_implanting_rate (float) – The proportion of sequences in a Repertoire where a motif associated
one of the signals should be implanted. (with) –
is_noise (bool) – indicates whether the implanting should be regarded as noise; if it is True, the signals will be implanted as specified, but
repertoire/receptor in question will have negative class. (the) –

YAML specification:

simulations: # definitions of simulations should be under key simulations in the definitions part of the specification
    # one simulation with multiple implanting objects, a part of definition section
    my_simulation:
        my_implanting_1:
            signals:
                - my_signal
            dataset_implanting_rate: 0.5
            repertoire_implanting_rate: 0.25
        my_implanting_2:
            signals:
                - my_signal
            dataset_implanting_rate: 0.2
            repertoire_implanting_rate: 0.75

    # a simulation where the signals is present in the negative class as well (e.g. wrong labels, or by chance)
    noisy_simulation:
        positive_class_implanting:
            signals:
                - my_signal
            dataset_implanting_rate: 0.5
            repertoire_implanting_rate: 0.1 # 10% of the repertoire includes the signal in the positive class
        negative_class_implanting:
            signals:
                - my_signal
            is_noise: True # means that signal will be implanted, but the label will have negative class
            dataset_implanting_rate: 0.5
            repertoire_implanting_rate: 0.01 # 1% of negative class repertoires has the signal

    # in case of defining implanting for paired chain immune receptor data the simulation with implanting objects would be:
    my_receptor_simulation:
        my_receptor_implanting_1: # repertoire_implanting_rate is omitted in this case, as it is not applicable
            signals:
                - my_receptor_signal
            dataset_implanting_rate: 0.4 # 40% of the receptors will have signal my_receptor_signal implanted and 60% will not

immuneML.simulation.Simulation module¶

class immuneML.simulation.Simulation.Simulation(implantings: List[immuneML.simulation.Implanting.Implanting])[source]¶: Bases: object

immuneML.simulation.SimulationState module¶

class immuneML.simulation.SimulationState.SimulationState(signals: list, simulation: immuneML.simulation.Simulation.Simulation, dataset: immuneML.data_model.dataset.Dataset.Dataset, formats: List[str] = None, paths: dict = None, resulting_dataset: immuneML.data_model.dataset.Dataset.Dataset = None, result_path: pathlib.Path = None, name: str = None)[source]¶