Contagion tutorial

a =Infectious Disease Simulation Tutorial=

Overview
Ths purpose of this tutorial is to provide an example simulation of the spread of an infectious, or contagious disease. The simulation created in this tutorial follows the specification of the "Contagion Design" description.

Creating the Simulation: Getting Started
If this is your first time using Agentsheets, please follow the links to commonly used tools.

 Make a New Project: The first thing to do is to create a new project and give it a meaningful name, such as "Contagion", which is the name of the example simulation associated with this tutorial. When creating a new project, the default 32 pixel x 32 pixel agent size is generally a good starting point. Smaller agent sizes are useful if you are creating a project with more "atomic" kinds of agents, such as simulating the accretion of dust particles. The more complex the features you want to be visible in the simulation, the larger the agent size needed.

 Creating Agents: Create agents for your simulation. In general, every object in the simulation, including the background, is an agent. This includes boundaries (e.g., walls). In addition, some agents may have multiple depictions to indicate changes in agent status (e.g., well person, sick person).

Use the  depiction editor to create your agent depictions. The depiction editor is a basic "paint" tool. In addition to creating your own designs, you can also import images downloaded from the Internet, as well as images from other AgentSheets projects. Just use the "File/Import Agent" menu option in the depiction editor.

Here are the agent depctions used in the infections disease simulation tutorial:



In order, these depictions are: Wall, Person, Sick Person, Dead Person, Background, Horizontal Wall, and World Health Organization (WHO).

'''NOTE: The depictions of the "well", "sick", and "dead" person are multiple depictions of THE SAME "Person" AGENT. After creating the "Person" agent, use the "New Depiction" button in the gallery to the remaining depictions.'''

 Creating the Worksheet


 * Make a new worksheet. A good practice is to save the worksheet immediately with a meaningful name. If your simulation will have multiple worksheets, use a naming convention that helps identify the worksheet.


 * The image at the top of this tutorial is the starting condition of the worksheet for the infections disease simulation. NOTE: You may wish to wait to place "person" agents on the worksheet until after you complete the behavior associated with creating a new agent (see discussion below).

Simulation Properties for Controlling a Simulation
Simulation properties will be used to simulate disease variables, such as the infectiousness of a disease and the immune response of a person. These variables will be referenced later in the implementation details of the tutorial; however, it will be helpful to define them at this point, so that you can test your implementation incrementally.

Here is the list of simulation properties to create, with suggested starting values:



PLEASE NOTE: When creating the "sick_persons", "well_persons", and "deaths" simulation properties, set them all to zero. As will be seen later, the values will automatically be set to the appropriate values via the person agent behavior. Also, after you have created the simulation properties and set the initial values, please click "SAVE" to permanently store the values for later use in the simulation. Although it is not required to leave the Simulation Properties window open, either during programming the behavior of agents, nor while running the simulation, it is usually useful to be able to view them, especially while testing your simulation.

Simulation Overview
Basically, the simulation has the following steps and general flow:


 * All persons -- sick and well -- move around the worksheet randomly and continuously. Dead persons don't move. (And they tell no tales, either.)


 * When a well person encounters a sick person, the former may become infected (sick). If that happens, the person continues to move around until he/she either recovers or dies. (This simulation takes place either a long time ago, or somewhere in a Third World country, where medical assistance is scarce or non-existent.)


 * When there are no sick people remaining in the simulation -- either because they have all recovered or they have all died -- the simulation ends.

That's it! Pretty simple. Now let's make it happen.

Programming the Behavior of the 'Person' Agent
Overview: Most of the "action" in this simulation is controlled and performed within the "person" agent's behavior. Extensive use is made of "methods", which are like subroutines in a conventional procedural programming language. This divides the actions of the behavior into smaller, more manageable blocks of rules. The "while running" block is the only block of rules in an agent's behavior that is executed continuously, in a polling nature. All other methods are executed only when specifically invoked, either from within the "while running" block or another method in the same or another agent's behavior, much like subroutines within a procedural programming language.

While Running ...: The "person" agent's "while running" has only two rules: one which deals with exposure of a well person to a sick person, and one which determines actions based on the status of the person (well, sick, or dead). Note that the only actions performed within the "while running" rules simply call on other methods within the "person" agent to make decisions. This hierarchy of decision making is similar to the hierarchy of an organization, where higher level policies and decisions are determined at the top of the hierarchy, and more detailed actions are managed at lower levels.

Note that in any set of rules in an agent's behavior, the order of the rules, as well as the order of conditions and actions within rules is important. In general, rules which test exceptional conditions precede rules which manage routine actions. For example, if an agent normally moves around randomly on a regular basis, but does something different when it encounters a goal, then a rule which tests for that goal should precede the regular random movement rule. Otherwise, the agent might actually be at the goal, yet move randomly away from it before the goal can be recognized. This general concept explains the order of the two rules in the "person" agent's "While Running" behavior.

Deciding Whether to Become Infected: Just because someone is exposed to a contagious disease, it doesn't mean he/she will get sick. Diseases have different degrees of contagiousness and people have different immune systems responses. In the case of a simulation, it's all about probability. Whether a person becomes infected is based on the "contagion" simulation property, which is used as a probability in the "% chance" condition. The higher the value of "contagion" (which must be between 0 and 100), the greater the probability of a well person's encounter with ("next to") a sick person will result in infection. If a person becomes infected, then a determination is made at that time as to whether the person will recover spontaneously, or whether the infection will be severe enough to cause death.

Recovering (or not) from the infection: Once a person agent becomes infected, it continues to move around the worksheet until he/she either recovers or dies. In the latter case, the person agent depiction changes to the "dead_person" depiction and no longer moves around the worksheet. In the former case, the person agent depiction returns to the "well" person depiction. Each cycle that a sick person moves, the "status" attribute is decremented, which results in the person agent approaching either recovery or death when the attribute reaches zero. In the sample simulation, two methods are used to implement this process: "decide" and "test_recovered".

The rest of the story ...: This completes the discussion of the main elements of the "Contagion" infections disease simulation tutorial and sample simulation. There are a few enhancements to the basic simulation, a discussion of which may be of interest, especially to those who examine the sample simulation in detail. They are discussed in the section below. It is important to note that this sample simulation is only a beginning, especially in trying to model the spread of an actual contagion. There are hundreds or more variables involved in such a simulation and millions of "agents" that would be simulated. It is obviously both a complex problem and a vital one to address in increasingly communicating world population. The page on "Contagion_Design" gives a short partial list of possible extensions to this simulation to begin to address some of this complexity.