Zombie Sim I

From MRC Centre for Outbreak Analysis and Modelling
Jump to navigation Jump to search

Introduction

This is the earlier, more complex older brother of Zombie Sim II, which has more options than you might want, but a lot of flexibility if you want to describe spatial epidemic modelling to a fairly science-friendly crowd. It's a spatial individual-based simulation of a directly transmissible disease, such as influenza. It's a hands-on tool and models an epidemic with the popular tidal wave of infections and recoveries before your eyes. While absolute accuracy has been sacrificed for speed, it can be used to explore the effects of R0, latent and infectious period, temporal seasonality, characteristics of travel, vaccination, isolation or travel restriction for symptomatic cases, stochastic properties (random seeds!), and population density effects.

Installation and Download

IT comes as a ZIP file containing source and binaries (that is, byte-code for Java). I compiled with Java 8u91, and it's a good idea to stay up-to-date anyway. So, install Java from Oracle, and download Zombie Sim I pack here. On Windows, unzip it to any folder you like. (Don't just run it from inside the ZIP - it won't work!). If you need an unzipper, try 7-Zip. Then click on runthis.bat in the root folder. If you like the command-line, or if you're on linux or mac, then simply java Z from the root folder will run it.

Using the Tool

Basic GUI

The top right chunk of the screen shows four graph panels. Top left is daily incidence in millions of people. Bottom left is the cumulative number of infections. Bottom right is a graph of the effective R - the actual number of infections generated per source case. And the top right shows a spatial map that animates as the epidemic progresses. Once the epidemic is done, you can drag the slider below the spatial map to show the frames of the movie, and to look very cool. Each of the three graphs can plot four graphs at once for you to compare - red, green, yellow and blue. Select the graph you want to plot with be clicking on the colour, or to remove a graph, click on the X button near that colour. The big button in the bottom right runs the spatial simulator, and the graph will start animating.

The Parameters

Again, if the range of parameters looks a bit cluttered and complicated for the event you want to present, then perhaps Zombie Sim II is for you. Otherwise, read on. The tool comes with a few pre-defined epidemic scenarios. Selecting from the drop-down next to "Epidemic" will load in a set of parameters from a config file. There's a hacky way of editing that later.

The parameters themselves are hopefully fairly obvious. The Natural History box lets you set the Latent period and Infectious period, measured in days, along with the probability of being symptomatic. The start of the infectious period, and the beginning of symptoms (if any) are assumed to happen at the same time. Next Reproductive Number and Seasonality lets you set R0, and allow that to vary over time. The graph shows you a preview of the resulting reproductive rate. The effect of amplitude is that R0 is multiplied by (YCentre+YAmp) or (YCentre>-YAmp) at the seasonal peaks and troughs respectively. The other variables set the timing offset, and the period of oscillation, which is sinusoidal.

The next panel lets you set Movement behaviour. The x-axis of the graph shows distance, and the y-axis shows probability. If you pick a random number between 0 and 1, find that point on the y-axis, then move to the right until you hit the line, then you have sampled the distance one person travels to make contact with another. The kernel function used is the simple 1/(1+(d/a)^b), where d is the distance, and a and b are the parameters you can set, with a maximum cut-off distance.

The Interventions panel lets you vaccinate a certain percentage of people within a certain radius of your favourite city. You can arrange also that a certain percentage of symptomatic cases get isolated somehow and do not make any infectious contacts, or you can say that symptomatic people are so unwell that they only travel a very small distance. For demonstrations of the effects, try vaccinating the whole country at 10%, 20%, 30% and compare the cumulative infections graphs, for example.

Finally, the Seeding panel lets you choose how many initial seeds the epidemic has, a certain distance from your least-favourite city perhaps. If you seed somewhere remote, you might be less likely to have a full epidemic than if you seed somewhere well connected. And the simulation is stochastic, but determinstic-ish (see Technical Section), so for a statistical crowd, you could run with different random seeds for the Marsenne Twister algorithm, and see how noisy the simulations are.

Lastly, the colours of the map. If there have never been any cases of the epidemic in a pixel, it remains grey scale, which indicates population density - brighter is more dense population. Once cases have been reported in a pixel, then the colour is a gradient from blue to red, where pure blue implies everyone who has been infected has now recovered, pure red would imply everyone who has been infected is still infectious. To put it another way, if blue is zero, and red is one, then then colour of the pixel would be I/(I+R), whenever (I+R)>0, where I is infectious and R is recovered people.

