1 - modifying a simple sample modelcephil.usask.ca/classes/ucla2014/stepbysteptutorials/01 -...

AGENT-BASED MODELING BOOTCAMP FOR HEALTH RESEARCHERS 2014 MODIFYING A SIMPLE SAMPLE MODEL

Exercise Rating: Basic

Rating: Basic Prerequisites: None Estimated Time Required: 1 hour This exercise will expose you to several basic concepts associated with Agent-based modeling.

• The concept of emergence, in which unexpected phenomena arise from the complex interaction of many factors that are individually very simple. The behaviour observed in the emergent phenomenon will be very different from the behaviour of any one of the pieces that make up the model, or any straightforward combination (e.g. sum, product) of the effects of the different pieces.

• The distinction between a model’s specification & behaviour at simulation time • The idea of independently specifying both “agenthood” (for example, what it means to

be a “Person” in our model, as specified through the “Agent” class) and the “stage” on which agents will play out their behaviour (the “Main” class).

• The distinction between model structure and the particular values of the parameters used in a model, and the accompanying notion of an AnyLogic “experiment” (which exercises a particular model structure with a specific combination of parameter values).

• The use of a “Statechart” to describe an agents “behavior” over time. The exercise seeks to expose you to the above by having you modify an existing agent-based model in AnyLogic. These modifications will also serve the role of familiarizing you with basics of the AnyLogic interface, and elements of the operation of that software. 1. Start up AnyLogic 7.

2. You will now need to access a "Splash Screen” that reads “Welcome to AnyLogic”. If this

has already appeared, you are all set. If not, please undertake the following steps. a. Under the menu item “Help”, Choose “Example Models”. b. The screen of “Example models” will show in one of the windows. Note that the

names of the models are sorted alphabetically, left-to-right and top-to-bottom. 3. Click on the item on the “Splash Screen” that reads “SIR Agent Based” (We have

highlighted this link in the image below, but please be advised that the details of its position might vary depending on the size of the screen, the particular position on the screen in which window it appears, etc.). Clicking on this link will load the specified model into AnyLogic.



4. Once you click on the link, AnyLogic will go from the “Example Model” screen to show the

workspace for working on a model. This is shown as below. a. In the upper left corner of the screen, you will see the “Project” window. This shows

you the structure of the current project – including the various pieces that collectively specify the model. This structure consists of several pieces

i. The “Person” class is an example of an “Agent” class specifies the behaviour and general characteristics of the stylized representation of persons in the model. In short, this represents the model’s characterization of “Personness”.

ii. The “Main” class provides a “stage” on which the agents (here, persons) play out their roles. It typically includes one or more populations of agents. Each agent within that population has the characteristics and behaviour specified by the corresponding agent class (here, the “Person” class specified above).

b. In the middle part of the screen, you will see what we will term the “Canvas”. This area gives the visual “declarative” specification of particular pieces of the model (e.g. of the “Main” class, or of the “Person” class).

c. The bottom window on the screen includes two tabs: the “Properties” window, and the “Console” window.

i. The “Properties” window describes the characteristics of the currently selected item.

ii. The “Console” window provides the output from the model simulation itself.

We note here that we are examining the specification of a model – the “what” the model describes, and varying amount of “how” it is to be accomplished. When we simulate (“run”) the model, we will see the behaviour of the model – behaviour that is a complex combination of the interactions of the different factors we see here.

5. Double-click on the “Person” class. You should see a corresponding “Person” tab appear in the “Canvas” window. This shows elements of the visual specification associated with a “Person” in this model. In this case, this includes a statechart (unassumingly called



“statechart”) that describes the natural history of infection in a person – a process that progresses from a “Susceptible’ state. Following infection (associated with a transition entitled “Infection”), the person proceeds to a state where a person is both “Infected” and “Infectious”. When in this state, through contact with others (an event whose occurrence is associated with the curly “self-transition” transition labeled “Contact”) a person can pass the pathogen on to others, thereby infecting them. Note that because this transition goes from the “Infectious” state back to that same state, the person actually doesn’t leave that state when the transition fires. Following “Recovery”, a person can then enter a “Recovered” state. Meanwhile, the “Properties” window below will show the various characteristics of a person.

