User Guide for the Vector-Human Agent-Based Model Tool (ABM-EpiVector)

General Description:

Agent-Based Model

SEIR and SEI Graphs Associated with Humans and Vectors, Respectively

1. : Susceptible

• It represents mosquitoes that can contract the disease because they are not infected.
• They transition to state E (Exposed) if they bite an infected person.

2. : Exposed

• Mosquitoes that have come into contact with the virus or pathogen (by biting an infected person) but are not yet infectious due to the incubation period.
• After a certain period, these mosquitoes transition to state I (Infected).

3. : Infected

• Mosquitoes that are infected and capable of transmitting the disease to humans.
• They remain in this compartment until they die, after which they are no longer considered in the simulation.

• These are the eggs laid by mosquitoes.

1. : Susceptible

• Represents individuals who can contract the disease because they are neither infected nor immunized.
• They transition to state E (Exposed) if they are bitten by an infected mosquito.

2. : Exposed

• Individuals who have been exposed to the virus or pathogen (bitten by an infected mosquito) but are not yet infectious due to the incubation period.
• After a certain period, these individuals transition to state I (Infected).

3. : Infected

• Individuals who are infected and capable of transmitting the disease to mosquitoes that bite them.
• They remain in this compartment for a specified period before recovering.

• Individuals who have been infected but can no longer transmit the disease because they have developed immunity.

Modeling Hypotheses

• The phenomenon is modeled using time steps of one day.
• Broadly speaking, the epidemic spreads because both the vector carrying the disease and the human population coexist in the same territory. Through their interaction, the vector transmits the disease to individuals in the population, potentially leading to an epidemic.

1. How do humans inhabit the territory?
2. How do vectors inhabit the territory?
3. How do humans and vectors interact?

1. Movement Dynamics
2. Interaction Dynamics

Map

In this context, a color map is a matrix that contains information about a set of points generated through simple random sampling of a rectangle within the Cartesian plane. Each sampled point is associated with a color represented by a number between and 1, where 0 corresponds to "blue" and 1to "red." The rows of the matrix correspond to the number of points used for sampling. The first column represents the x-coordinate of these points, the second column represents the y-coordinate, and the third column contains the color associated with each point. This third column corresponds to an initial coloring; if the color distribution of the map changes over time, additional columns are added to the matrix to reflect the updated colors.

Movement Dynamics

Under the assumption of an initial human population within the territory, human movement dynamics are simplified to the two main locations where individuals spend most of their time: home and work. This pattern remains constant throughout the entire simulation (i.e., across all days).

• Blue ("0") indicates no preference for settling in that location.
• Red ("1") indicates a strong preference for that location.

• Red ("1") represents the highest suitability for mosquito survival.
• Blue ("0") represents the lowest suitability for survival (mosquitoes cannot survive in these areas).

Interaction Dynamics

• Only female mosquitoes bite humans because they require blood proteins to produce eggs.
• Mosquitoes have a limited flight range (for dengue-carrying mosquitoes, the literature suggests a radius of 500 meters).
• Biting frequency varies by species; for dengue-transmitting mosquitoes, studies indicate they bite an average of 4 times per day.
• Disease transmission occurs through bites:
• Humans are infected with a certain probability when bitten by an infected mosquito.
• Mosquitoes become infected with a certain probability when biting an infected human.

States:

Object-Oriented Programming (OOP) for Modeling the Epidemiological Interaction Between Humans and Vectors

• There are two child classes:
• sim_host: Responsible for creating and managing objects that represent the human population and store their complete individual dynamics.
• sim_vector: Responsible for creating and managing objects that represent the vector population (mosquitoes) and store their complete individual dynamics.
• These child classes inherit from a parent class called sim_scenario, which provides the general framework for the simulation environment.
• Additionally, there is another class called epidem_scenario, which manages the interaction between the two child classes, facilitating the epidemiological dynamics between humans and vectors.

1. You travel from home to work, which is located somewhere within the territory.
2. While at work, you might be within the range of an infected female mosquito, which has an average biting frequency of n_times per day.
3. If the mosquito has not yet bitten that day n_times, there is a probability that it will bite you.
4. Since the mosquito is infected, there is another probability that you become infected.
5. If this happens, you transition from being Susceptible (S) to Exposed (E).