Useful Command-line Options

There are two. /MOVIE will cause screenshots of the whole app will be dumped - which I used for making the movies on this page. They'll have the name gui_1_123.png - where the first '1' is the number of the run being executed which increases each time you click the go button, and the 123 is the frame number of the simulation. To make a movie out of this: ffmpeg -r 15 -f image2 -s 1024x700 -i gui_1_%d.png -crf 25 -pix_fmt yuv420p output.mp4

Secondly, /UNDEAD will run in administrative mode. This will cause an "XML" button to become visible. If you click on it, a bit of text will appear in your command or terminal window, which might look a little like this:-

<c n="Base" k_cut="800" k_a="4" k_b="3" k_r0="1.8" s_amp="0" s_per="40.0" s_off="0.0" s_cen="1.0" v_city="0" i_rad="20" i_pc="50" i_isol="0" i_limit_trav="0" h_latent="3" h_inf="3" h_sympt="0.5" seed1
="12345" seed2="67890" s_loc="0" s_rad="20" n_seeds="5" />

This is a snapshot of the current parameters. If you edit the file z_conf.xml in the root of the Zombie folder, you can paste this in the <creatures> tag, (change the name from "Base" to something more useful). Then when you re-run the Simulator, that configuration will be available in the Epidemic drop-down box.

Data and Algorithms

The code and approach is taken from the Global Epidemic Simulator we've been working on for some years. The population data is a 10% sample of UK and Ireland households, taken from the synthetic population generated for the GES for the UK and Ireland. Hence, the individual-based simulation involves around 6 million people. The synthetic population itself is derived from Landscan 2008, transformed using population distributions and household size distributions. It's a long story.

The algorithm used is then purely a spatial algorithm. The GES also allows within-household transmission and workplace-transmission, which actually speeds up the simulations, but for the Zombie Sim we wanted a more direct relationship between the simple input parameters and the results, so the mode has been simplified to purely spatial transmission. For efficiency, we use the GES's well established sampling algorithm, putting people into patches, calculating patch-to-patch probabilities, and then using a rejection algorithm to correct that over-sampling, which results in a memory-efficient and fast way of approximating a person-to-person probability network. (Remember, 6 million people...). See this Nature paper for details. The number of contacts an infected host makes is poisson distributed, with mean R0.

We use OpenMP then to run the infection process in parallel, but because we are not critically worried about accuracy, the results are not totally deterministic. To explain: the main loop is running in parallel with the different cores of your processor working together. On occasion, two cores might run processes whereby two infected people might try to infect the same susceptible. In the GES, I handle these properly and chronologically, so the result is deterministic, and the earliest infection. In the Zombie Sim, that correction is not done, so you can on occasion get slightly different outcomes from the same run.

Technical Computing

The interface is written in Java, and the pretty widgets are part of a library of tools (GKit) developed for the first Global Epidemic Simulator release. The simulation itself is written in C++ (mostly pure C actually), using OpenMP with as many threads as your machine reports. The source is platform-independent, with binaries for Windows, Linux and Mac provided; Java detects the platform and calls the right one automatically. The Windows executable was compiled with Microsoft VS 2014, and therefore vcomp140.dll is in the same folder. The compiler optimisation for the binaries is set conservatively to avoid any processor compatibility issues (which I found I could not avoid in the latest Intel compiler). If you want to eke out a little more speed, compile the C++ source code yourself - it doesn't need any special treatment - just put your executable in the job folder. (Test it first!)

The first second or so of each simulation execution is initialisation, reading the population data and the patches. Potentially, this could be replaced with a C executable that stays running the background and receives commands without having to be fully restarted, but for the one second delay, I didn't think it was really worth it! The C code then generates PNG files for each movie frame, and a text file after each, which ensures the PNG is complete before Java tries to read it. The TXT file also contains the values for the graphs.

The source for the C++ executable is the same for this version, and for Zombie Sim II.

Usage History

Here are the events where we've used this tool - generally for quite scientifically interested crowds!

Credits and Thanks

The Zombie I interface, simulation code and widget kit was written by Wes Hinsley, for the Imperial College Fringe Event in South Kensington, November 2013. The Synthetic Population generation part of the GES was written by Pavlo Minayev. And the underlying methods used for spatial simulation were established by Neil Ferguson, here for instance. Special mention for Diane Pople in captivating a pretty big crowd demonstrating this at the Fringe Event, and to all the presenters who used it and gave feedback at the Big Bang festival.