6. Now double-click on the “Main” class. In the Canvas (the middle part of the screen), with a

bit of scrolling to the left, you will see something like the below (note that the details of the image may differ, including the tabs at the top of the window). This view shows some logical elements to the left, and some visual elements to the right. The logical elements include a set of parameters that govern factors in the model (such as “TotalPopulation”, “AverageIllnessDuration”, “ContactRate”), a set of variables that count the number of people in the population in particular states (such as “nSusceptible”, “nInfectious”, “nRecovered”). Also included are a population (entitled “people [...]”) of agents (here, Persons), and an environment that describes the geometric and topological (connectivity) context of those agents. This context will be important for governing the spread of infection among the



people.

7. Having seen elements of the logic of the “Person” class and “Main” class – logic that governs

the behaviour of the model, we will now simulate (i.e. “run”) the model with its default settings. We do this by running the default experiment currently present, which is entitled “Simulation: Main”. Running this experiment can be accomplished in either one of the following ways:

a. Click on the small black triangle next to the green button on the top of the screen, and select “SIR Agent Based / Simulation”. (Note that if this is the only model loaded – as is shown below – you can just press the green button itself, as there’s no need to make a choice between experiments to be simulated.)



b. Right-click on “Simulation: Main” in the project window, and select “Run” (as shown below)

8. When the model runs, you should see something like the screen below. This is an

introductory screen for models that is commonly used to let you change the settings by which the model runs (e.g. how quickly it is to run), the information to show, and the default parameter values for the run.

9. In this case, we’ll accept the default settings. Press the button to start the simulation. You

should see the window showing something like seen below. The window depicts a field (a grid) of individual agents (Persons), each connected to its neighbours in the 4 cardinal directions (North, South, East, and West). Note that in the visualization, the yellow color indicates susceptible individuals, the red indicates infectious (and infected) individuals, and the grey indicates recovered individuals. While we don’t show the associated logic here, we



note that one initial infective individual was introduced in the lower right of the field of individuals, and the infection has been spreading out from there. For the period following its introduction, the longer we wait, the larger the circle grows. We note that the dynamic behaviour pattern seen – the radial growth of roughly round shape, with infectives concentrated at the periphery, and recovered individuals inside – is not something directly “programmed in to” the model. Instead, this pattern resulted from a complex combination of many factors – of how individuals are linked together within the grid, of the infection transmission process that takes place from one person to that person’s neighbours, and of the natural history of infection of a given person.

10. Here, suppose we want to do some timing of infection spread. While we could record this on

a stopwatch, it would be more reliable to have the model show us its own internal time. To do this, you can press the small yellow arrow” in the middle of the bottom of the window (in the image below, this is highlighted, and is located just above and to the left of the “tooltip” that says “Customize status bar”). Note that if we had been prescient, we could have done this in the introductory screen as well.



11. Once that button is pushed, a menu will appear below around this button (see below). Make

sure that “Model time” has a check mark next to it. If it does, you can just press the “Escape” key to dismiss the popped menu. If checkmark is visible next to “Model time”, then click on “Model time”. The menu will disappear, but a “model time” should now be visible at the bottom of the window, slightly to the left of center. When the model started simulation, this time had a value of 0.



12. Watch as the infection spreads, and keep track of the time to see how long it takes to just reach the topmost boundary.

13. Once the infection has reached the top boundary, you can press the “stop” button – the button with a red square located to the upper left of the simulation window.

14. Congratulations – you’ve just run what may be your first simulation! In the following steps, we will undertake a set of changes to our assumptions (in the form of different assumptions for parameter values and different assumptions about the staging of the natural history of infection) and see how these changes to our assumptions affect the behaviour of the model. Our first such change won’t change the model structure (e.g. the assumptions about the history of infection), but will instead focus on the detailed parameter values to be assumed within the current structure. To do this, please copy the simulation current experiment from the Project window (marked with a blue dot with an “X” in it). You can do this in any of three ways.

a. Through clicking on the name of the simulation, and pressing the standard “Copy” keystroke for your computer system (on Windows computers, this is Control-C, on Macintoshes, this is Command-C).

b. Through clicking on the name of the simulation and then invoking the “Copy” command in the “Edit” window.

