Herd Immunity

Work in progress! Details below could change!

Introduction

Also known as the Billiard Ball Game, and various alternatives! It's a fun and pretty Java application that shows a load of coloured balls bouncing around a space. At the beginning they will either be green (susceptible), or blue (vaccinated). Then a couple will turn red (infected), and they will each try to infect the next R₀ different balls they bounce into. If those victims are susceptible, then they will turn red and start trying to do their own infecting. When R₀ attempts to infect have been made, they becoming immune (grey). The vaccination percentage, and R₀ are the things you can choose; R₀ is a whole number between 3 and 8, and vaccination between 0 and 100% in 10% intervals.

After each run, the number of infections made is recorded and plotted on a graph; there is one graph for each value of R₀ with vaccination coverage on the x-axis, and number of hosts on the y-axis. After a few samples have been connected, a best fit curve will be plotted, showing the basic herd immunity principle: vaccinating for example 30% of the population causes a reduction of much more than 30% in the final number of cases.

The game can be used as a standalone application, or with various additional dependencies, it can be controlled through a tablet, which has been our favourite and most engaging way of using the game in public events.

Platforms

The code for the main app is in Java, but has only been tested so far on Windows. Will update with better cross-platform support soon - the things I'm thinking about are the fonts, and a small bunch of external scripts that are called from the web platform for clearing or restoring data. (And, trivially, the run scripts). Nothing that hard.

Running on a Standalone Machine

Download the ZIP file here, which containing Java source and compiled classes. I compiled with Java 8u91; install Java from Oracle if you need to. 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 run.bat in the root folder. (Or simply javaw Herd. Being native Java code, it should also be fine on Linux and Mac, but I haven't specifically tested.

The User Interface

It's really easy. You click the up and down arrows vary the reproductive number, and the percentage vaccination, then you click the big button to run the simulation. Then you wait and watch in awe and wonder as the simulation runs and presents you its results. At the end, you'll see a graph of all the collected samples for that R₀, and the key will highlight which sample was the one you just did. (Afraid in the current standalone version, you can't name your sample, which you can with the android version below. I might fix that one day - then again, it's nice to not really need a keyboard while you're demoing).

Demo mode

If you run run_local_demo.bat (or javaw Herd /DEMO), then it runs in a demo mode, which cycles round non-interactively, collecting data evenly across vaccination coverage and R₀ - so if you leave it running overnight, it will collect enough samples to give you good looking best-fit curves for all the graphs. There's no exit button, so you'll have to do ALT+F4 in windows to exit. (Need to test Mac/Linux!)

Managing Data

There's a batch file clear.bat, which will make a directory of the form bkp_yyyymmdd_hhmmss, and copy the current data in it. Then it will replace the data files with the ones found in "bkp_OneSample", which contain just a single point for every graph. And to restore a previously backed up dataset, (which is just a file copy really), restore.bat bkp_201609012_152819 for example. NB - at present, these batch files have the working directory hard coded into the file. I'll fix this soon - in the meantime, edit them!

Running with Androids

Web Server

We'll be using tablets to talk to the Herd Immunity main app, by being on the same wifi network, and communicating via the Web Platform for MRC Outreach Events - it's the same platform used for the Barcode Epidemic, so you only need to set it up once on one laptop, even if you want to run both the Barcode Epidemic and the Herd Immunity app at the same time. The only thing I'd suggest is: run the Herd Immunity app on a laptop of its own, because it wants all the resources it can get to run smoothly. Anyway, see the Web Platform for MRC Outreach Events page for setting up the web server platform, and make a note of the IP address of the web server, because the Herd Immunity Android app will want to know it.

The Android App

• Download the android app here, and install it in whatever way you usually coax Android to install things. Once you've got it installed, the app menu (the three dots on the top right), will let you check for updates.
• This time, you need to run the main bouncing ball software in network mode with something similar to javaw Herd /URL http://192.168.2.2/epi (or look in the run.bat file). It won't wait for you to click anything; instead it will start running simulations and collecting sample data points for its graphs, in an orderly distributed way.
• Make sure you're connected to the right wifi, and then run the android app. If it's the first time, press the three-dots, and Set Server URL to something like http://192.168.2.2/epi
• The buttons let you choose the initial percentage of the population that is vaccinated, and the reproductive number. You can also optionally give a name for the data-point you're about to collect - the most recent five points obtained for each graph can have names next to them.
• While the main app is in "Demo" mode, it loops indefinitely, keeping itself busy. As soon as you run your first android-driven experiment, it will stop that behaviour, and wait on the graph screen for someone to request the next simulation to be done. If you want it to go back into demo mode again, push the Demo Mode button!
• If the main app is busy doing a simulation, then the button on the bottom left will say "Run Soon!" - otherwise, if the main app is ready and waiting for the next parameters, it will say "Run Now!". The app will queue all the jobs up and process them in order.

Credits and Thanks

The Herd Immunity Java code, Android code and Web support was written by Wes Hinsley. The idea, and a lot of later ideas to make it much more exciting, was from Neil Ferguson. Many thanks also to all who demonstrated this in exciting ways at the Centenary event.