API

class sim.Simulator(populations_number=1, number_of_susceptible_groups=1, seed=None, sampling_probability=False, memory_optimization=None)

The class which creates and runs simulations.

__init__(populations_number=1, number_of_susceptible_groups=1, seed=None, sampling_probability=False, memory_optimization=None)

Parameters

number_of_sites (int) – the number of mutable sites
populations_number (int) – the number of populations (demes)
number_of_susceptible_groups (int) – the number of susceptible groups (groups with different immunity response)
seed (float or None) – seed to generate simulation from. If None, then chosen at random
sampling_probability (bool or None) – whether we set sampling probability as a share of recovered individuals (True value) or we will set it explicitly. Default is False.
memory_optimization (bool or None) – if True, then memory optimization is conducted (useful for large number of possible haplotypes)

Epidemiological model

Simulator.set_transmission_rate(rate, haplotype=None)

Transmission rate is the the expected number of new infections from a single infected individual per time unit in the beginning of the epidemics when all but one of the hosts are susceptible. See Wikipedia - that is parameter beta in SIR model.

Parameters

rate (float) – transmission rate value.
haplotype (int or string or None) – haplotypes for which the new value is being set. See for details.

Note

In many methods skipping an argument (or setting it to None) allows filling in multiple entries. Methods will apply the settings to all possible values of this argument.

Simulator.set_recovery_rate(rate, haplotype=None)

Recovery rate is the inverse of the expected recovery time - non-negative float value. See Wikipedia - that is parameter gamma in SIR model.

Parameters

rate (float) – recovery rate value.
haplotype (int or string or None) –
haplotypes for which the new value is being set. See for details.

Simulator.set_sampling_rate(rate, haplotype=None)

Sampling rate: the rate at which infected individuals are sampled. The genealogy will be generated only for these samples. Alternatively, if sampling_probability is True, it will specify the fraction of recovered individuals which are sampled.

Parameters

rate (float) – sampling rate value.
haplotype (int or string or None) –
haplotypes for which the new value is being set. See for details.

Simulator.set_mutation_rate(rate=None, probabilities=None, haplotype=None, mutation=None)

This method allows setting the mutation rate and the weights for each single nucleotide substitution (given the mutation happened).

Parameters

rate (float or None) – mutation rate value (None would not change the old value).
probabilities (list of four non-negative integers or None) – weights of each single nucleotide substitution given mutation occured (None would not change the old values). See for example.
haplotype (int or string or None) –
the ancestral haplotype for the mutation. See for details.
mutation (int or None) – the id of position on the haplotype where mutation arises.

Note

Haplotypes can be set either by their id (which can be calculated by assuming that the haplotype is a quaternary number with A=0, T=1, C=2, G=3), or directly by the string. E.g. haplotype “AGT” can be referred by the same string or by id=0*4²+3*4¹+1*4⁰=13. One can also use “*” to indicate “any nucleotide”. In this case the changes will be applied to all the haplotypes matching the pattern. E.g. “A*T” corresponds to four haplotypes “AAT”, “ATT”, “ACT”, “AGT”. See for details.

Host immunity

Simulator.set_susceptibility_type(susceptibility_type, haplotype=None)

The type of immunity (or the susceptibility group) which an individual gets after being infected with a pathogen of a haplotype.

Parameters

susceptibility_type (int) – immunity group id.
haplotype (int or string or None) –
haplotypes for which the new value is being set. See for details.

Simulator.set_susceptibility(rate, haplotype=None, susceptibility_type=None)

Susceptibility is a multiplicative modifier of the transmission rate based on the susceptible host immunity with a certain susceptibility_type. It can decrease or increase the transmission rate of a particular haplotype to the individuals of said susceptibility_type.

Parameters

rate (float) – susceptibility value.
haplotype (int or string or None) –
haplotypes for which the new value is being set. See for details.
susceptibility_type (int or None) – immunity group id for which the new susceptibility value is being set.

Simulator.set_immunity_transition(rate, source=None, target=None)

The change of immunity without infection (e.g. due to vaccination or immunity loss with time).

Parameters

rate (float) – transition rate value.
source (int or None) – source immunity group id (None means that the new value will be set to all immunity groups as source).
target (int or None) – target immunity group id (None means that the new value will be set to all immunity groups as source).

Population model

Simulator.set_population_size(size, population=None)

Set the number of individuals in the population.

Parameters

size (int) – total number of individuals in the population.
population (int or None) – population for which the new population size is being set (in case of None the value will be updated for all populations).

Simulator.set_contact_density(value, population=None)

The relative number of contacts per time units.

Parameters

value (float) – contact density value.
population (int or None) – population for which the new contact density size is being set (in case of None the value will be updated for all populations).

Simulator.set_npi(parameters, population=None)

Setting conditions when lockdown in a population is imposed and lifted with the certain contact density during the lockdown.

Parameters

parameters (list of length 3 with float values) – list with three elements: contact density value during lockdown, fraction of infectious population when the lockdown is set, fraction of infectious population when lockdown is lifted.
population (int or None) – population for which the lockdown parameters are being set (in case of None the value will be updated for all populations).

Simulator.set_sampling_multiplier(multiplier, population=None)

The relative sampling in the population (multiplicative modifier). Sampling rate of each haplotype is modified by this factor.

Parameters

value (float) – sampling multiplier value.
population (int or None) – population for which the new sampling multiplier is being set (in case of None the value will be updated for all populations).

Simulator.set_migration_probability(probability=None, total_probability=None, source=None, target=None)

The probability that an individual from the population source is travelling to the population target.

Parameters

