episimmer.model

Base Model API

class BaseModel(name)

Base class for disease models in Episimmer.

Parameters

name (str) – Name of Disease Model

state_proportion_checker()

Checks whether the state proportions add up to 1.

Return type

None

initialize_states(agents)

Initializes the states of the agents based on state proportions.

Parameters

agents (Dict[str, episimmer.agent.Agent]) – A dictionary mapping from agent indices to agent objects

Return type

None

find_next_state(agent, agents)

Returns next state of the agent according to the transition functions between the states and the schedule time left.

Parameters

• agent (episimmer.agent.Agent) – The agent whose next state is to be determined

• agents (Dict[str, episimmer.agent.Agent]) – A dictionary mapping from agent indices to agent objects

Returns

The new state of the agent, Schedule time left for the agent in current state

Return type

Tuple[str, int]

set_state_color(state, infectious)

Sets the state color based on whether the state is infectious or not.

Parameters

• state (str) – State that needs color assignment

• infectious (bool) – Whether the state is infectious or not

Return type

None

update_event_infection(event_info, location, agents_obj)

Updates the agents with event probabilities of all the events the agents attended.

Parameters

• event_info (Dict[str, Union[float, str, List[str]]]) – Dictionary containing location and participating agents of an event

• location (episimmer.location.Location) – Location object

• agents_obj (episimmer.read_file.ReadAgents) – An object of class ReadAgents containing all agents

Return type

None

set_event_contribution_fn(fn)

Sets the event contribute function specifying the contribution of an agent to the ambient infection of an event. It must be set to a Callable function with four parameters : agent, event_info, location and time_step. agent refers to the current agent responsible for contribution to ambient infection. event_info and location refer to the current event’s parameters from the event and location files. time_step refers to the current time step.

An example with the Stochastic Model is given below

def event_contribute_fn(agent,event_info,location,current_time_step):
        if agent.state=='Infected':
            return 1
        return 0

class UserModel(model.StochasticModel):
    def __init__(self):
        .
        .
        .
        self.set_event_contribution_fn(event_contribute_fn)

Parameters

fn (Callable) – User-defined function used to determine the contribution of an agent to an ambient infection

Return type

None

set_event_receive_fn(fn)

Sets the event receive function specifying the probability of infection for an agent from the ambient infection of an event. It must be set to a Callable function with four parameters : agent, ambient_infection, event_info, location and time_step. agent refers to the current agent receiving infection from participating in the event, ambient_infection is the total infection accumulated by all the agents in the event (calculated by event_contribution_fn). event_info and location refer to the current event’s parameters from the event and location files. time_step refers to the current time step.

An example with the Stochastic Model is given below

def event_receive_fn(agent,ambient_infection,event_info,location,current_time_step):
    beta=0.001
    return ambient_infection*beta

class UserModel(model.StochasticModel):
    def __init__(self):
        .
        .
        .
        self.set_event_receive_fn(event_receive_fn)

Parameters

fn (Callable) – User-defined function used to determine the probability of an agent receiving an ambient infection

Return type

None

set_external_prevalence_fn(fn)

Sets the external prevalence function to specify probability of infection due to external prevalence. It must be set to a Callable function with two parameters : agent and time_step. agent refers to the current agent affected by external prevalence and time_step refers to the current time step.

An example with the Stochastic Model is given below

def external_prevalence(agent, current_time_step):
    if(agent.info['Compliance'] == 'High'):
        return 0.1
    elif(agent.info['Compliance'] == 'Medium'):
        return 0.2
    elif(agent.info['Compliance'] == 'Low'):
        return 0.35

class UserModel(model.ScheduledModel):
    def __init__(self):
        .
        .
        .
        self.set_external_prevalence_fn(external_prevalence)

Parameters

fn (Callable) – User-defined function for specifying probability of infection due to external prevalence

Return type

None

states_checker(states)

Checks whether the states list passed belong to the states in the disease model created.

Parameters

states (List[str]) – List of states to be checked

Returns

Boolean representing whether valid states have been passed

Return type

bool

set_symptomatic_states(states)

Sets the symptomatic states of the disease model. These agents in these states have visible symptoms of the disease.

An example with the Stochastic Model is given below

