Getting Started¶
This tutorial assumes that you have installed metawards. To check
that you have, type the following into your console;
metawards --version
and then press return. You should see something similar to the below printed to your screen.
$ metawards --version
************************
metawards version 0.10.0
************************
-- Source information --
repository: https://github.com/metawards/MetaWards
branch: 0.10.0)
revision: 56949a79ae23b0b9a1310d2a74b37830c1ea3af5
last modified: 2020-04-27T13:06:36+0100
-- Additional information --
Visit https://metawards.github.io for more information
about metawards, its authors and its license
If you don’t see this, or the output includes a warning about not being about to find MetaWardsData, then please try installing MetaWards or installing and configuring MetaWardsData again.
Warning
This tutorial is written for metawards version 0.10.0 or
higher. If you are using an older version then please upgrade.
Introducing the Lurgy¶
The Lurgy is a
completely ficticious disease that we will use throughout this
tutorial. We can run a simulation of an outbreak of the lurgy using
the --disease command line argument. Type the following;
metawards --disease lurgy
Press return and you should see a lot of output printed. Near the end of the output you will see these lines;
S: 56082077 E: 0 I: 0 R: 0 IW: 0 TOTAL POPULATION 56082077
0 0
S: 56082077 E: 0 I: 0 R: 0 IW: 0 TOTAL POPULATION 56082077
1 0
S: 56082077 E: 0 I: 0 R: 0 IW: 0 TOTAL POPULATION 56082077
2 0
S: 56082077 E: 0 I: 0 R: 0 IW: 0 TOTAL POPULATION 56082077
3 0
S: 56082077 E: 0 I: 0 R: 0 IW: 0 TOTAL POPULATION 56082077
4 0
S: 56082077 E: 0 I: 0 R: 0 IW: 0 TOTAL POPULATION 56082077
Infection died ... Ending on day 5
Note
Do not worry if you don’t see exactly this output. You may be using
a different version of metawards compared to the one used to write
this tutorial. The main thing to look for is the line
Infection died ... Ending on day 5
The --disease option also has the shorthand -d. You can get the same
output as above by typing;
metawards -d lurgy
Note
This time when you ran metawards it stopped to say that the output
directory already exists, and if you want to remove it.
The metawards program takes care not to overwrite any of your output.
By default a lot of output files from this run have been written to a
directory called output (we will take a look at these files later).
metawards will ask you if you want to remove any existing output.
Press y and hit return to do so. If you want to automatically
remove existing output then use the --force-overwrite-output option,
e.g.
metawards -d lurgy --force-overwrite-output
You can also set the output directory using the --output or -o
options, e.g.
metawards -d lurgy -o output2
Seeding an outbreak¶
The key output from metawards are the lines which read;
S: 56082077 E: 0 I: 0 R: 0 IW: 0 TOTAL POPULATION 56082077
0 0
S: 56082077 E: 0 I: 0 R: 0 IW: 0 TOTAL POPULATION 56082077
1 0
S: 56082077 E: 0 I: 0 R: 0 IW: 0 TOTAL POPULATION 56082077
2 0
S: 56082077 E: 0 I: 0 R: 0 IW: 0 TOTAL POPULATION 56082077
3 0
S: 56082077 E: 0 I: 0 R: 0 IW: 0 TOTAL POPULATION 56082077
4 0
S: 56082077 E: 0 I: 0 R: 0 IW: 0 TOTAL POPULATION 56082077
Infection died ... Ending on day 5
These tell you how long the outbreak lasted (in this case, 5 days), together with how many people were infected. These are the numbers next to the codes;
- S: The number of the population who are susceptible to infection
- E: The number of the population who are latent, meaning they are infected, but not yet infectious.
- I: The number of the population who are infected, meaning they have symptoms and are infectious
- R: The number of the population who are removed from the outbreak, e.g. because they have recovered and are no longer susceptible to infection
- IW: The number electoral wards that contain at least one infected individual.
For more information about these values, please read the papers detailed in the scientific background.
From this output it is clear that no-one has been infected by the lurgy.
This is because we haven’t yet seeded any outbreaks. We can seed an
outbreak in a specific electoral ward by using an additional seeds file.
In this case, we will seed an infection of the lurgy in London using
the ExtraSeedsLondon.dat
file that comes in MetaWardsData. You specify the additional seeds
file to use via the --additional or -a options.
Try typing the below into your console and press return;
metawards -d lurgy -a ExtraSeedsLondon.dat
Now the program will run for a long time (minutes), and you will see an outbreak move through the population. The final lines of your output may look something like this;
217 9
S: 11772514 E: 0 I: 7 R: 44309556 IW: 1 TOTAL POPULATION 56082077
218 7
S: 11772513 E: 1 I: 7 R: 44309556 IW: 1 TOTAL POPULATION 56082076
219 8
S: 11772512 E: 1 I: 5 R: 44309559 IW: 1 TOTAL POPULATION 56082076
220 6
S: 11772512 E: 1 I: 5 R: 44309559 IW: 0 TOTAL POPULATION 56082076
221 6
S: 11772512 E: 0 I: 3 R: 44309562 IW: 0 TOTAL POPULATION 56082077
222 3
S: 11772512 E: 0 I: 2 R: 44309563 IW: 0 TOTAL POPULATION 56082077
223 2
S: 11772512 E: 0 I: 2 R: 44309563 IW: 0 TOTAL POPULATION 56082077
224 2
S: 11772512 E: 0 I: 0 R: 44309565 IW: 0 TOTAL POPULATION 56082077
Infection died ... Ending on day 225
Note
Do not worry if your numbers are different. All will be explained :-)
Repeating a calculation¶
metawards runs a stochastic simulation. This means that random numbers
are used in the decisions on how individuals in the model are infected,
and how quickly they progress through the infection. This means that
every metawards run is different.
Fortunately, metawards prints enough information in the output
to enable a job to be repeated. Look the for line the reads;
******************************************
*** To repeat this job use the command ***
******************************************
metawards --repeats 1 --seed 20460833 --additional ExtraSeedsLondon.dat --output output --UV 0.0 --disease lurgy --input-data 2011Data --start-date 2020-04-20 --start-day 0 --parameters march29 --repository /Users/chris/GitHub/MetaWardsData --population 57104043 --nthreads 4 --nprocs 1
This is the command line that you can use to repeat a job (note that
the command line you see will be different). We have been careful to
write metawards so that it gives the same output when you use
the same inputs, using the same version of metawards and same version
of data in MetaWardsData, for the same random number seed and running
the calculation over the same number of threads. We consider it a bug
if metawards is not reproducible, and ask that you
submit an issue if
you find you cannot repeat a run.