Contagion tutorial

From Scalable Game Design wiki
Jump to navigation Jump to search
Contagion screen shot 1.jpg

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

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:

Agent depictions

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:

Contagion simulation properties.jpg

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.

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.

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.

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.