class UserModel(model.StochasticModel):
  def __init__(self):
    individual_types=['Susceptible','Exposed','Asymptomatic','Symptomatic','Recovered']
    infected_states=['Asymptomatic','Symptomatic']
    state_proportion={
              'Susceptible':0.99,
              'Exposed':0,
              'Recovered':0,
              'Asymptomatic':0,
              'Symptomatic':0.01
            }
    model.StochasticModel.__init__(self,individual_types,infected_states,state_proportion)
    self.set_transition('Susceptible', 'Exposed', self.p_infection())
    self.set_transition('Exposed', 'Symptomatic', self.p_standard(0.15))
    self.set_transition('Exposed', 'Asymptomatic', self.p_standard(0.2))
    self.set_transition('Symptomatic', 'Recovered', self.p_standard(0.1))
    self.set_transition('Asymptomatic', 'Recovered', self.p_standard(0.1))

    self.set_event_contribution_fn(event_contribute_fn)
    self.set_event_receive_fn(event_receive_fn)
    self.set_symptomatic_states(['Symptomatic'])

Parameters

states (List[str]) – List of disease model states that are symptomatic

Return type

None

get_final_infection_prob(fn, p_infected_states_list, agent, agents)

Returns the final infection probability for an agent based on

• Interactions (Individual and Probabilistic)

• Events (Regular and One-Time)

• External Prevalence

Parameters

• fn (Optional[Callable]) – User-defined function defining the probability of infection based on individual/probabilistic interactions

• p_infected_states_list (Optional[List[float]]) – List of probabilities that can be used in the user-defined function fn

• agent (episimmer.agent.Agent) – Current agent object

• agents (Dict[str, episimmer.agent.Agent]) – A dictionary mapping from agent indices to agent objects

Return type

float

Stochastic Model API

class StochasticModel(individual_state_types, infected_states, state_proportion)

Class for the Stochastic model.

A simple example of a UserModel.py file with a Stochastic disease model is given below

import episimmer.model as model

def event_contribute_fn(agent,event_info,location,current_time_step):
        if agent.state=='Symptomatic':
            return 1
        elif agent.state=='Asymptomatic':
            return 0.5
        return 0

def event_receive_fn(agent,ambient_infection,event_info,location,current_time_step):
    #Example 1
    beta=0.001
    return ambient_infection*beta


class UserModel(model.StochasticModel):
    def __init__(self):
        individual_types=['Susceptible','Exposed','Asymptomatic','Symptomatic','Recovered']
        infected_states=['Asymptomatic','Symptomatic']
        state_proportion={
                            'Susceptible':0.99,
                            'Exposed':0,
                            'Recovered':0,
                            'Asymptomatic':0,
                            'Symptomatic':0.01
                        }
        model.StochasticModel.__init__(self,individual_types,infected_states,state_proportion)
        self.set_transition('Susceptible', 'Exposed', self.p_infection())
        self.set_transition('Exposed', 'Symptomatic', self.p_standard(0.15))
        self.set_transition('Exposed', 'Asymptomatic', self.p_standard(0.2))
        self.set_transition('Symptomatic', 'Recovered', self.p_standard(0.1))
        self.set_transition('Asymptomatic', 'Recovered', self.p_standard(0.1))

        self.set_event_contribution_fn(event_contribute_fn)
        self.set_event_receive_fn(event_receive_fn)

Parameters

• individual_state_types (List[str]) – The states in the compartment model

• infected_states (List[str]) – The states that are infectious

• state_proportion (Dict[str, Union[float, int]]) – Starting proportions of each state

reset()

Initializes transitions probabilities between states to 0.

Return type

None

set_transition(s1, s2, fn)

Adds a transition probability function between the specified states. The user must specify one of the following functions for the transition function

• p_standard()

• p_function()

• p_infection()

def rec_to_dead_fn(time_step):
    return 0.1

class UserModel(model.StochasticModel):
    def __init__(self):
        individual_types=['Susceptible','Infected','Recovered','Dead']
        infected_states=['Infected']
        state_proportion={
                            'Susceptible':0.99,
                            'Infected':0.01,
                            'Recovered':0
                            'Dead':0
                        }
        model.StochasticModel.__init__(self,individual_types,infected_states,state_proportion)
        self.set_transition('Susceptible', 'Infected', self.p_infection())
        self.set_transition('Infected', 'Recovered', self.p_standard(0.2))
        self.set_transition('Recovered', 'Dead', self.p_function(rec_to_dead_fn))

Parameters

• s1 (str) – The first state

• s2 (str) – The second state

• fn (Callable) – The function to be used for calculating the probability of transition

Return type

None

initialize_states(agents)

Initializes the states of the agents based on state proportions.

Parameters

agents (Dict[str, episimmer.agent.Agent]) – A dictionary mapping from agent indices to agent objects

Return type

None

find_next_state(agent, agents)

