Usage¶
metawards program¶
MetaWards comes with a command-line program called metawards.
This is installed by default into the same directory as the
python executable used to build the package. To run metawards
type;
metawards --version
This prints out the version of metawards, which should look something
like this;
┌──────────────────────────────────────────────────────────────────────┐
│ │
│ ╔══════════════════════════════════════════════════════════════╗ │
│ ║ MetaWards version 1.5.1 ║ │
│ ╚══════════════════════════════════════════════════════════════╝ │
│ │
│ ╔══════════════════════════════════════════════════════════════╗ │
│ ║ https://metawards.org ║ │
│ ╚══════════════════════════════════════════════════════════════╝ │
│ │
│ ╔══════════════════════════════════════════════════════════════╗ │
│ ║ Source information ║ │
│ ╚══════════════════════════════════════════════════════════════╝ │
│ │
│ • repository: https://github.com/metawards/MetaWards │
│ • branch: 1.5.1) │
│ • revision: c1793dadc7c4a53cf9d467743ce88b6d43ae16c0 │
│ • last modified: 2021-02-26T11:30:56+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 │
│ │
└──────────────────────────────────────────────────────────────────────┘
This version information gives you the provenance of this executable which should help in reproducing output. It is written to the top of all metawards outputs.
If you see output like this, with WARNING lines about the version
not having been committed to git…
┌──────────────────────────────────────────────────────────────────────┐
│ │
│ │
│ MetaWards version 0.12.0+17.gd839bca1.dirty │
│ │
│ │
│ https://metawards.org │
│ │
│ Source information │
│ │
│ • repository: https://github.com/metawards/MetaWards │
│ • branch: feature-mover-tutorial │
│ • revision: d839bca1e32e8c8b1814d7f72667e84ead1a59d7 │
│ • last modified: 2020-05-20T13:01:14+0100 │
│ │
│ WARNING: This version has not been committed to git, so you may │
│ not be able to recover the original source code that was used to │
│ generate this run! │
│ │
│ MetaWardsData information │
│ │
│ • version: 0.5.0 │
│ • repository: https://github.com/metawards/MetaWardsData │
│ • branch: main │
│ │
│ Additional information │
│ │
│ Visit https://metawards.org for more information about metawards, │
│ its authors and its license │
│ │
└──────────────────────────────────────────────────────────────────────┘
then this means that your metawards executable has been built using
source code that has not been committed to git, and is therefore not
version controlled. Do not use dirty software for production jobs
as it will not be possible to recover the software used to produce
outputs at a later date, and thus it may not be possile to reproduce
results.
Getting help¶
The metawards program has up-to-date and very comprehensive in-built
help for all of its command line options. You can print this help by
typing;
metawards --help
The full help is available here.
Understanding the options¶
metawards is a powerful program so it comes with a lot of options.
The most used and thus most important options are given first. These
are;
--disease / -d: Specify the name of the disease file to load. These files are described in Model data. If the file exists in your path then that will be used. Otherwise the file will be searched for from theMetaWardsData/diseasesdirectory. Note that you don’t need to specify the file type, as this is assumed to be.json.--input / -i: Specify the input file adjustable parameters that will be explored for the model run. You must supply an input file to be able to run a model. This file is described below.--line / -l: Specify the line number (or line numbers) of adjustable parameter sets from the input file. Line numbers are counted from 0, and multiple line numbers can be given, e.g.--line 3, 5, 7-10will read from lines 3, 5, 7, 8, 9, and 10 (remembering that the first line of the file is line 0). If multiple lines are read, then multiple model runs will be performed.--repeats / -r: specify the number of times model runs for each adjustable parameter set should be repeated. MetaWards model runs are stochastic, based on random numbers. The results for multiple runs must thus be processed to derive meaning.--additional / -a: specify the file (or files) containing additional seeds. These files are described in Model data. You can specify as many or few files as you wish. If the file exists in your path then that will be used. Otherwise the file will be searched for from theMetaWardsData/extra_seedsdirectory. Note that you can write the additional seeds directly, rather than using a file. To see how, take a look at this section of the tutorial.--output / -o: specify the location to place all output files. By default this will be in a new directory calledoutput. A description of the output files is below.--seed / -s: specify the random number seed to use for a run. By default a truly random seed will be used. This will be printed into the output, so that you can use it together with this option to reproduce a run. The same version ofmetawardswill reproduce the same output when given the same input, same random number seed, and run over the same number of threads.--start-date: specify the date of day zero of the model outbreak. If this isn’t specified then this defaults to the current date. This recognises any date that is understood bymetawards.Interpret.date(), which includes dates like today, tomorrow, Monday, Jan 2020 etc. The start date is used to trigger events based on day of week or date within a model outbreak (e.g. is the day a weekend)--start-day: specify the day of the outbreak, e.g. the default is0for day zero. This is useful if you want to start the model run from a later day than the start date. Note that the start date passed via--start-dateis the date of day zero, so the first day modelled will be--start-daydays after--start-date.--nthreads: specify the number of threads over which to perform a model run. The sequence of random numbers drawn in parallel is deterministic for a given number of threads, but will be different for different numbers of threads. This is why you can only reproduce a model run using a combination of the same random number seed and same number of threads. The number of threads used for a model run is written into the output.--nprocs: specify the number of processes over which you want to parallelise the model runs. This is useful if you have multiple processors on your computer and you are running multiple model runs. Note that this option is set automatically for you if you are running on a cluster.
Using these options, a typical metawards run can be performed
using;
metawards -d ncov -a "1 5 1"
This python port of metawards was written to reproduce the output
of the original C code. This original code is bundled with this
port and is in the original directory. There are several integration
tests included in the unit testing suite that validate that the
Python code still reproduces the results generated using the C code.
Understanding the input¶
The input file for metawards is a
design file that can be as
simple as a set of lines containing
five comma-separated or space-separated values per line, e.g.
0.95,0.95,0.19,0.91,0.91
0.90,0.93,0.18,0.92,0.90
or
0.90 0.93 0.18 0.92 0.90
These five values per line adjust the beta[2], beta[3],
progress[1], progress[2] and progress[3] parameters of
the disease model as described in Model Data.
You can optionally choose which parameters will be varied by adding a title line, e.g.
beta[2] progress[2] progress[3]
0.90 0.92 0.90
0.85 0.91 0.92
specifies that you want to adjust the beta[2], progress[2] and
progress[3] parameters to the specified values.
This file can adjust a lot more, include user-specified parameters, and control the numbers of repeats and output directories. Please see the full file format description for more information.
Understanding the output¶
The output of metawards is primarily a trajectory of the outbreak
through the model population. This is reported daily from the first
day (day 0) until the outbreak ends. For single runs this is printed
to the screen, e.g.
21 58
S: 56081959 E: 52 I: 17 R: 49 IW: 9 TOTAL POPULATION 56082025
A model run moves individuals between different states according to whether they become infected, and then progress through the outbreak. The codes mean;
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.
As well as being printed to the screen, this data is also written
to the CSV file output/results.csv.bz2 for easy reading and analysis
using R or Python pandas.
If multiple model runs are performed, then each run is given a fingerprint
based on the adjustable parameters and repeat number. The output is written
to output/[fingerprint]_[repeat]/output.txt. In addition, results
for all of the runs are combined into a single output/results.csv.bz2
file for easy combined analysis.
For example, this output could be read into a pandas dataframe using
import pandas as pd
df = pd.read_csv("output/results.csv.bz2")
df # perform analysis
We run a good online workshop on how to use pandas for data analysis.
Note
The E, I and R stages are just the defaults, and metawards
does support custom disease stages which may not have E, I or R.
To learn more, take a look at the
tutorial on custom named stages.
metawards-plot¶
For quick and simple plots, metawards comes with the command-line
program metawards-plot. This can be used to create plots of the
data in the output/results.csv.bz2 file using, e.g.
metawards-plot --input output/results.csv.bz2
For full help on this program using metawards-plot --help.
The full help is available here.