1. You travel back home.
2. While at home, the same conditions apply: if you are within the range of an infected mosquito, and it has not yet bitten that day n_times, there is a probability you will be bitten and an additional probability of getting infected.
3. If this happens, you again transition from Susceptible (S) to Exposed (E).

1. Start of the simulation day.
2. Humans move from home to work.
3. Vectors bite humans.
4. Humans move from work back home.
5. Vectors bite humans again.
6. Infection process occurs in vectors (newly exposed vectors transition to infected).
7. Infection process occurs in humans (newly exposed humans transition to infected).
8. End of the simulation day.

Steps to Run a Simulation

Step 1: Main Object with epidem_scenario

• mu_a: Mortality rate of the aquatic phase after the minimum waiting time (delayM).
• mu_m: Probability of mosquito death.
• mu_h: Probability of human replacement.
• beta_hm: Probability of disease transmission from human to mosquito.
• beta_mh: Probability of disease transmission from mosquito to human.
• theta_m: Probability of an exposed mosquito becoming infectious.
• theta_am: Probability of a mosquito egg becoming an adult female mosquito after the waiting time (delayM).
• theta_h: Probability of an exposed human becoming infectious after the waiting time (delayH_ei).
• delta: Number of eggs laid per day by a mosquito that has fed on human blood.
• gamma: Probability of an infected human recovering after the waiting time (delayH_ir).
• K: Carrying capacity (maximum population limit).
• Z: Number of bites per mosquito (average number of times a mosquito bites per day).
• R: Mosquito habitat radius (range of movement in kilometers).
• ac_delay: Delay (in days) before mosquito eggs hatch.
• delayH_ei: Minimum waiting time before humans transition from exposed to infected.
• delayH_ir: Minimum waiting time before humans transition from infected to recovered.
• delayM: Minimum waiting time before a mosquito emerges as an adult (related to theta_am).

Step 2: Secondary Objects Associated with Vectors and Humans using create_Vpop and create_Hpop

• vec_pop: Initial mosquito population.
• host_pop: Initial human population.
• deformations_limit: Parameter for generating maps (recommended values: 1, 2, or 3).
• msize: Map size in kilometers.
• ncentersH: Number of maps to create for humans.
• ncentersM: Number of maps to create for vectors.
• nreferencePoints: Number of points used to generate maps. These points are sampled uniformly within the rectangle
• minOccM: Minimum percentage of occupation in the mosquito map.
• maxOccM: Maximum percentage of occupation in the mosquito map.
• AlphaM: Value that increases the intensity of the color distribution in the mosquito map (recommended: a natural number greater than 1).
• If AlphaM=1, the color distribution remains unchanged.
• If AlphaM=0, the entire map is uniformly colored.
• kindM: Determines the mosquito reproduction paradigm:
• kindM=1: Mosquitoes must bite humans to lay eggs.
• kindM=0: Mosquitoes lay eggs without biting humans.
• minOccH: Minimum percentage of occupation in the human map.
• maxOccH: Maximum percentage of occupation in the human map.
• AlphaH: Value that increases the intensity of the color distribution in the human map (recommended: a natural number greater than 1).
• If AlphaH=1, the color distribution remains unchanged.
• If AlphaH=0, the entire map is uniformly colored.

• For mosquitoes/vectors → minOccM=1=maxOccM
• For humans → minOccH=1=maxOccH

Step 3: Setting the Initial Conditions of the Populations with the set_initConds() Method

• propsH: A 1×4 row vector representing the initial percentage distribution of the human population across the following states:[Susceptible, Exposed, Infected, Recovered].
• propsV: A 1×3 row vector representing the initial percentage distribution of the vector population across the following states:[Susceptible, Exposed, Infected].

Step 4: Iterating a Simulation Cycle with the epidem_cicle() Method

1. Humans move from the Home map to the Work map.
2. Vectors bite humans.
3. Humans move from the Work map back to the Home map.
4. Vectors bite humans again.
5. Infection in the vector population is recognized, and the number of individuals in vector states ("S, E, I") is updated.
6. Infection in the human population is recognized, and the number of individuals in human states ("S, E, I, R") is updated.

Step 5: Epidemiological Simulation with simulator()

• Where num_ciclos specifies the number of cycles (days) of the simulation.

Example 1: Simple Simulation

Changing the Vector Map Using simulator() & change_vectorMap(time_step)

