Sweeps

Sweep provides the basic class framework to build methods which sweep over the population.

Overview:

• AbstractSweep

• HostProgressionSweep

• HouseholdSweep

• InitialDemographicsSweep

• InitialInfectedSweep

• InitialisePlaceSweep

• InitialHouseholdSweep

• InitialVaccineQueue

• InterventionSweep

• PlaceSweep

• QueueSweep

• SpatialSweep

• TravelSweep

• UpdatePlaceSweep

• StateTransitionMatrix

• TransitionTimeMatrix

class pyEpiabm.sweep.AbstractSweep

Abstract class for Population Sweeps.

__call__(time: float)

Run sweep over population.

Parameters:

time (float) – Current simulation time

bind_population(population: Population)

Set the population which the sweep will act on.

Parameters:

population (Population) – Population: Population to bind

static store_infection_periods(infector, infectee, time)

Sets the exposure_period of the infectee (defined as the time between the infector having status I and the infectee having status E. Also sets stores the infector’s latent period within the infectee (to be used in calculating the generation time). This is called during the daily sweeps.

Parameters:

• infector (Person) – Current primary case

• infectee (Person) – Current secondary case

• time (float) – Current simulation time

class pyEpiabm.sweep.HostProgressionSweep

Class for sweeping through population and updating host infection status and time to next infection status change.

__call__(time: float)

Sweeps through all people in the population, updates their infection status if it is time and assigns them their next infection status and the time of their next status change. Also updates their infectiousness.

Parameters:

time (float) – Current simulation time

asympt_uninf_testing_queue(person_list: list, time)

Adds asymptomatic and uninfected people to a testing queue with a given probability depedent on their status as either a care home resident or key worker.

Detailed description of the implementation can be found in github wiki: https://github.com/SABS-R3-Epidemiology/epiabm/wiki/Interventions#testing

Parameters:

• person_list (list) – list of (cell, person) tuples giving the list of people to be added to a testing queue and their cell.

• time (float) – current time point to determine whether uninfected indivuals should stop being considered as positive.

static set_infectiousness(person: Person, time: float)

Assigns the initial infectiousness of a person for when they go from the exposed infection state to the next state, either InfectAsympt, InfectMild or InfectGP. Also assigns the infection start time and stores it as an attribute of the person.

Called right after an exposed person has been given its new infection status in the call method below. This static method is non private as it is also used by the initial infected sweep to give new infected individuals an infectiousness.

Parameters:

• Person (Person) – Instance of person class with infection status attributes

• time (float) – Current simulation time

sympt_testing_queue(cell, person: Person)

Adds symptomatic people to a testing queue with a given probability depedent on their status as either a care home resident or a key worker.

Detailed description of the implementation can be found in github wiki: https://github.com/SABS-R3-Epidemiology/epiabm/wiki/Interventions#testing

Parameters:

• cell (Cell) – cell for which the person is a member of and therefore will be added to the testing queue of.

• person (Person) – symptomatic inndividual to be added to a testing queue.

update_next_infection_status(person: Person, time: float | None = None)

Assigns next infection status based on current infection status and on probabilities of transition to different statuses. Weights are taken from row in state transition matrix that corresponds to the person’s current infection status. Weights are then used in random.choices method to select person’s next infection status. Exception is carehome residents who die with probability=1 if reach ICU and probability=1-‘carehome_rel_prob_hosp’ if reach hospital.

Parameters:

• person (Person) – Instance of person class with infection status attributes

• time (float) – Current simulation time (if necessary for the method, default = None)

update_time_status_change(person: Person, time: float)

Calculates transition time as calculated in CovidSim, and updates the time_of_status_change for the given Person, given as the time until next infection status for a person who has a new infection status. If it is expected that the person will not transition again (for example in Recovered or Dead statuses), then the time of status change is set to infinity.

Parameters:

• person (Person) – Instance of Person class with InfectionStatus attributes

• time (float) – Current simulation time

class pyEpiabm.sweep.HouseholdSweep

Class to run the intra-household infections as part of the sweep function. Takes an individual person as input and tests a infection event against each susceptible member of their household. The resulting exposed person is added to an infection queue.

__call__(time: float)

Given a population structure, loops over infected members and considers whether they infected household members based on individual, and spatial infectiousness and susceptibility.

Parameters:

time (float) – Simulation time

class pyEpiabm.sweep.InitialDemographicsSweep(dem_file_params: Dict)

Class to sweep through the population at the beginning of the simulation and record their demographic information.

__call__(*args)

During the initial sweeps, this will be called, and will loop through everyone in the population and write their demographic data to a .csv file titled “demographics.csv”. This file will have one row per person, and will have the following columns: id (str), age_group (int, optional), location_x (float, optional), location_y (float, optional), kw_or_chr (str).

Furthermore, we write up the counts of how many people there are per age group within each cell in a contingency table .csv file titled “counts.csv”.

Note that kw_or_chr stands for ‘key worker or care home resident’. For kw_or_chr, ‘W’ refers to a key worker, ‘C’ refers to a care home resident and ‘X’ refers to a person who is neither.

class pyEpiabm.sweep.InitialisePlaceSweep

Class to initialise people in the “Place” class.

__call__(*args)

Given a population structure, updates the people present in each place at a specific timepoint. The explicit code handles the fixed population which are not changed later on in the simulation. To initialise the variable population (for example OutdoorSpace only has a variable population) one instance of UpdatePlaceSweep is called at the end to instantiate that.

Parameters:

time (float) – Current simulation time

create_age_weights(place, params)

Function to return a list of people in the correct age range to be added to a place, and the weights for the different age groups.

Parameters:

• place (Place) – Place to add people to

• params (dict) – Dictionary of parameters with age structure data

Returns:

• typing.List[Person] – List of people who may be in the place

• typing.List[float] – Corresponding weights for the person list

class pyEpiabm.sweep.InitialInfectedSweep

Class for sweeping through population at start of simulation and setting an initial number of infected people, with status InfectMild.

__call__(sim_params: dict)

Method that randomly chooses a user-supplied number of people in the population, changes their infection status to InfectMild and sets their time of next status change.

Parameters:

sim_params (dict) – Dictionary of simulation parameters

class pyEpiabm.sweep.InitialHouseholdSweep

Class to assign ages to people in households using the same age distribution model as CovidSim. For a discription of the analagous function in CovidSim see https://github.com/SABS-R3-Epidemiology/epiabm/wiki/Overview-of-the-Ferguson-Model.

__call__(sim_params)

Given a population structure, sorts the people into households of required size and if required loops over all people and assigns them an age dependant on their household size.

calc_number_of_children(household_size: int)

Method that calculates the amount of children in a household of three or more people.

Parameters:

household_size (int) – Number of people in a household

Returns:

int

Return type:

Number of children that will be in that household

household_allocation(population: Population)

Method that takes in a population and assigns them to different sized households according to a household size distribution.

Parameters:

Population (Population) – Instance of Population class

one_person_household_age(person: Person)

Method that assigns an age to the person in a one person household. A random number is first drawn that decides which set of conditions the person’s age should satisfy, e.g. if they are old or young and single etc. The person’s age is then repeatedly set until it is realistic e.g they are not a child living alone.

Parameters:

Person (Person) – Instance of Person class

three_or_more_person_household_ages(people: list)

Method that assigns ages to the people in a three person or larger sized household. The number of children is first calculated, this then decides which set of conditions the people’s ages should satisfy, e.g. if they are both old or it is one parent and one child etc. The people’s ages are then repeatedly set until they are realistic e.g their ages are compatible if they are a couple.

Parameters:

People (list) – List of three or more instances of Person class

two_person_household_ages(people)

Method that assigns ages to the people in a two person household. A random number is first drawn that decides which set of conditions the people’s ages should satisfy, e.g. if they are both old or it is one parent and one child etc. The people’s ages are then repeatedly set until they are realistic e.g their ages are compatible if they are a couple.

Parameters:

People (list) – List of two instances of Person class

class pyEpiabm.sweep.InitialVaccineQueue

Runs through the eligible population and adds people to a priority queue for vaccination, prioritised by age and added according to the uptake in each age group. For a description of how the method functions in the context of vaccination see https://github.com/SABS-R3-Epidemiology/epiabm/wiki/Interventions#vaccination

__call__(sim_params)

If vaccinations are to be performed, runs through the population and adds people to a priority queue if elligible for vaccination based on their priority level and the vaccination uptake in their age group.

assign_priority_group(person, age_thresholds)

Assigns priority group to each person based on age and whether they are a carehome resident. Lower numbers denote higher priority

Parameters:

• person (Person) – Person in population

• age_thresholds (list) – List of the minimum age in each priority group

Returns:

level – Priority level of 1, 2, 3, or 4

Return type:

int

class pyEpiabm.sweep.InterventionSweep

Class to sweep through all possible interventions. Check if intervention should be active based on policy time and number of infected individuals.

Possible interventions:

• case_isolation: Symptomatic case stays home.

• place closure: Place closure if number of infectious

  people or icu patients exceeds the threshold.

• household quarantine: Household quarantine if member

  is symptomatic.

• social distancing: Social distancing if number of infectious

  people exceeds the threshold.

• vaccination: Implement mass vaccination.

• disease_testing: PCR and LFT disease testing.

• travel_isolation: Isolate travelling individuals when

  introduced to population.

__call__(time)

Perform interventions that should take place.

Parameters:

time (float) – Simulation time

bind_population(population)

Set the population which the sweep will act on.

Parameters:

population (Population) – Population: Population to bind

class pyEpiabm.sweep.PlaceSweep

Class to run the place infections as part of the sweep function. Runs through infectious people within a cell and tests a infection event against each susceptible member of the place. The resulting exposed person is added to an infection queue.

__call__(time: float)

Given a population structure with places, loops over infected members of the place and considers whether they infected other people present, based on individual and place infectiousness and susceptibility.

Parameters:

time (float) – Current simulation time

class pyEpiabm.sweep.QueueSweep

Class to sweep through the enqueued persons in each cell and update their infection status.

__call__(time: float)

Function to run through the queue of people to be exposed.

Parameters:

time (float) – Simulation time

class pyEpiabm.sweep.SpatialSweep

Class to run the inter-cell space infections as part of the sweep function. Runs through cells and calculates their infectiousness parameter and calculates a poisson variable of how many people each cell should infect. Then chooses other cells, and persons within that cell to assign as infectee. Then tests a infection event against each susceptible member of the place. The resulting exposed person is added to an infection queue.

__call__(time: float)

Given a population structure, loops over cells and generates a random number of people to infect. Then decides which cells the infectees should be found in and considers whether an infection event occurs on individual and cell infectiousness and susceptibility.

Parameters:

time (float) – Current simulation time

bind_population(population)

Set the population which the sweep will act on.

Parameters:

population (Population) – Population: Population to bind

do_infection_event(infector: Person, infectee: Person, time: float)

Helper function which takes an infector and infectee, in different cells and tests whether contact between them will lead to an infection event.

Parameters:

• infector (Person) – Infector instance of Person

• infectee (Person) – Infectee instance of Person

• time (float) – Current simulation time

Returns:

List of people to infect

Return type:

List[Person]

find_infectees(infector_cell: Cell, possible_infectee_cells: List[Cell], number_to_infect: int)

Given a specific infector, a list of possible infectee cells, and the number of people needed to infect, follows a distance based implementation to create a list of infectees.

Parameters:

• infector_cell (Cell) – Infector cell instance of Cell

• possible_infectee_cells (List[Cell]) – List of possible cells to infect

• number_to_infect (int) – maximum number of people to infect

Returns:

infectee_list – List of exposed people to test an infection event

Return type:

List[Person]

find_infectees_Covidsim(infector: Person, possible_infectee_cells: List[Cell], number_to_infect: int)

Given a specific infector, a list of possible infectee cells, and the number of people needed to infect, follows Covidsim’s implementation to create a list of infectees.

Parameters:

• infector (Person) – Infector instance of person

• possible_infectee_cells (List[Cell]) – List of possible cells to infect

• number_to_infect (int) – Maximum number of people to infect

Returns:

List of people to infect

Return type:

List[Person]

class pyEpiabm.sweep.TravelSweep

Class to manage the introduction and removal of individuals. The number of individuals introduced depends on the number of total infectious cases in the population. All individuals are infectious when entering the population and will be distributed over microcells based on population density of the microcells. Individuals will be removed from the population after a certain number of days if they are isolated or quarantined.

__call__(time: float)

Based on number of infected cases in population, infected individuals are introduced to the population for a certain period. They are distributed over the microcells based on population density. They are not assigned permanently to a place for the duration of their visit.

Parameters:

time (float) – Simulation time

assign_microcell_and_household(number_individuals_introduced)

Assign individuals introduced to microcells based on population density of micorcells in the general population. A number of microcells equal to the number_individuals_introduced (or max number of microcells) with highest population density are selected. The individuals are assigned to one of these microcells by a uniform random choice between them. Individuals can end up in the same microcell. Next, individuals are assigned to an existing or a new household within the selected microcell.

Parameters:

number_individuals_introduced (int) – Infected individuals added to population at certain time step

check_leaving_individuals(time, person)

Check if individuals travel_end_time is reached. If interventions are active and travelling individual is in isolation and/or quarantine individuals leave after their travel_end_time is reached and they are out of isolation and/or quarantine.

Parameters:

• time (float) – Simulation time

• Person (Person) – Instance of Person class

create_introduced_individuals(time, number_individuals_introduced)

Create individuals and assign them an age and infectious status. This is based on age proportions if age is used in the model. Individuals are assigned an age between 15-80 years and are all infected (mild or asymptomatic).

Parameters:

• time (float) – Simulation time

• number_individuals_introduced (int) – Infected individuals added to population at certain time step

remove_leaving_individuals(time)

Remove individuals after their travel_end_time is reached from cell, microcell and household.

Parameters:

time (float) – Simulation time

class pyEpiabm.sweep.UpdatePlaceSweep

Class to update people in the “Place” class.

__call__(time: float)

Given a population structure, updates the people present in each place at a specific timepoint.

Parameters:

time (float) – Current simulation time

update_place_group(place, mean_capacity: float = 25, power_law_params: list | None = None, group_index: int | None = None, group_size: int = 0, person_list: list | None = None, person_weights: list | None = None)

Specific method to update people in a place or place group.

Parameters:

• place (Place) – Place to change

• mean_capacity (int) – Average number of people in this place

• power_law_params (list) – Should only be given for workplaces, contains the further parameters used to calculate place_size. List entries should take the order [Maximum size, Offset, Power]

• group_index (int) – If specified, the index of the group to be added to

• group_size (int) – Average size of the groups in each place

• person_list (list) – List of people that may be present in the place

• person_weights (list) – Weights for people in list

class pyEpiabm.sweep.StateTransitionMatrix(coefficients: Dict[str, List[float]], multipliers: Dict[str, List[float]], use_ages=False)

Class to generate and edit the state transition matrix

static create_empty_state_transition_matrix()

Builds the structure of the state transition matrix that is used in the host progression sweep. Labels the rows and the columns with the infection status. Fill the rest of the dataframe with zero probabilities of transition.

Returns:

Symmetric matrix in the form of a dataframe

Return type:

pd.DataFrame

create_state_transition_matrix(coeff: Dict[str, List[float]])

Fill the state transition matrix with the non-zeros probabilities. The rows are associated to the current infection status, the columns to the next infection status, and the elements are the probabilities to go from one state to another. For example, the element ij in the matrix is the probability of someone with current infection status associated with the row i to move to the infection status associated with the column j.

Parameters:

coefficients (Dict[str, List[float]]) – Dictionary of age-dependent lists for matrix coefficients

Returns:

Matrix in the form of a dataframe

Return type:

pd.DataFrame

create_waning_transition_matrix(coeff: Dict[str, List[float]])

Fill the waning transition matrix with lambda functions corresponding to a linear combination of state transition probabilities and the probability of protection from this change in state. The rows are associated to the current infection status, the columns to the next infection status, and the elements are the probabilities to go from one state to another. For example, the element i,j in the matrix is the probability of someone with current infection status associated with the row i to move to the infection status associated with the column j. Further explanation of this matrix can be found at https://github.com/SABS-R3-Epidemiology/epiabm/wiki/Parameters#waning-infection-matrix

Parameters:

coefficients (Dict[str, List[float]]) – Dictionary of lists for rate multipliers

Returns:

Matrix in the form of a dataframe

Return type:

pd.DataFrame

remove_age_dependence()

Conducts weighted average over age groups to remove age dependence in the state transition matrix.

update_probability(current_infection_status_row: InfectionStatus, next_infection_status_column: InfectionStatus, new_probability: float)

Method to manually update a transition probability in the transition state matrix.

Parameters:

• current_infection_status_row (InfectionStatus) – Infection status corresponding to the row where the probability will be updated

• next_infection_status_column (InfectionStatus) – Infection status corresponding to the column where the probability will be updated

• new_probability (float) – Updated transition probability value

class pyEpiabm.sweep.TransitionTimeMatrix

Class to generate the matrix with transition times

create_transition_time_matrix()

Fills the transition time matrix with InverseCdf objects, where the distributions of times of transition are defined. For example, the element ij in the matrix is the InverseCdf object for defining the transition time of someone with current infection status associated with the row i to move to the infection status associated with the columns j. Transitions that we do not expect to happen are assigned a value of -1.0 in the matrix, so it will not pass silently if these are accessed accidentally.

Returns:

Matrix in the form of a dataframe

Return type:

pd.DataFrame

update_transition_time_with_float(current_infection_status_row: InfectionStatus, next_infection_status_column: InfectionStatus, new_transition_time: float)

Method to manually update a transition time in the transition time matrix.

Parameters:

• current_infection_status_row (InfectionStatus) – Infection status corresponding to the row where the probability will be updated

• next_infection_status_column (InfectionStatus) – Infection status corresponding to the column where the probability will be updated

• new_transition_time (float) – Updated transition time value

update_transition_time_with_icdf(current_infection_status_row: InfectionStatus, next_infection_status_column: InfectionStatus, new_transition_time_icdf: ndarray, new_transition_time_icdf_mean: float)

Method to manually update a transition time in the transition time matrix.

Parameters:

• current_infection_status_row (InfectionStatus) – Infection status corresponding to the row where the probability will be updated

• next_infection_status_column (InfectionStatus) – Infection status corresponding to the column where the probability will be updated

• new_transition_time_icdf (list) – The associated list of icdf values if wanting to specify a new distribution for a transition time

• new_transition_time_icdf_mean (float) – The mean of the icdf if specifying a new distribution for a transition time