probability (float) – probability of migration value.
total_probability (bool) – if True, all the entries (except for the diagonal element) of row corresponding to source population is filled with probabilitie/(K-1). That represents individual travelling out of its population to a random destination.
source (int or None) – source population with infectious individual (None means that the new value will be set to all populations as source).
target (int or None) – target population with infectious individual (None means that the new value will be set to all populations as source).

Note

total_probability=float means that probability is the total probability to find an individual from population source outside of its population. All the entries (except for the diagonal) of the corresponding row of the migration probability matrix will be set to total_probability/(K-1), where K is the number of populations in the simulation.

Simulate

Simulator.simulate(iterations=1000, sample_size=None, epidemic_time=None, method='direct')

This methods performs the simulation. The simulation interrupts when either one of the following conditions is satisfied: the number of iterations equals iterations, the number of collected samples equals sample_size, ot the total virtual time of the epidemic exceeds time It can be called multiple times, changes of most parameters are allowed between simulation runs.

Parameters

iterations (int) – maximal number of iterations.
sample_size (int or None) – desired sample size.
epidemic_time (float or None) – virtual (model) time to be simulated.
method (string) – ‘direct’ for the exact algorithm, ‘tau’ for tau-leaping approximated algorithm.

Simulator.genealogy(seed=None)

Generates a genealogy based on the chain of events generated during all the instances of simulate() method.

Parameters: seed (int or None) – seed value (None for random seed).

Simulator.set_chain_events(file_name)

Allows to import chain of events directly from the .npy file

Parameters: file_name (str) – a name of the file (without the .npy extension)

Output

Simulator.output_newick(file_template='newick_output', file_path=None)

Outputs the result of simulation in the newick format.

Parameters

file_template (str) – template for the file name
file_path (str) – path to output file

Simulator.output_mutations(file_template='mutation_output', file_path=None)

Outputs the information about all mutations

Parameters

file_template (str) – template for the file name
file_path (str) – path to output file

Simulator.output_migrations(file_template='migrations', file_path=None)

Outputs the information about all migrations

Parameters

file_template (str) – template for the file name
file_path (str) – path to output file

Simulator.output_sample_data(output_print=False)

Show all information about sampling, time, place, etc.

Parameters: output_print (bool) – if Thue, it outputs data about each sample to the console. Data includes time of sampling, population and haplotype of sampled individual.
Returns: 3 lists with times, population ids and haplotypes of the sampled individuals

Simulator.output_epidemiology_timelines(step=1000, output_file=False)

Records simulation state changes over some period of time.

Parameters

step (str) – a number of steps which split the epidemiology timelines.
output_file (bool) – if True, the timeline is written in the output file

Simulator.output_chain_events(file_name='chain_events')

Outputs event chain.

Parameters

file_name – file name for the output
file_name – str

Simulator.output_state(): Outputs event chain and settings.

Visualization

Simulator.plot_infectious(population, haplotype, step_num, label_infectious, label_samples)

Creates plots for infectious and sampled individuals.

Parameters

population (int) – population id for the plot
haplotype (int or str) – haplotype for the plot
step_num (int) – number of steps which split the epidemiology timeline
label_infectious (str) – the label for the infectious plot in the plot legend
label_samples (str) – the label for the samples plot in the plot legend

Simulator.add_plot_infectious(population, haplotype, step_num=100, label_infectious=None, label_samples=None)

Add to plot the trajectories of the change of the number of infectious individuals over time.

Parameters

population (int) – population id for the plot
haplotype (int or str) – haplotype for the plot
step_num (int) – number of steps which split the epidemiology timeline
label_infectious (str or None) – the label for the infectious plot
label_samples (str or None) – the label for the samples plot

Simulator.add_plot_susceptible(population, susceptibility_type, step_num=100, label=None)

Add to plot the trajectories of the change of the number of susceptible individuals over time.

Parameters

population (int) – population id for the plot
haplotype (int or str) – haplotype for the plot
step_num (int) – number of steps which split the epidemiology timeline
label (str) – the label for the susceptible plot

Simulator.add_legend(): Add legend to the plot.

Simulator.add_title(name='Plot')

Add plot title.

Parameters: name (str) – the title for the plot

Simulator.plot(): Show plot with all the trajectories added by other methods.

Data retrieval

Simulator.get_data_susceptible(population, susceptibility_type, step_num)

Returns the list with the amount of sucseptible individuals over some period of time.

Parameters

population (int) – population to retrieve data from
susceptibility_type (int) – susceptibility type to retrieve data from
step_num (int) – number of steps which split the epidemiology timeline.

Returns

3 lists - amounts of susceptible individuals on the time points, time points themselves at which we retrieve amounts of individuals, and lockdowns data for the current epidemiology

Simulator.get_data_infectious(self, population, haplotype, step_num)

Returns the list with the amount of infectious individuals over some period of time.

Parameters

population (int) – population to retrieve data from
haplotype (int) – haplotype to retrieve data from
step_num (int) – number of steps which split the epidemiology timeline

Returns

3 lists - amounts of infectious individuals on the time points, time points themselves at which we retrieve amounts of individuals, and lockdowns data for the current epidemiology

Parameters

Simulator.print_basic_parameters(): This methods prints the basic parameters of the epidemiological model.

Simulator.print_populations(): This methods prints parameters of the population model.

Simulator.print_immunity_model(): This methods prints the basic parameters of the immunity model.

Simulator.print_all(basic_parameters=True, populations=True, immunity_model=True)

This methods prints all the parameters of the simulation.

Parameters

basic_parameters (bool) – whether to output the basic parameters of the epidemiological model.
populations (bool) – whether to output parameters of the population model.
immunity_model (bool) – whether to output parameters of the immunity model.

Miscellaneous

Simulator.citation(): Prints a citation of the paper in the console