Zombie Sim II
Introduction
This is a spatial individual-based simulation of a directly transmissible disease, such as influenza. It is a simplified version of Zombie Sim I. The emphasis in developing it has been on execution speed rather than accuracy, and various compromises have been made to achieve a running time of around 20 seconds for a full epidemic. Never-the-less, the tool provides hands-on methods of looking at the effects of the basic parameters of an epidemic, and also some simple vaccination scenarios.
Installation and Download
Zombie Sim II 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 II 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
The tool will display 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 near that colour. The big button in the bottom left runs the spatial simulator, and the graph will start animating. You can drag the slider below the graph to see previous frames of the movie, and to swish it backwards and forwards which looks very cool. See the movies on the right - particularly the last one, where the different coloured graphs show different levels of vaccination.
The parameters are fairly self explanatory, starting with the basic reproductive rate R0, and infectious period in days. I'd suggest keeping R0 below 4, or it starts to get slow at dealing with the number of cases. You can then vaccinate a certain proportion of people within a certain range of your favourite city. If you set the proportion to 100%, you will see a golf-ball of protection on the map to prove that it's working (unrealistically!) Similarly, you can pick your least favourite city and choose to start an epidemic there. 4 or 5 seeds should cause an epidemic every time, but the simulation is stochastic, so sometimes if you pick just one seed, you might get an epidemic that dies off very early.
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
Like the earlier version, there are two. /MOVIE will cause screenshots of the whole app to 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="Simulation" 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, but since this version doesn't have a drop down box of different configurations, you have to overwrite the existing one. Then these parameters will be the defaults when you start up. There are more parameters in the XML above than the Zombie II interface lets you edit, as the executable spatial simulation is the same one as Zombie Sim I's, which exposed all of these features. If, for some reason, you want to set some of these non-editable parameters to certain values, then the best way probably is to run Zombie Sim I in /UNDEAD mode, export the XML, and then paste it into Zombie Sim II's z_conf.xml file.
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.
As we said in the command-line section, the source for the C++ executable is identical for this version, as for Zombie Sim I; hence it supports all the parameters the earlier version let you change, but they are not in the simpler user interface.
Usage History
Here are the events where we've used the tool.
- May 2016 - Imperial Festival.
- May 2015 - Imperial Festival.
- March 2015 - HPRU Open Day.
Credits and Thanks
The Zombie II Sim interface, simulation code and widget kit was written by Wes Hinsley, with particular design and presentation help on the simplification of Zombie Sim I from Harriet Mills and Rafal Nostowy. 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. Many thanks to all others who have demonstrated the tool and given feedback.