Returns next state of the agent according to the transition functions between the states stored in transmission_prob.

Parameters

• agent (episimmer.agent.Agent) – The current agent whose next state is to be determined

• agents (Dict[str, episimmer.agent.Agent]) – A dictionary mapping from agent indices to agent objects

Returns

The new state of the agent

Return type

Tuple[str, None]

full_p_standard(p, agent, agents)

Returns a fixed probability of transition.

Parameters

• p (float) – Probability of transition

• agent (episimmer.agent.Agent) – An agent object

• agents (Dict[str, episimmer.agent.Agent]) – A dictionary mapping from agent indices to agent objects

Returns

Probability of transition

Return type

float

p_standard(p)

This function can be used by the user in UserModel.py to specify an independent transition with a fixed probability. It returns a partial function of full_p_standard().

class UserModel(model.StochasticModel):
    def __init__(self):
        individual_types=['Susceptible','Infected','Recovered']
        infected_states=['Infected']
        state_proportion={
                            'Susceptible':0.99,
                            'Infected':0.01,
                            'Recovered':0
                        }
        model.StochasticModel.__init__(self,individual_types,infected_states,state_proportion)
        .
        .
        .
        self.set_transition('Infected', 'Recovered', self.p_standard(0.2))

Parameters

p (float) – Probability of transition

Returns

Partial function

Return type

Callable

full_p_function(fn, agent, agents)

Returns the probability of transition that is specified by a user-defined function.

Parameters

• fn (Callable) – User-defined function defining the probability of transition

• agent (episimmer.agent.Agent) – An agent object

• agents (Dict[str, episimmer.agent.Agent]) – A dictionary mapping from agent indices to agent objects

Returns

Probability of transition

Return type

float

p_function(fn)

This function can be used by the user in UserModel.py to specify an independent transition with a user-defined function defining the probability of transition. This user-defined function must have a single parameter defining the current time step of the simulation. It returns a partial function of full_p_function().

def rec_to_dead_fn(time_step):
    return 0.1

class UserModel(model.StochasticModel):
    def __init__(self):
        individual_types=['Susceptible','Infected','Recovered','Dead']
        infected_states=['Infected']
        state_proportion={
                            'Susceptible':0.99,
                            'Infected':0.01,
                            'Recovered':0
                            'Dead':0
                        }
        model.StochasticModel.__init__(self,individual_types,infected_states,state_proportion)
        .
        .
        .
        self.set_transition('Recovered', 'Dead', self.p_function(rec_to_dead_fn))

Parameters

fn (Callable) – User-defined function defining the probability of transition

Returns

Partial function

Return type

Callable

full_p_infection(fn, p_infected_states_list, agent, agents)

This function returns the probability of infection based on all types of interaction between the current agent and other agents.

Parameters

• fn (Optional[Callable]) – User-defined function defining the probability of infection based on individual/probabilistic interactions

• p_infected_states_list (Optional[List[float]]) – List of probabilities that can be used in the user-defined function fn

• agent (episimmer.agent.Agent) – Current agent object

• agents (Dict[str, episimmer.agent.Agent]) – A dictionary mapping from agent indices to agent objects

Returns

Probability of getting an infection

Return type

float

p_infection(fn=None, p_infected_states_list=None)

This function can be used by the user in UserModel.py to specify a dependent transition. The transition probability is based on all the types of interactions between the agents. For individual and probabilistic interactions, we must pass two parameters. The first parameter defines the user-defined function fn which returns the probability of infection for every agent considering these two types of interactions. The second parameter is an optional list of infected state probabilities to be used in the user-defined function fn. The parameters to be passed in the user-defined function are p_infected_states_list, contact_agent, c_dict and current_time_step. p_infected_states_list is the above-mentioned list of probabilities, contact_agent is the agent that the current agent is in contact with (through an individual or probabilistic interaction), c_dict is a dictionary defining the interaction and current_time_step is the current time step. If you do not have any of these types of interactions, you need not pass anything. Returns a partial function of full_p_infection().

class UserModel(model.StochasticModel):
    def __init__(self):
        individual_types=['Susceptible','Infected','Recovered']
        infected_states=['Infected']
        state_proportion={
                            'Susceptible':0.99,
                            'Infected':0.01,
                            'Recovered':0
                        }
        model.StochasticModel.__init__(self,individual_types,infected_states,state_proportion)
        self.set_transition('Susceptible', 'Infected', self.p_infection())

In case of individual or probabilistic interactions, a callable function must be passed. A list can also be passed optionally. In the following example, we use the list.