• A new map is created, replacing the previous one gradually over the next time_step simulation cycles.
• This ensures continuity in vector movement dynamics, rather than an abrupt change.
• After these iterations, Step 4 will use the updated map.

• time_step must be a positive natural number.

Step 6: Extracting State Information for Visualization Using graphicSummary() and Time Series Analysis

time_series = sim1.graphicSummary();

• : (In Fig. 1, this represents the population of node Ac over the simulation time).
• : (In Fig. 1, this represents the population of node over the simulation time).
• : (In Fig. 1, this represents the population of node over the simulation time).
• : (In Fig. 1, this represents the population of node over the simulation time).
• : (In Fig. 2, this represents the population of node over the simulation time).
• : (In Fig. 2, this represents the population of node over the simulation time).
• : (In Fig. 2, this represents the population of node over the simulation time).
• : (In Fig. 2, this represents the population of node over the simulation time).

1. Number of mosquito eggs laid during a specific cycle.
2. Number of susceptible mosquitoes at the end of a specific cycle.
3. Number of exposed mosquitoes at the end of a specific cycle.
4. Number of infected mosquitoes at the end of a specific cycle.

Cumulative flow of Individuals Between States and (Last Row)

9. Cumulative sum of individuals transitioning from state to state over time.

(In Fig. 2, let us define the flow of individuals moving from state to state at time t.)

Then, this row corresponds to:

Let be the population size found in the respective states over time.

.

Step 7: Simulation Including Color Map Information for Vectors Over Time and Human Maps

In this context, a color map is a matrix that contains information about a set of points generated through simple random sampling of a rectangle within the Cartesian plane. Each sampled point is associated with a color represented by a number between 0 and 1, where 0 corresponds to "blue" and 1 to "red."

• num_ciclos: Specifies the number of cycles (days) of the simulation.
• extract_step: Defines the frequency at which the vector map coloring is captured.

Example 2: Simulation with Map Extraction

Step 8: Simulation Including a GIF Using the get_graphics() Method

1. Humans Home

• Displays the exact residential locations of all individuals in the human population.
• Identifies their epidemiological state using colors:
• Green → Susceptible ("S")
• Orange → Exposed ("E")
• Red → Infected ("I")
• Blue → Recovered ("R")
• This movement dynamic is determined by the human color map ("Host"), which is visualized in the Host + Work plot.

1. Humans Work

• Displays the work locations of all individuals in the human population.
• Identifies epidemiological states using the same color scheme as the Humans Home graph.
• Unlike residences, work locations are not fixed; instead, the "Work" color map is used to guide individuals toward preferred locations.
• This design captures a more realistic social dynamic, where individuals always return home, but work is not the only inhabited location.

1. Vector Map

• Represents the color map that determines the movement dynamics of vectors.
• This suitability map is constructed based on environmental information for the analyzed region.
• Since this map can change over time, these updates are illustrated in the GIF.

1. Host Home + Work

• Merges the two human movement maps (Home & Work).
• These maps do not change over time, meaning they remain constant across all simulation cycles.

1. Vectors

• Displays the location of mosquitoes on a specific simulation day.
• Identifies epidemiological states using colors:
• Green → Susceptible ("S")
• Orange → Exposed ("E")
• Red → Infected ("I")
• As vector maps change, this affects mosquito distribution in the simulation.

1. Aquatic

• Displays all live mosquito eggs at a given simulation moment.
• Each egg is represented by an orange dot.
• Newly hatched eggs are shown as green dots, representing the emergence of susceptible mosquitoes.

1. History of Vector States

• Plots the historical trends of mosquito states over time:
• S(t) → Susceptible
• E(t) → Exposed
• I(t) → Infected
• A(t) → Aquatic (corresponds to the Ac node in Fig. 1).

1. History of Human States

• Plots the historical trends of human states over time:
• S(t) → Susceptible
• E(t) → Exposed
• I(t) → Infected
• R(t) → Recovered

• Color maps
• Movement dynamics of both vectors and humans
• Interaction dynamics between vectors and humans
• State history trends for both populations

• num_ciclos: Specifies the number of cycles (days) of the simulation.
• 'nameGIF.gif': Defines the name of the GIF file, including its extension.

Example 3: Simulation with GIF Generation

% mu_a= 0.15;

