VensimPLE SARS Tutorial

8/10/2019 VensimPLE SARS Tutorial

1/34

VensimPLE 5.4d

Understanding Epidemics Using

VensimPLE

For use with VensimPLE, version 5.4d

September 2005

Professor Nelson Repenning

Professor John StermanSystem Dynamics GroupMIT Sloan School of Management

Cambridge, MA O2142

Send comments to [email protected] or [email protected]


2/34


3/34


4/34

4

Start your model of the Taiwanese SARS epidemic at day 0 (enter 0 in the INITIAL TIME box)and simulate for 120 days (enter 120 in the Final Time box). Select a time step of 0.25 days.Check the box saying Save results every time TIME Step. Finally, select day as the unit fortime (instead of the default value month).

Change the name of your model by selecting the File menu and entering the desired name in thetext field and click on OK. (VensimPLE will automatically supply the .mdl extension. If youare working with a different version of Vensim and see a Show all of type option on the right sideof the dialog box, make sure that the .mdl Fmt Models extension is selected. This allowsVensimPLE to save the model in a format that can be used by both Macintosh and IBM-compatible computers.) !

Finally, before beginning to develop your model, make sure the SARS data are loaded. To do

this, first click on the icon to get the control panel (which should look like this):

! Vensim saves every simulation run and custom graph you produce as a separate file. It supplies a .vdf extensionfor simulation runs and a .vgd extension for custom graphs. These files cannot be opened from outside theVensim application; they can be opened within Vensim through the Control Panel .


5/34

5

If you see something different, click on the Datasets tab. To load the data file, SARSDATA,select it by clicking and then hit the >> button which will move it to the Loaded column. Thedata set is now available. One important note: to access that data you must use the exact variablenames specified in this tutorial .

You are ready to start building your model.


6/34

6

II. Developing the Stock, Flow, and Feedback Structure

The VensimPLE software is designed using the metaphor of a workbench. The large blankarea in the middle of the screen is your work area, where you develop and analyze your model.The different buttons on the border of the work area represent the different tools available as

you work on your model. The tools on the top horizontal row are for building your model. Thetools on the left vertical row are for model analysis. The tools on the bottom horizontal rowallow you to change the formatting of the model diagram. You will become familiar with manyof these tools as you build the epidemic model.

To begin, add a stock representing the population susceptible to SARS to your model. To do this

click on the button (the one with the box around the word VAR) on the top horizontaltoolbar and then click in the right center of the screen. You use this tool whenever you want toadd a stock or level variable to your model. VensimPLE then returns an empty text box and ablinking cursor. Type the variable name Population Susceptible to SARS and then hit thereturn key. If the variable name does not fit comfortably within the stock, you can re-size thestock by grabbing the handle in the lower right corner (place the mouse of the small circle andhold down the left mouse button) and moving the mouse. Your screen should now look like this:

You have just created the first variable in your model, the stock of people that could potentiallycontract SARS.


7/34

7

Now add the stock of people who have contracted the disease. To do so, click on the stock toolbutton, and then click again about two inches to the right of the susceptible stock. Name thisvariable, Population Infected with SARS . Your screen should now look like this:

Now add the flow of infections that connects the two stocks. Click on the button in the tophorizontal tool menu. Now, click and release inside the stock of susceptible people, then movethe cursor so that it sits inside the infected stock and click and release again. VensimPLE thengives you an empty text box and a blinking cursor. Type Infection Rate and hit the return key.Your screen should now look like this:


8/34

8

You have now created the flow, Infection Rate , which decreases the stock of people susceptibleto SARS and increases the stock of those infected. Now you need to add the variables that closethe loops between that infection rate and the states of the susceptible and infected stocks. Begin

by adding the two auxiliary variables that determine the infection rate, Infectivity and ContactsBetween Infected and Uninfected People . To add Infectivity click on the button and thenclick again approximately an inch above the infection rate flow. When the text box appears, typeInfectivity and hit return. To add the next variable, click again, this time about an inch belowthe infection flow. When the text box appears, type Contacts Between Infected and Uninfected People. Unlike the previous variableswhich were either stocks or flows--the newvariables are not attached to a valve or a box. These are called auxiliary variables .

To show pictorially that the Infection Rate is determined by Infectivity and Contacts Between

Infected and Uninfected People , we connect them with causal arrows. First click on the

