Routines

Routine provides various methods to act upon or create a population, or members of it.

Overview:

• AbstractPopulationFactory

• FilePopulationFactory

• ToyPopulationFactory

• Simulation

class pyEpiabm.routine.AbstractPopulationFactory

Abstract class for population creation.

class pyEpiabm.routine.FilePopulationFactory

Class that creates a population based on an input .csv file.

static add_households(microcell: Microcell, household_number: int)

Groups people in a microcell into households together.

Parameters:

• microcell (Microcell) – Microcell containing all person objects to be considered for grouping

• household_number (int) – Number of households to form

static find_cell(population: Population, cell_id: str, current_cell: Cell)

Returns cell with given ID in population, creates one if current cell has another ID. As input is sorted on cell no cell will exist with that ID.

Parameters:

• population (Population) – Population containing target cell

• cell_id (str) – ID for target cell

• current_cell (Cell or None) – Cell object of current cell

Returns:

Cell with given ID in population

Return type:

Cell

static make_pop(input_file: str, random_seed: int = None, time: float = 0)

Initialize a population object from an input csv file, with one row per microcell. A uniform multinomial distribution is used to distribute the number of people into the different households within each microcell. A random seed may be specified for reproducible populations.

Input file contains columns:

• cell: ID code for cell

• microcell: ID code for microcell

• location_x: The x coordinate of the parent cell location

• location_y: The y coordinate of the parent cell location

• household_number: Number of households in that microcell

• place_number: Number of places in that microcell

• Any number of columns with titles from the InfectionStatus enum (such as InfectionStatus.Susceptible), giving the number of people with that status in that cell

Parameters:

• input_file (str) – Path to input file

• random_seed (int) – Seed for reproducible household and place distribution

• time (float) – Start time of simulation where this population is used (default 0)

Returns:

Population object with individuals distributed into households

Return type:

Population

static print_population(population: Population, output_file: str)

Outputs population as .csv file, in format usable by the make_pop() method. Used for verification, or saving current simulation state. Note the current household distribution is random, and so the seed for household allocation must also be recorded to precisely save the simulation state.

WARNING: This function is only tested with versions of pandas > 1.4, and may not function correctly in older cases. This will include cases where the user is running python 3.7 or older versions.

Parameters:

• population (Population) – Population object to output

• output_file (str) – Path to output file

class pyEpiabm.routine.ToyPopulationFactory

Class that creates a toy population for use in the simple python model.

static add_households(population: Population, household_number: int)

Groups people in a microcell into households together.

Parameters:

• population (Population) – Population containing all person objects to be considered for grouping

• household_number (int) – Number of households to form

static add_places(population: Population, place_number: float)

Generates places within a Population.

Parameters:

• population (Population) – Population where Place s will be added

• place_number (float) – Average number of places to generate per Microcell

static assign_cell_locations(population: Population, method: str = 'random')

Assigns cell locations based on method provided. Possible methods:

• ‘random’: Assigns all locations randomly within unit square

• ‘uniform_x’: Spreads points evenly along x axis in range (0, 1)

• ‘grid’: Distributes points according to a square grid within a unit square. There will be cells missing in the last row if the input is not a square number

Parameters:

• population (Population) – Population containing all cells to be assigned locations

• method (str) – Method of determining cell locations

static make_pop(pop_params: Dict)

Initialize a population object with a given population size, number of cells and microcells. A uniform multinomial distribution is used to distribute the number of people into the different microcells.

There is also an option to distribute people into households or places. file_params contains (with optional args as (*)):

• population_size: Number of people in population

• cell_number: Number of cells in population

• microcell_number: Number of microcells in each cell

• household_number: Number of households in each microcell (*)

• place_number: Average number of places in each microcell (*)

• population_seed: Random seed for reproducible populations (*)

Parameters:

file_params (dict) – Dictionary of parameters for generating a population

Returns:

Population object with individuals distributed into households

Return type:

Population

class pyEpiabm.routine.Simulation

Class to run a full simulation.

compress_csv()

Compresses the infection history csvs when they are written.