% mu_m= 0.38;

% mu_h= 0.02;

% beta_hm= 0.58;

% beta_mh= 0.3;

% theta_m= 0.9;

% theta_am=0.89;

% theta_h= 0.9;

% delta= 8;

% gamma= 0.05;

% K=2e3;

% Z= 4;

% R= 0.5;

% ac_delay= 14;

% delayH_ei= 2;

% delayH_ir= 2;

% delayM= 2;

 

% The created object is named sim3.

sim3=epidem_scenario(mu_a,mu_m,mu_h,beta_hm,beta_mh,theta_m, ...

theta_am,theta_h,delta,gamma,K,Z,R,ac_delay,delayH_ei,delayH_ir,delayM);

 

% %Map and population params

% vec_pop=100;

% host_pop=1000;

% deformations_limit=1;

% msize=400;

% ncentersH=2;

% ncentersM=2;

% nreferencePoints=rand(5000,2);

% %%%% params

% minOccM=0.5;

% maxOccM=0.5;

% alphaM=2;

% kindM=2;

% minOccH=0.5;

% maxOccH=0.5;

% alphaH=1;

 

% Creates the "Vectors" object, which stores the movement

% and interaction dynamics of mosquitoes/vectors.

sim3=sim3.create_Vpop(vec_pop,nreferencePoints, ...

msize,ncentersM,deformations_limit,minOccM,maxOccM,alphaM,kindM);

 

% Creates the "Hosts" object, which stores the movement

% and interaction dynamics of humans.

sim3=sim3.create_Hpop(host_pop,nreferencePoints, ...

msize,ncentersH,deformations_limit,ncentersH,minOccH,maxOccH,alphaH)

sim3 =

epidem_scenario with properties: parsV: [1×1 struct] parsH: [1×1 struct] Vectors: [1×1 sim_vector] Hosts: [1×1 sim_host] Summary: [] numCicles: 1 matrix_MAP: []

 

% propsH = [0.9, 0.1 , 0, 0];

% propsV = [1, 0, 0];

 

% This generates the initial conditions of the simulation.

sim3=sim3.set_initConds(propsH,propsV);

 

%num_ciclos=100; % Days or simulation cycles.

nameGIF='nameGIF3.gif'; % Specifies the name of the GIF, including its extension.

sim3=sim3.simulator(num_ciclos,[],nameGIF,[])

sim3 =

epidem_scenario with properties: parsV: [1×1 struct] parsH: [1×1 struct] Vectors: [1×1 sim_vector] Hosts: [1×1 sim_host] Summary: [9×52 double] numCicles: 1 matrix_MAP: []

Example 4: Simulation with GIF and Vector Map Updates

% mu_a= 0.15;

% mu_m= 0.38;

% mu_h= 0.02;

% beta_hm= 0.58;

% beta_mh= 0.3;

% theta_m= 0.9;

% theta_am=0.89;

% theta_h= 0.9;

% delta= 8;

% gamma= 0.05;

% K=2e3;

% Z= 4;

% R= 0.5;

% ac_delay= 14;

% delayH_ei= 2;

% delayH_ir= 2;

% delayM= 2;

 

% The created object is named sim4.

sim4=epidem_scenario(mu_a,mu_m,mu_h,beta_hm,beta_mh,theta_m, ...

theta_am,theta_h,delta,gamma,K,Z,R,ac_delay,delayH_ei,delayH_ir,delayM);

 

% %Map and population params

% vec_pop=100;

% host_pop=1000;

% deformations_limit=1;

% msize=400;

% ncentersH=2;

% ncentersM=2;

% nreferencePoints=rand(5000,2);

% %%%% params

% minOccM=0.5;

% maxOccM=0.5;

% alphaM=2;

% kindM=2;

% minOccH=0.5;

% maxOccH=0.5;

% alphaH=1;

 

% Creates the "Vectors" object, which stores the movement

% and interaction dynamics of mosquitoes/vectors.

sim4=sim4.create_Vpop(vec_pop,nreferencePoints, ...

msize,ncentersM,deformations_limit,minOccM,maxOccM,alphaM,kindM);

 

% Creates the "Hosts" object, which stores the movement

% and interaction dynamics of humans.

sim4=sim4.create_Hpop(host_pop,nreferencePoints, ...

msize,ncentersH,deformations_limit,ncentersH,minOccH,maxOccH,alphaH)