c. By right clicking on the simulation, and selecting “Copy”. The last of these options is shown below.

15. Paste the copied experiment into this project. This can again be done in any one of three

ways a. Through clicking on the name of the Project (“SIR Agent Based”) in the “Project”

window, and then pressing the standard “Paste” keystroke for your computer system (on Windows computers, this is Control-V, on Macintoshes, this is Command-V).

b. Through clicking on the name of the Project in the “Project” window, and then invoking the “Paste” command in the “Edit” window.

c. By right clicking on the name of the Project in the “Project” window, and selecting “Paste”.



The resulting screen should look as follows (note the presence of a new experiment, called “Simulation1” at the bottom of the project hierarchy, following the original experiment

16. Click on the name of the new experiment (“Simulation1”) to call up its properties in the

“Properties” window. Click on the “General” tab in the “Properties” window, and type “SlowRecovery” (no spaces!) in the field for the experiment name (entitled “Name”. The result should be as follows.

17. Select the “Parameters” tab in the “Properties” window. The illness duration (given in the

field labeled “AverageIllnessDuration” initially shown should be the default value (15). Change it to hold an alternative value of 50, so as to create a much longer illness (a much slower recovery). Leave the other parameters unchanged. The result of this change should be as shown below.



18. We will now run the model to see how this changed assumption of a longer infectious period

(and correspondingly slow recovery) affects the spread of illness in the population. To run the model, perform one of the two following tasks

a. Right-click in the “Project” window on the experiment “SlowRecovery” and select “Run” from the “context menu” that results.

b. Click on the small black triangle next to the green button on the top of the screen, and select “SIR Agent Based / SlowRecovery”.

19. In the initial simulation screen, perform both of two actions in order: a. Follow the process of steps 10 and 11, to request that the simulation display the

AnyLogic time on the simulation display. Recall that this is done by clicking on the yellow triangle at the bottom of the window.

b. Click on the button to start the simulation. 20. You should see the infection start to spread across the population. As it grows, the spread

will probably look something like the below. While they may not be immediately obvious, by comparing to the images shown above, there are several changes – the border of the infected region is far thicker, and the interior of the red region has much larger numbers of residual infectives. Using the timer at the bottom, keep track of the time until the infection reaches the top border of the field. Recall that we are performing this simulation with an assumption of a longer period of infectiousness. Does this infection reach the top border of the field more quickly than when we assumed a shorter period of infectiousness? Why or why not?



21. We examined above the effect of changed assumptions regarding parameter values on the

results of the model. We will now continue on this same line of investigation of alternative assumptions, but in a way that requires changes to assumptions about model structure. Make sure that the “Person” tab is shown in the canvas. If it is not, double-click on “Person” in the “Project” window to call it up.

22. Elements of the visual model specification for “Person” should be shown in the canvas. Most prominently, this includes the statechart. We will now add a new transition to this statechart. In the “Palette”, select the “Statechart” tab. If it is hard to remember which icon denotes “Statechart”, just hang you mouse over any of those icons for a few seconds, a detailed list with shall pop up.

23. Add to the canvas window a “transition” from the “Statechart” tab of the “Palette” window.

Drag from the icon labeled “Transition” from the palette to the canvas, and drop by releasing the mouse button.



24. Position the ends of the transition so as to connect the “Recovered” and “Susceptible” states. This process has two steps – one for each end of the arrow.

a. Position the end of the arrow from which the arrow is headed outward (i.e. the end that does not include an arrowhead) on the edge of the top left side of the “Recovered” state, so that the small circulate at the end of the transition has a green color (see image below).

b. Position the “incoming” end of the arrow (i.e. the end with the arrowhead) so that it is located on the bottom left side of the “Susceptible” state.

The resulting visual specification should look as follows:

25. Specifically, because the arrow is selected (if it’s not, click on it so that it is!), its properties

should be visible in the “Properties” window. You will now set several of these properties. a. Change its name (in the “Name” field) to “waningImmunity”. b. Make sure the “Triggered by” dropdown is set to “Timeout” (this should be its default

value, and make sure that it still holds that value. c. For the “Timeout” value, enter “100”. (Note that it is poor practice to directly place a

constant in for this value; it would be better to create a named parameter that could then be documented, named, and overridden in other scenarios. However, to simplify the exposition here, we will directly specify the numeric timeout value.

Following these settings, the window should appear as below.



26. Because we have made these changes to the model structure itself, their existence is

independent of parameter values and apply to all experiments we have defined for this model. Using the procedure we have applied twice above, run the default experiment (entitled “Simulation” – not the “SlowRecovery” experiment) for the model. (Recall that this experiment can be run either by right-clicking on it or via the menu next to the “Run” button at the top of the screen. When the initial model simulation screen comes up, enable the display of the model time (see Steps 10 and 11) so that you can do timing of infection spread, and then press the button to start the model simulation itself. You should see output that look similar to the below.

The figure above illustrates multiple “waves” of infection (in addition to some small “pockets” of localized infection). As the model continues to run forward, additional “waves” of infection appear around the origin of the infection. Each of these waves propagates outwards radially.



Compare the figures seen here with those seen for the original version of the model structure seen above. Why do we see such different patterns? For example, why are there multiple “waves” of infection produced by the new model? On a related note, why are the susceptibles limited to appearing outside of the broad “infection frontier” in the original model, but appear in multiple rings within the new model? Record how long it takes the outermost “wave” of infection to reach the top border. How does this compare to the value for the original model, using the same (default) parameter assumptions? 27. The experiment we have just run uses the new model structure, but assumes the default

values of the model parameters. Recall that we had earlier created an additional experiment – called “SlowRecovery” that runs the model using an alternative set of parameters. You can find this “SlowRecovery” experiment in the “Project” window to the upper left part of the screen. Please run this experiment, using either the “Right-click” method, or by using the menu next to the “Green button” in the upper right part of the screen. As before, when the initial simulation screen comes up, use the “yellow triangle” at the bottom to enable the display of the model time (see Steps 10 and 11) so that we can do timing of the propagation of the waves in the model. Run the model, and record the time taken for the frontier of infection to reach the top border of the field. You should see something similar to like the following:



28. This time – even though we are running the experiment with the new version of the model

structure (involving a waning of immunity) – only a few scattered Yellow (Susceptible) individuals within the outermost “infection frontier” are visible. There is also very little high-level internal structure visible. Why is this so different than the results with the faster default recovery shown in the previous step?

29. Using the timer, assess how long it takes for the infection to reach the top boundary. How does this compare with the results for the same model structure, but with a shorter period of infectiousness (i.e. a faster recovery)? With the results with the different model structure (involving no waning of immunity) but with the same period of infectiousness?

30. Return to the “waningImmunity” transition in the “Person” statechart. Set the “Timeout” to a value of “25”, rather than “100” (see below). Run the model. How does this affect the emergent behaviour?



The phenomenon of emergence seen in these examples – the fact that we see high level behaviour that is very distinct from the low-level behaviour specifications we used when building the model – has many implications, both philosophical and practical. At a practical level, many phenomena we observe in the world exhibit emergence. Within agent-based modeling (and dynamic modeling more generally), we often do not try to directly “program in” these observable patterns to the model that we build. Instead, we try to build a “generative” model out of simple pieces that naturally gives rise to the phenomenon. In contrast to parametric statistical models (where we have a pre-defined “functional form” of the model – e.g. linear, exponential, etc.), non-linear dynamic models do not have a “functional form” for their behaviour that can be specified in advance – instead, the behaviour is merely implicit in the definition of the model, and emerges during the simulation process. In contrast to a regression analysis for a parametric statistical model (where we “fit” a pre-defined functional form to some data), dynamic model calibration process typically involves adjusting model parameters or structure so that the emergent behaviour that results best matches our observations. A few closing comments: If you have gone through the whole of this exercise, you will have learned not only the basics skills of interaction with AnyLogic software, but also many principles associated with dynamic modeling that will place you in good stead for more challenging assignments. You are to be congratulated for your persistence. While the example here is simple and works with a pre-existing model, rest assured that the processes of building up your own, more complicated models will draw on many of the same skills and concepts developed in this exercise.

1 - modifying a simple sample modelcephil.usask.ca/classes/ucla2014/stepbysteptutorials/01 -...

Documents