configure(population: Population, initial_sweeps: List[AbstractSweep], sweeps: List[AbstractSweep], sim_params: Dict, file_params: Dict, inf_history_params: Dict = None)

Initialise a population structure for use in the simulation.

sim_params Contains:

• simulation_start_time: The initial time for the simulation

• simulation_end_time: The final time to stop the simulation

• initial_infected_number: The initial number of infected individuals in the population

• simulation_seed: Random seed for reproducible simulations

• include_waning: Boolean to determine whether immunity waning is included in the simulation

file_params Contains:

• output_file: String for the name of the output .csv file

• output_dir: String for the location of the output file, as a relative path

• spatial_output: Boolean to determine whether a spatial output should be used

• age_stratified: Boolean to determine whether the output will be age stratified

inf_history_params Contains:

• output_dir: String for the location for the output files, as a relative path

• status_output: Boolean to determine whether we need a csv file containing infection status values

• infectiousness_output: Boolean to determine whether we need a csv file containing infectiousness (viral load) values

• secondary_infections_output: Boolean to determine whether we need a csv file containing secondary infections and R_t values

• serial_interval_output: Boolean to determine whether we need a csv file containing serial interval data

• generation_time_output: Boolean to determine whether we need a csv file containing generation time data

• compress: Boolean to determine whether we compress the infection history csv files

Parameters:

• population (Population) – Population structure for the model

• pop_params (dict) – Dictionary of parameter specific to the population

• initial_sweeps (List) – List of sweeps used to initialise the simulation

• sweeps (List) – List of sweeps used in the simulation. Queue sweep and host progression sweep should appear at the end of the list

• sim_params (dict) – Dictionary of parameters specific to the simulation used and used as input for call method of initial sweeps

• file_params (dict) – Dictionary of parameters specific to the output file

• inf_history_params (dict) – This is short for ‘infection history file parameters’ and we will use the abbreviation ‘ih’ to refer to infection history throughout this class. If status_output, infectiousness_output, secondary_infections_output, serial_interval_output and generation_time_output are all False, then no infection history csv files are produced (or if the dictionary is None). These files contain the infection status, infectiousness and secondary infection counts of each person every time step respectively. The EpiOS tool (https://github.com/SABS-R3-Epidemiology/EpiOS) samples data from these files to mimic real life epidemic sampling techniques. These files can be compressed when ‘compress’ is True, reducing the size of these files.

run_sweeps()

Iteration step of the simulation. First the initialisation sweeps configure the population on the first timestep. Then at each subsequent timestep the sweeps run, updating the population. At each timepoint, a count of each infection status is written to file. Note that the elements of initial sweeps take the sim_params dict as an argument for their call method but the elements of sweeps take time as an argument for their call method.

static set_random_seed(seed)

Set random seed for all subsequent operations. Should be used before population configuration to control this process as well.

Parameters:

seed (int) – Seed for RandomState

write_to_Rt_file(times: array)

Records the number of secondary infections of each Person at the time they first became infected. Each Person may have multiple entries if they have been infected multiple times. Also records the R_t value for each time step.

Parameters:

times (np.array) – An array of all time steps of the simulation

write_to_file(time)

Records the count number of a given list of infection statuses and writes these to file.

Parameters:

time (float) – Time of output data

write_to_generation_time_file(times: array)

Records the intervals between an infector and an infectee getting exposed to provide an overall generation time for each time-step of the epidemic. This can be used as a histogram of values for each time step.

Parameters:

times (np.array) – An array of all time steps of the simulation

write_to_ih_file(time, output_option: str)

Records the infection history of the individual people and writes these to file.

Parameters:

• time (float) – Time of output data

• output_option (str) – Determines if you write data of infection status where output_option=”status” and/or infectiousness where output_option=”infectiousness”

write_to_serial_interval_file(times: array)

Records the intervals between an infector and an infectee getting infected to provide an overall serial interval for each time-step of the epidemic. This can be used as a histogram of values for each time step.

Parameters:

times (np.array) – An array of all time steps of the simulation