button to select the causal arrow tool. Now, click and release on the variable Infectivity andthen click and release again on Infection Rate . Do the same for Contacts Between Infected and Uninfected People and Infection Rate . Make sure your causal arrows actually end on theword Infectivity . They should not be attached to the stocks. You can delete arrows using the

tool.


9/34

9

Clicking on the button allows you to select the variables you have created and move them todifferent places on the screen. To do this, place the arrow cursor over the variable you wish tomove, hold down the mouse button, move the variable to the desired place, and then release themouse button. You can also select the handles of the causal arrows (the small circles in themiddle of the arrow) and change the curvature of the arrow. Arrange your variables and arrowsso that your diagram looks approximately like this:

Now, update your diagram to show the polarity of the causal connections. First click on thebutton. Then select the handle of the arrow you wish to label by clicking and releasing on thesmall circle in the middle of the arrow (the handle darkens when selected). Now, with the handle

selected, click and release the button on the bottom horizontal toolbar. You then see a pop-up menu:

Click and release on the desired label, and it will show up in the diagram. Label your two causalarrows so your diagram looks like this:


10/34

10

PopulationSusceptible to

SARS

PopulationInfected with

SARSInfection Rate

Infectivity

Contacts BetweenInfected and Uninfected

People

+

+

Now, using the same steps discussed above, add the necessary variables, links and labels so thatyour diagram looks like this:


11/34

11

You may want to slide the handle of each arrow close to its arrowhead, so each label is clearlyassociated with its causal arrow. Also, to move the polarity labels (the +s and -s) to theother side of the arrow, right click on the arrow handle (the small circle) and you will get thefollowing dialog box:

With this menu, you can change the location of the polarity sign and the thickness of the arrowitself.

Finally, you may wish to label the loops you have just created. To do this, click on the tooland then click in the center of the feedback loop. You can use this tool to create comments that,while having no structural use, can greatly help someone else understand your model diagram.After clicking in the center of the reinforcing loop (the one linking the infection rate and theinfected population), you should see the following dialog box:

To label the reinforcing loop click, on the Loop Clkwse button in the Shape box; click onCenter in the Word Position box; and type R in the Comment Type box. Click on the OK button or hit return. Your model should now appear as:


12/34

12

PopulationSusceptible to

SARS

PopulationInfected with

SARSInfection Rate

Infectivity

Contacts BetweenInfected and Uninfected

People

+

+

SusceptibleContacts

ContactFrequency

Probability of Contactwith Infected Person

Total Population

+

+ +

+

++

R

Repeat this process to label the balancing depletion loop; your model should now look like:


13/34

V. Simulating Your Model 13

III. Specifying Equations for Your Model

Now that you have developed a complete stock, flow, and feedback representation for the SARSepidemic, you need to write equations for each of the variables. Equation formulation is acritical step in the process of model building and central to developing a rigorous understanding

of the problem at hand.

To begin writing equations, click on the button on the top horizontal toolbar . The variablesin your diagram become highlighted.

A highlighted variable indicates that the equation for that variable is incomplete.

Variables in dynamic models are classified as either exogenous or endogenous. Exogenous

variables are those that are not part of a feedback loop, while endogenous variables participate inat least one feedback loop. Your model has three exogenous variables-- Infectivity , ContactFrequency , and the Total Population --and six endogenous variables Population Susceptibleto SARS , Infection Rate , Population Infected with SARS , Probability of Contact withInfected Person , Susceptible Contacts , and Contacts Between Infected and UninfectedPeople .


14/34


Start by writing the equations for the endogenous variables. Begin by clicking on the InfectionRate. You then see the following dialog box:

Good modeling practice requires that each equation in a model have three elements: (1) theequation itself; (2) specified units of measure; and (3) complete documentation. You enter theequation in the box to the right of the = sign. You enter the units of measure in the text field tothe right of the word Units . Documentation is entered in the box to the right of the wordComment .

Write the equation first. Begin by clicking in the box to the right of the equal sign. Now, look inthe box in the middle right. Here Vensim has provided you with the two variables that yourmodel diagram shows as influencing the infection rate, Contacts Between Infected andUninfected People and Infectivity . A simple and plausible formulation for the infection rate issimply to multiply the number of contacts by the infectivity (which, by definition, is the fraction

of contacts that result in transmission of the disease). To enter this equation first click on theContacts Between Infected and Uninfected People variable, which then appears in theequation box to the right of the = sign. Now either click on or type * to representmultiplication. Complete the equation by clicking on Infectivity . Your dialog box should nowlook like this:


