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 1.4.1                    ║   │
│   ╚══════════════════════════════════════════════════════════════╝   │
│                                                                      │
│   ╔══════════════════════════════════════════════════════════════╗   │
│   ║                    https://metawards.org                     ║   │
│   ╚══════════════════════════════════════════════════════════════╝   │
│                                                                      │
│   ╔══════════════════════════════════════════════════════════════╗   │
│   ║                      Source information                      ║   │
│   ╚══════════════════════════════════════════════════════════════╝   │
│                                                                      │
│    • repository: https://github.com/metawards/MetaWards              │
│    • branch: 1.4.1)                                                  │
│    • revision: 18f7ff160d4b7e037e059bee29d17d9a9b709892              │
│    • last modified: 2020-11-18T14:41:12+0000                         │
│                                                                      │
│   WARNING: MetaWardsData cannot be found! Please see                 │
│   https://metawards.org/model_data for instructions on how to        │
│   download and install this necessary data.                          │
│                                                                      │
│   ╔══════════════════════════════════════════════════════════════╗   │
│   ║                    Additional information                    ║   │
│   ╚══════════════════════════════════════════════════════════════╝   │
│                                                                      │
│   Visit https://metawards.org 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 1.4.1 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;

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Day 0 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
S: 56082077  E: 0  I: 0  R: 0  IW: 0  POPULATION: 56082077
Number of infections: 0

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Day 1 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
S: 56082077  E: 0  I: 0  R: 0  IW: 0  POPULATION: 56082077
Number of infections: 0

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Day 2 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
S: 56082077  E: 0  I: 0  R: 0  IW: 0  POPULATION: 56082077
Number of infections: 0

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Day 3 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
S: 56082077  E: 0  I: 0  R: 0  IW: 0  POPULATION: 56082077
Number of infections: 0

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Day 4 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
S: 56082077  E: 0  I: 0  R: 0  IW: 0  POPULATION: 56082077
Number of infections: 0
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;

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Day 0 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
S: 56082077  E: 0  I: 0  R: 0  IW: 0  POPULATION: 56082077
Number of infections: 0

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Day 1 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
S: 56082077  E: 0  I: 0  R: 0  IW: 0  POPULATION: 56082077
Number of infections: 0

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Day 2 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
S: 56082077  E: 0  I: 0  R: 0  IW: 0  POPULATION: 56082077
Number of infections: 0

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Day 3 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
S: 56082077  E: 0  I: 0  R: 0  IW: 0  POPULATION: 56082077
Number of infections: 0

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Day 4 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
S: 56082077  E: 0  I: 0  R: 0  IW: 0  POPULATION: 56082077
Number of infections: 0
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 being susceptible, either because they have been newly infected that day, or because they have recovered from the infection and are no longer susceptible to infection

  • IW: The number of electoral wards that contain at least one individual who was newly infected that day.

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;

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Day 214 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
S: 11780863  E: 0  I: 1  R: 44301213  IW: 1  POPULATION: 56082077
Number of infections: 1

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Day 215 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
S: 11780863  E: 1  I: 0  R: 44301213  IW: 0  POPULATION: 56082077
Number of infections: 1

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Day 216 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
S: 11780863  E: 0  I: 1  R: 44301213  IW: 0  POPULATION: 56082077
Number of infections: 1

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Day 217 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
S: 11780863  E: 0  I: 1  R: 44301213  IW: 0  POPULATION: 56082077
Number of infections: 1

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Day 218 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
S: 11780863  E: 0  I: 0  R: 44301214  IW: 0  POPULATION: 56082077
Number of infections: 0
Infection died ... Ending on day 219

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;

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Repeating this run ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
To repeat this job use the command;
┌────────────────────────────────────────────────────────────────────────────────────────┐
│metawards –repeats 1 –seed 85564100 –additional ExtraSeedsLondon.dat –output output     │
│–disease lurgy –start-date 2020-05-20 –start-day 0 –parameters march29 –repository      │
│/Users/chris/GitHub/MetaWardsData –population 57104043 –nsteps 730 –UV 0.0 –nthreads 4  │
│–nprocs 1 –max-nodes 16384 –max-links 4194304                                           │
└────────────────────────────────────────────────────────────────────────────────────────┘
Or alternatively use the config.yaml file that will be written to the output directory and
use the command;
┌────────────────────────────────────────────────────────────────────────────────────────┐
│metawards -c config.yaml                                                                │
└────────────────────────────────────────────────────────────────────────────────────────┘

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.

As the command line can be quite long, metawards will also print out a config file in the output directory called output/config.yaml. This file contains everything needed to reproduce the calculation, which can be re-run using the command;

metawards -c config.yaml

(assuming you have copied the config.yaml file into your current directory)

Using config files for inputs

You can use this config file directly to run a job using the --config or -c options, e.g.

metawards --config config.yaml

This should repeat the calculation that generated this config. You can also edit this file and use it to store commonly used options, e.g. if you always want to model the lurgy, then the config file would read;

disease: lurgy

and you could use this via

metawards -c config.yaml

Note

metawards uses the ConfigArgParse python module for parsing command line arguments. Options can be passed on the command line, in a yaml or ini format config file, or in some identified cases as an environment variable. If an arg is specified in more than one place, then commandline values override environment variables which override config file values which override defaults.