Infectious Disease Simulation Tutorial
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
|See detailed simulation recap.|
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.
|See the Contagion Tutorial agent Gallery.|
- 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).
|See tips and techniques for creating and modifying worksheets.|
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.
|See how to open the Simulation Properties window.|
Here is the list of simulation properties to create, with suggested starting values:
PLEASE NOTE: When creating the "sick_persons" and "dead_person" agents on the worksheets, the "infections" simulation property, and the "deaths" simulation property (when a "dead_person" is placed on the worksheet) are updated in the "when creating new agent" method of the "person" agent. Care must be taken when modifying a worksheet to reset these simulation properties if the initial numbers of sick and/or dead person agents is changed on the worksheet. Remember to save the simulation properties (maintained separately from the worksheet) if you make changes to them you wish to retain.
|See descriptions of the simulation property meanings.|
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.
|Before you do, you can peek here to learn a little more detail ...|
Simulation proceeds as follows:
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.
Follow along in the simulation: In order to understand this tutorial, it is best to download the companion project (see the link at the bottom of this tutorial), and open it in AgentSheets. Examine the behavior of the various agents, the simulation properties window, and the agent attributes window.
While Running ...: The "person" agent's "while running" has only one rule, which simply calls upon the "decide" method to determine what to do. Thus, the latter is the method that is the primary decision-maker within the "person" agent behavior. And the methods invoked by the "decide" method perform the changes in status of the "person" agent.
|Learn more about the decisions regarding infection and recovery.|
In this simulation, the "contagion" simulation property simulates the degree (probability) to which the simulated contagion will cause an exposed person to become infected. The degree to which an infected person can infect others in this simulation is essentially determined by the length of time the person remains sick. This is controlled by two simulation properties: "minimum_sick_time" and "variable_sick_time". An infected person will be sick for the number of simulation cycles specified in the first property plus a random number between zero and the value in the second property. This provides some variability in the amount of time that a person will remain sick.
When a person agent becomes infected (sick), an agent attribute ("sick_clock") is set to the sum of the "minimum_sick_time" plus a random number derived from the "variable_sick_time" properties. Afterward, that attribute is decremented each simulation cycle until it is less than or equal to zero, at which point a decision is made as to whether the person dies or recovers. This decision is based on the "mortality" simulation property, which is analogous to the mortality rate of a diseasse.
|Statistics maintained by the simulation.|
Agent attributes and simulation properties used (note that in referring to a simulation property within behavior, the "@" symbol precedes the simulation property name):
Note that the above simulation properties are maintained by the "WHO" agent, which uses polling to request that all person agents on the worksheet update the simulation properties. Note, also, that when the simulation property is running, the display of simulation properties may be somewhat inaccurate. In order to see the status at any point in time, use the "stop simulation" button to temporarily pause the simulation.
Note that the above three simulation properties are different from the first three properties, in that the latter are "snapshots" in time -- the status of the simulation at any point in time; whereas, the former are cumulative statistics that characterize the simulation as a whole.
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. However, it remains only briefly on the worksheet; otherwise, it would become a barrier to movement of other agents. In order to actually see the appearance of a dead person, one must move the simulation run-time slider bar far to the left.
The rest of the story ...: This completes the discussion of the main elements of the "Contagion" infections disease simulation tutorial and sample simulation. 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.
|And here is the rest of the story:|
The "When Creating New Agent" trigger in AgentSheets allows actions to be taken when an agent is created in a worksheet, either statically by manually placing the agent with one of the worksheet tools, or dynamically during simulation. This method in the "person" agent is used to initialize counters when placing a "sick_person" or "dead_person" agent on the worksheet. Specifically, the "infections" simulation property is incremented in both cases and the "deaths" property is incremented for the latter case. Note that it is not necessary to adjust the status type simulation properties, which are continuously updated by the polling of the "WHO" agent. In addition to simulation property updates, the placement of a "sick_person" on the worksheet also sets that agent's "sick_count" in the same way as an infection when the simulation is running.
NOTE: Regarding worksheet construction and the "When creating new agent" method. You MUST place your "person" agents on the worksheet AFTER you define the actions in this method, in order for this method to properly count the agents, as well as set the agent attributes. If you make changes to this method that affect the statistics, you must erase and re-place the appropriate agents. Also, you MUST SAVE the simulation properties after you have completed placing all agents. AND, you MUST SAVE the worksheet after placing all "sick_person" agents on the worksheet. Finally, if you have modified the worksheet multiple times, be sure to examine, adjust, and re-save the simulation properties to account for the proper number of "infections" and/or "deaths" represented on the worksheet.