15/34


Now fill in the units. Infection Rate is a flow variable, so the appropriate unit of measure forthis equation is people/time unit. Since you already chose to measure time in units of days (seepage 3), the appropriate unit is people/day. Type people/day in the units field.

Vensim automatically tracks the units you have defined. The next time you specify the units fora variable in this model, people/day will appear in the units pull-down menu. Click on thearrowhead to the right of the units field to see units already specified in the model, and selectfrom that list when appropriate.

Finally, provide a description of this equation in the comment field. A good comment will bebrief but also explain to the reader the logic behind the equation, key assumptions, limitationsand caveats, and sources for data. For example, for the infection rate you might write:

The infection rate is equal to the number of contacts between infected anduninfected people multiplied by the fraction of those contacts that result intransmission of the disease.

Your dialog box should now look like this:


16/34


17/34


The Infection Rate is no longer highlighted, since you have just specified its equation.

Now write the equation for the stock of susceptible people. Begin by clicking on the susceptiblestock. You should get a dialog box that looks like the following:


18/34


You enter the equation for the stock in the box to the right of the word Integ . Integ stands forintegrate and simply means that the stock at any moment in time is equal to the sum of all theinflows minus the sum of all the outflows plus the initial value. When you created the stock,flow, and feedback diagram, you made the Infection Rate an outflow from the stock of PeopleSusceptible to SARS . Vensim captures this stock-flow dependency by showing the equation forthe susceptible stock as Integ (Infection Rate). This simply means that at any point in time thesusceptible stock is equal to its initial condition less all the people that have flowed out of it up tothat point in time.

Now we need to specify the initial condition or the starting point for the susceptible stock. Theinitial condition is entered in the box just to the right of the words Initial Value . Initialconditions can either be numbers or other variables in a model. In this case it is easier toinitialize the stock with another variable, specifically the constant (or exogenous) variable, theTotal Population . So type Total Population in the Initial Value box.

Now the equation specification for the Population Susceptible to SARS stock is complete.Your equation indicates that the susceptible population is the initial value at the start of thesimulation less all of those people who contract the disease.

You still need to specify the unit of measure, however, and document your equation in thecomment field. The units should be fairly straightforward. The Population Susceptible to


19/34


SARS is a stock and its units are people. A sample comment for Population Susceptible toSARS is:

The Population Susceptible to SARS is the equal to the population susceptible priorto the onset of the disease less all of those that have contracted it. Initialized to the