def probability_of_infection_fn(p_infected_states_list, contact_agent ,c_dict, current_time_step):
    if contact_agent.state=='Infected':
        return p_infected_states_list[0]
    return 0

class UserModel(model.StochasticModel):
    def __init__(self):
        individual_types=['Susceptible','Infected','Recovered']
        infected_states=['Infected']
        state_proportion={
                            'Susceptible':0.99,
                            'Infected':0.01,
                            'Recovered':0
                        }
        model.StochasticModel.__init__(self,individual_types,infected_states,state_proportion)
        self.set_transition('Susceptible', 'Infected', self.p_infection(probability_of_infection_fn, [0.1]))

Parameters

• fn (Optional[Callable]) – User-defined function defining the probability based on individual/probabilistic interactions

• p_infected_states_list (Optional[List[float]]) – List of probabilities that can be used in the user-defined function fn

Returns

Partial function

Return type

Callable

Scheduled Model API

class ScheduledModel

Class for the Scheduled model.

A simple example of a UserModel.py file with a Scheduled disease model is given below

import episimmer.model as model

def event_contribute_fn(agent,event_info,location,current_time_step):
        if agent.state=='Infected':
            return 1
        return 0

def event_receive_fn(agent,ambient_infection,event_info,location,current_time_step):
    #Example 1
    beta=0.001
    return ambient_infection*beta


class UserModel(model.ScheduledModel):
    def __init__(self):
        model.ScheduledModel.__init__(self)
        self.insert_state('Susceptible',None, None,self.p_infection({'Infected':1}),False,0.99)
        self.insert_state('Infected',6,3,self.scheduled({'Recovered':1}),True,0.01)
        self.insert_state('Recovered',0, 0,self.scheduled({'Recovered':1}),False,0)

        self.set_event_contribution_fn(event_contribute_fn)
        self.set_event_receive_fn(event_receive_fn)

insert_state(state, mean, vary, transition_fn, infected_state, proportion)

Inserts a state into the model and schedules the agent for this state using a Normal distribution. The mean and variance are passed here as parameters to the Normal distribution. The user must specify one of the following functions for the transition function

• scheduled()

• p_infection()

The last two parameters define whether the state is an infected state and the initial proportion of agents belonging to this state.

class UserModel(model.ScheduledModel):
    def __init__(self):
        model.ScheduledModel.__init__(self)
        self.insert_state('Susceptible', 2, 1, self.p_infection({'Infected':1}), False, 0.99)
        self.insert_state('Infected', 6, 3, self.scheduled({'Recovered':1}), True, 0.01)
        self.insert_state('Recovered', 0, 0, self.scheduled({'Recovered':1}), False, 0)

Parameters

• state (str) – The state to be inserted

• mean (Optional[int]) – The mean parameter of the Normal distribution

• vary (Optional[int]) – The variance parameter of the Normal distribution

• transition_fn (Callable) – A function that encodes the states the agent can transition into from the current state

• infected_state (bool) – Defines whether the state is infectious

• proportion (Union[float, int]) – Initial proportion of the state

Return type

None

insert_state_custom(state, fn, transition_fn, infected_state, proportion)

Inserts a state into the model and schedules the agent for this state using a custom distribution specified by the user-defined function. The user must specify one of the following functions for the transition function

• scheduled()

• p_infection()

The last two parameters define whether the state is an infected state and the initial proportion of agents belonging to this state.

def fn1(current_time_step):
    r=random.random()
    if r<0.2:
        return 2
    elif r<0.8:
        return 3
    else:
        return 4

class UserModel(model.ScheduledModel):
    def __init__(self):
        model.ScheduledModel.__init__(self)
        .
        .
        .
        self.insert_state_custom('Recovered', fn1, self.scheduled({'Recovered':1}), False, 0)

Parameters

• state (str) – The state to be inserted

• fn (Callable) – User-defined function that encodes the scheduled time step for transition

• transition_fn (Callable) – A function that encodes the states an agent can transition into from the current state

• infected_state (bool) – Defines whether the state is infectious

• proportion (Union[float, int]) – Initial proportion of the state

Return type

None

initialize_states(agents)

Initializes the states of the agents based on state proportions.

Parameters

agents (Dict[str, episimmer.agent.Agent]) – A dictionary mapping from agent indices to agent objects

Return type

None

find_scheduled_time(state)

Returns the scheduled time of transition for a state.

Parameters

state (str) – The state for which the scheduled time is returned

Returns

The scheduled time of transition for the state

Return type

int

find_next_state(agent, agents)