sim4 =

epidem_scenario with properties: parsV: [1×1 struct] parsH: [1×1 struct] Vectors: [1×1 sim_vector] Hosts: [1×1 sim_host] Summary: [] numCicles: 1 matrix_MAP: []

 

% propsH = [0.9, 0.1 , 0, 0];

% propsV = [1, 0, 0];

% This generates the initial conditions of the simulation.

sim4=sim4.set_initConds(propsH,propsV);

 

% num_ciclos=100; % Days or simulation cycles.

nameGIF='nameGIF4.gif'; % Specifies the name of the GIF, including its extension.

time_step=20; % The frequency at which the vector map changes.

sim4=sim4.simulator(num_ciclos,[],nameGIF,time_step)

sim4 =

epidem_scenario with properties: parsV: [1×1 struct] parsH: [1×1 struct] Vectors: [1×1 sim_vector] Hosts: [1×1 sim_host] Summary: [9×52 double] numCicles: 13 matrix_MAP: []

Step 9: Simulation Including GIF and Map Extraction

• num_ciclos: Number of simulation cycles (days).
• extract_step: Frequency at which the vector map coloring is captured.
• 'nameGIF.gif': Name of the GIF file, including its extension.

% mu_a= 0.15;

% mu_m= 0.38;

% mu_h= 0.02;

% beta_hm= 0.58;

% beta_mh= 0.3;

% theta_m= 0.9;

% theta_am=0.89;

% theta_h= 0.9;

% delta= 8;

% gamma= 0.05;

% K=2e3;

% Z= 4;

% R= 0.5;

% ac_delay= 14;

% delayH_ei= 2;

% delayH_ir= 2;

% delayM= 2;

 

% The created object is named simu5.

sim5=epidem_scenario(mu_a,mu_m,mu_h,beta_hm,beta_mh,theta_m, ...

theta_am,theta_h,delta,gamma,K,Z,R,ac_delay,delayH_ei,delayH_ir,delayM);

 

% %Map and population params

% vec_pop=100;

% host_pop=1000;

% deformations_limit=1;

% msize=400;

% ncentersH=2;

% ncentersM=2;

% nreferencePoints=rand(5000,2);

% %%%% params

% minOccM=0.5;

% maxOccM=0.5;

% alphaM=2;

% kindM=2;

% minOccH=0.5;

% maxOccH=0.5;

% alphaH=1;

 

% Creates the "Vectors" object, which stores the movement

% and interaction dynamics of mosquitoes/vectors.

sim5=sim5.create_Vpop(vec_pop,nreferencePoints, ...

msize,ncentersM,deformations_limit,minOccM,maxOccM,alphaM,kindM);

 

% Creates the "Hosts" object, which stores the movement

% and interaction dynamics of humans.

sim5=sim5.create_Hpop(host_pop,nreferencePoints, ...

msize,ncentersH,deformations_limit,ncentersH,minOccH,maxOccH,alphaH)

sim5 =

epidem_scenario with properties: parsV: [1×1 struct] parsH: [1×1 struct] Vectors: [1×1 sim_vector] Hosts: [1×1 sim_host] Summary: [] numCicles: 1 matrix_MAP: []

 

% propsH = [0.9, 0.1 , 0, 0];

% propsV = [1, 0, 0];

 

% This generates the initial conditions of the simulation.

sim5=sim5.set_initConds(propsH,propsV);

 

% num_ciclos=100; % Days or simulation cycles.

extract_step=7; % The frequency at which the vector map coloring is captured.

nameGIF='nameGIF5.gif'; % Specifies the name of the GIF, including its extension.

 

sim5=sim5.simulator(num_ciclos,extract_step,nameGIF,[])

sim5 =

epidem_scenario with properties: parsV: [1×1 struct] parsH: [1×1 struct] Vectors: [1×1 sim_vector] Hosts: [1×1 sim_host] Summary: [9×52 double] numCicles: 1 matrix_MAP: {[5000×3 double] [5000×3 double] [5000×11 double]}

MAP_cell5=sim5.matrix_MAP % A cell that stores the human Home map, human Work map, and vector map.

MAP_cell5 = 1×3 cell

	1	2	3
1	5000×3 double	5000×3 double	5000×11 double