Total Population, which assumes that all individuals are initially susceptible (noprior natural or vaccine-conferred immunity.

Your dialog box should now look like this:

Click on OK or press return. Your model diagram should now look like this:


20/34


Following a similar process to the one outlined above, you should now be able to specify theequations for the remaining endogenous variables, Susceptible Contacts, Contacts BetweenInfected and Uninfected People , and Probability of Contact with Infected Person .

Susceptible Contacts= Population Susceptible to SARS*Contact Frequency(people/day)

Contacts Between Infected and Uninfected People=Susceptible Contacts*Probability of Contact with Infected Person(people/day)

Probability of Contact with Infected Person= Population Infected with SARS/Total Population(dimensionless)

Finally, you need to specify equations for the exogenous variables, Infectivity, ContactFrequency, and Total Population. Begin with Total Population . Clicking on it should bringup the following dialog box:


21/34


Note first that there are no inputs variables, just as you specified in the diagram. Consequently,you will need to specify a numerical value for the Total Population. The data suggest that inTaiwan, the cumulative number of cases eventually rose to approximately 350, so start with thatvalue for Total Population (you may want to revisit this assumption later). You also need tospecify units of measure and provide a comment. When you are finished your dialog box shouldlook like this:


22/34


Following this example, complete the equations for the other two parameters, ContactFrequency (people/day) and Infectivity (dimensionless ). You do not have hard data for thevalues of these parameters so you will need to use your judgment to estimate appropriate values.Later, we will discuss how you can evaluate the models sensitivity to these assumptions.

Now we will add the structure to allow us to compare the behavior of the model to the data forthe SARS epidemic in Taiwan. We have created a file containing these data (the fileSARSDATA.vdf). To compare the model against the data we need to create variables thatcorrespond to the incidence of new cases, denoted New Reported Cases , and the prevalence ofSARS, denoted Cumulative Reported Cases . Because the data file uses these variable namesyou must create variables in your model with exactly the same names.

Using the stock variable tool create a new stock called Cumulative Reported Cases , placed

a few inches below the current structure. Then use the flow tool to create an inflow to thatstock called New Reported Cases . This structure captures the relationship between incidenceand prevalence: As new cases are reported the cumulative number of cases increases. Yourdiagram should look like this:


23/34


Now you need to define New Reported Cases . For simplicity we will assume that new cases(the infection rate) are immediately diagnosed and reported. In reality, of course, there is a delaybetween the infection rate, diagnosis, and reporting through the public health system. To defineNew Reported Cases as equal to the infection rate you could simply draw a causal arrow fromthe Infection Rate to New Reported Cases . However, doing so would clutter the diagram.

Instead, we will use a Shadow Variable. Select the Shadow Variable tool from the toptoolbar. Click about an inch to the left of New Reported Cases . The following dialog will popup, listing all variables in the model. Select the Infection Rate , then click OK.


24/34


Vensim creates a copy (Shadow) of the Infection Rate . Shadow variables are gray and placedwithin braces: . Your screen should now look like this:


25/34


Shadow variables enable you to keep your model diagrams clean and readable.

Now draw a causal arrow from the shadow to New Reported Cases :

Now use the equation tool to define New Reported Cases as equal to the Infection Rate . Theunits for New Reported Cases are People/Day. Add an appropriate comment (point out that youare assuming that new cases are reported immediately). Now define the stock of CumulativeReported Cases . You will see that Cumulative Reported Cases is already defined as theintegral (accumulation) of New Reported Cases . You need to supply the initial number ofreported cases, which is zero. Specify the units as People and add an appropriate comment.

Note that the Cumulative Reported Cases will equal the actual population infected with SARS,because you have assumed that New Reported Cases equals the actual Infection Rate. Why thenbother to define Cumulative Reported Cases separately from the Population Infected withSARS? There are two reasons: (1) They are conceptually different: the actual number of peopleinfected with SARS differs from the number reported through the public health surveillancesystem (there may be delays and measurement errors you might want to capture later); (2) youmight later alter the model structure so that the equivalence of the two stocks no longer holds.


26/34


IV. Using the Model Structure Analysis Tools

You are now ready to analyze your model. VensimPLE provides several tools for analyzing and

understanding the structure of your model.

By far the most important of these is the unit-checking function. To access this tool, go to theModel menu and select Units Check . An important feature of any system dynamics equationis dimensional consistency . This is just a fancy way of saying that the units of measure must bethe same on both the left and right sides of the equation. For example, if you have followed theinstructions in the tutorial so far and you run the units check, you will get the following message:

Followed by:


27/34


The problem is that, in this example, the equation for Susceptible Contacts is not dimensionallyconsistent: The right and left sides of the equation have different units. Susceptible Contacts ismeasured in contacts per day, but, in the current formulation multiplying the PopulationSusceptible to SARS by the Contact Frequency yields a value with units of people*people/day.

The cause of the problem is that the units of measure for Contact Frequency are incorrect. TheContact Frequency represents the number of contacts each person makes per day, not the totalnumber of contacts (which is captured by the variable Susceptible Contacts ). However, theunits of measure previously specified do not capture this definition. To fix this problem, changethe units of measure for contact frequency to be people/person/day. After you do this, run theunits check again.

Unfortunately, this change doesnt quite fix the problem. You will still find a unit error with thefollowing message:

The problem now is that Vensim does not recognize the people and person represent the sameunit of measure. Fortunately, this problem can be fixed. Go to the Model menu and selectSettings . When the dialog box appears, select the Units Equiv button, which should thenproduce the following dialog box:


28/34


The units equivalence feature allows you to specify which units you wish Vensim to recognize as

the same. This feature is often used to match singular and plural forms of the same word, suchas person and people, dollar and dollars . To use this feature simply type people and personseparated by a comma, people, person and click on the Add Editing button. When you aredone click OK . Now when you run the units check you should get the following:

The units in your model now balance.

The other tools are also useful. The and the buttons create causes and uses treesfor the selected variable. To use these tools, you need to first select a variable. Do this by firstclicking on the button and then double-clicking on the variable you wish to select. You cantell which variable is selected by looking at the top border of the VensimPLE window. If youselect the variable Infection Rate, words Infection Rate will appear after the model name.Having selected Infection Rate , clicking on the two causes and uses buttons in sequence

gives you:

Infection RateContacts Between Infected and Uninfected People

Probability of Contact with Infected Person

Susceptible Contacts

Infectivity


29/34


and

Infection RatePopulation Infected with SARS Probability of Contact with Infected Person

Population Susceptible to SARS Susceptible Contacts

The tool identifies all the feedback loops in which the selected variable is a member, and the

button creates a documented listing of the equations in your model. Try them.

V. Simulating Your Model

VensimPLE also has tools to help you analyze the behavior of your model. Before doing this,however, you must actually simulate the model so you have some behavior to analyze.

To run a simulation, you first need to choose a name for this particular model run. It is helpful tochoose names that suggest some idea of what is being tested rather than using names like SIM1,SIM2, etc. Since this is the base case run for your model, you might choose to call the runBASE. * The name of the simulation is entered in the white box in the analysis tool bar. Thedefault name for any simulation run is Current . Change this to Base .

To run a simulation, click the button and your model will run.

Once the simulation run is completed, you can look at the results of your simulation.VensimPLE provides many tools with which to view simulation output. The most basic, andoften most useful, of these is the graph. To create a graph of a variable, such as CumulativeReported Cases , first click on the tool and then double-click on the desired variable.Double-clicking on a variable places that variable on the workbench.

To get see a graph, click on the button in the left toolbar. You will then see the output ofyour model, compared against the data. The behavior of your model will depend on theparameters you have chosen. My version generated the following graph:

* Advanced Tip: VensimPLE also offers you the choice of two numerical integration methods, Euler and Runge-Kutta 4.Runge-Kutta 4 is a more accurate simulation method, but it is also more computationally intensive. Generally it is better touse the Euler method and change only if you believe you are seeing integration error. Read Business Dynamics , Appendix A,for further details.


30/34


Besides the graph, VensimPLE provides many other ways to examine simulation output.

The button displays a graph of the currently selected variable, along with graphs of all thevariables that determine the selected variable (the causes). Clicking this button gives you:


31/34


VensimPLE also can present the output in the form of a table rather than a graph. To see a table

simply click on the button.

Having analyzed this simulation, you may wish to run additional simulations under differentassumptions. For example, what might happen if you cut the contact frequency in half?

One way to do this is simply to change the model equation in the variables equation box. Thisis time-consuming and error-prone, however, since you must remember to go back and changethe parameter back to its original value before testing another assumption. If you change a

variables formulation in its equation box, it remains as you specify until you change it again.So, if you want to alter a variables value only once, to observe its effect on the simulation, andthen have the variable revert to its original value, use the Parameter Changes button, accessible

on the analysis tool bar. Test the effect of a change in the Contact Frequency click thebutton. You screen should now look like this:


32/34


To change the contact frequency for this simulation, click on Contact Frequency and its currentvalue will appear in a box. Type in a smaller value (such as a 50% reduction) and hit return .Before simulating, make sure you name your new simulation so that you can compare the twodifferent runs. Use a name that helps you remember what the changes are, for example LowContacts .

Now the simulation will run under the new assumption for contact frequency. To run the

simulation just click the button.

Now when you select any of the model output tools, they show the results from both simulations.The graph tool displays:


33/34


If you do not wish to see the previous (base) run displayed with the new simulation run, then

click on the button and the following dialog box will appear:

This is the Control Panel . Click on the Datasets button and the dialog box will display thetwo data sets you have created so far. To eliminate the first run, simply click on it twice.

The control panel also allows you to select a given variable (chose the Variable tab). Modifythe horizontal axis of your graphs, and create custom graphs. See the help menu for moreinformation on all of these features.


34/34

Vensim also offers another simulation mode, called SyntheSim, to help you analyze your model.

To activate Synthesim click on the button at the top of your screen. When you do this,SyntheSim is activated and your screen should now look like this (note that we have changed thename of the current simulation to Current so as not to override the results of the Low Contacts simulation):

All the constants in your model now appear with sliders while the other variables will have smallgraphs superimposed on them showing the model behavior. With Synthesim activated you cannow change any of the constants in your model using the sliders and Vensim will automaticallyre-simulate the model and provide updated output. For small models such as this one, theresponse is almost instantaneous. SytheSim can be extremely useful in developing intuition as tohow your models behavior changes as its underlying parameters are adjusted. Try it by varyingthe contact frequency and other parameters.

Documents

VensimPLE SARS Tutorial