Returns next state of the agent according to the transition functions between the states and the schedule time left.

Parameters

• agent (episimmer.agent.Agent) – The agent whose next state is to be determined

• agents (Dict[str, episimmer.agent.Agent]) – A dictionary mapping from agent indices to agent objects

Returns

The new state of the agent, Schedule time left for the agent in current state

Return type

Tuple[str, int]

choose_one_state(state_dict)

Returns a new state from state_dict according to its proportion in the state_dict.

Parameters

state_dict (Dict[str, float]) – A dictionary mapping states to proportions of current state that can transition into

Returns

A new state

Return type

str

full_scheduled(new_states, agent, agents)

This function specifies that the state change is scheduled. Returns a new state from new_states and its scheduled time for an agent.

Parameters

• new_states (Dict[str, float]) – A dictionary mapping states to proportions an agent from the current state can transition to

• agent (episimmer.agent.Agent) – An agent object

• agents (Dict[str, episimmer.agent.Agent]) – A dictionary mapping from agent indices to agent objects

Returns

The new state of the agent and its scheduled time

Return type

Tuple[str, int]

scheduled(new_states)

This function can be used by the user in UserModel.py to specify an independent transition. The transition will occur based on a calculated scheduled time of stay for the state. The only parameter required here is a dictionary mapping new states to transition proportions. Returns a partial function of full_scheduled().

class UserModel(model.ScheduledModel):
    def __init__(self):
        model.ScheduledModel.__init__(self)
        .
        .
        .
        self.insert_state('Infected', 6, 3, self.scheduled({'Recovered':1}), True, 0.01)

Parameters

new_states (Dict[str, float]) – A dictionary mapping states to proportions an agent from the current state can transition to

Returns

A partial function of full_scheduled()

Return type

Callable

full_p_infection(new_states, fn, p_infected_states_list, agent, agents)

This function returns a new state from new_states and its scheduled time based on all types of interaction between the current agent and other agents.

Parameters

• new_states (Dict[str, float]) – A dictionary mapping states to proportions an agent from the current state can transition to

• fn (Callable) – User-defined function defining the probability of infection based on individual/probabilistic interactions

• p_infected_states_list (Optional[List[float]]) – List of probabilities that can be used in the user-defined function fn

• agent (episimmer.agent.Agent) – Current agent object

• agents (Dict[str, episimmer.agent.Agent]) – A dictionary mapping from agent indices to agent objects

Returns

The new state of the agent and its scheduled time

Return type

Tuple[str, int]

p_infection(new_states, fn=None, p_infected_states_list=None)

This function can be used by the user in UserModel.py to specify a dependent transition. The transition probability is based on all the types of interactions between the agents. It takes three parameters. The first is a dictionary mapping new states to transition proportions. The next two parameters are the same parameters as in the p_infection function of the Stochastic Model. The fn parameter defines the user-defined function for probability of infection from individual and probabilistic interactions and the p_infected_states_list parameter is a list of float probabilities that can be used in the user-defined function. The parameters to be passed in the user-defined function are p_infected_states_list, contact_agent, c_dict and current_time_step. p_infected_states_list is the above-mentioned list of probabilities, contact_agent is the agent that the current agent is in contact with (through an individual or probabilistic interaction), c_dict is a dictionary defining the interaction and current_time_step is the current time step. If you do not have any of these types of interactions, you need not pass the second and third parameters. Returns a partial function of full_p_infection().

class UserModel(model.ScheduledModel):
    def __init__(self):
        model.ScheduledModel.__init__(self)
        self.insert_state('Susceptible',None, None,self.p_infection({'Infected':1}),False,0.99)

In case of individual or probabilistic interactions, a callable function must be passed. A list can also be passed optionally. In the following example, we use the list.

def probability_of_infection_fn(p_infected_states_list, contact_agent ,c_dict, current_time_step):
    if contact_agent.state=='Infected':
        return p_infected_states_list[0]
    return 0

class UserModel(model.ScheduledModel):
    def __init__(self):
        model.ScheduledModel.__init__(self)
        self.insert_state('Susceptible', None, None, self.p_infection({'Infected':1}, probability_of_infection_fn, [0.1]), False, 0.99)

Parameters

• new_states (Dict[str, float]) – A dictionary mapping states to proportions an agent from the current state can transition to

• fn (Optional[Callable]) – User-defined function defining the probability of infection based on individual/probabilistic interactions

• p_infected_states_list (Optional[List[float]]) – List of probabilities that can be used in the user-defined function fn

Returns

A partial function of full_p_infection()

Return type

Callable