Command line options¶

The full set of command line options for metawards is below;

usage: metawards [-h] [--version] [-c CONFIG] [-i INPUT]
                 [-l [LINE [LINE ...]]] [-r [REPEATS [REPEATS ...]]] [-s SEED]
                 [-a [ADDITIONAL [ADDITIONAL ...]]] [-o OUTPUT] [-d DISEASE]
                 [-m MODEL] [-D DEMOGRAPHICS] [--start-date START_DATE]
                 [--start-day START_DAY] [-p PARAMETERS] [-R REPOSITORY]
                 [-P POPULATION] [-n NSTEPS] [-u USER_VARIABLES]
                 [--iterator ITERATOR] [--extractor EXTRACTOR] [--mixer MIXER]
                 [--mover MOVER] [--star-is-E] [--star-is-R] [--disable-star]
                 [--UV UV] [--UV-max UV_MAX] [--theme THEME] [--no-spinner]
                 [--no-progress] [--debug] [--debug-level DEBUG_LEVEL]
                 [--outdir-scheme OUTDIR_SCHEME] [--nthreads NTHREADS]
                 [--nprocs NPROCS] [--hostfile HOSTFILE]
                 [--cores-per-node CORES_PER_NODE] [--auto-bzip]
                 [--no-auto-bzip] [--force-overwrite-output]
                 [--max-nodes MAX_NODES] [--max-links MAX_LINKS] [--profile]
                 [--no-profile] [--mpi] [--scoop]

MetaWards epidemic modelling - see for more information.
Args that start with '--' (eg. --version) can also be set in a config file
(specified via -c). Config file syntax allows: key=value, flag=true,
stuff=[a,b,c] (for details, see syntax at If an arg is
specified in more than one place, then commandline values override environment
variables which override config file values which override defaults.

optional arguments:
  -h, --help            show this help message and exit
  --version             Print the version information about metawards
                        (default: None)
  -c CONFIG, --config CONFIG
                        Config file that can be used to set some or all of
                        these command line options. (default: None)
  -i INPUT, --input INPUT
                        Input file for the simulation that specifies the
                        adjustable parameters to change for each run of the
                        model. You must supply some input to run a model!
                        (default: None)
  -l [LINE [LINE ...]], --line [LINE [LINE ...]]
                        Line number (or line numbers) containing the values of
                        adjustable parameters to run for this run (or runs) of
                        the model If this isn't specified then model runs will
                        be performed for adjustable parameters given on all
                        lines from the input file. You can specify many
                        numbers, and ranges are also accepted, e.g. '-l 5 6-10
                        12,13,14' etc. Note that the line numbers are
                        0-indexed, e.g. the first line of the file is line 0.
                        Ranges are inclusive, so 3-5 is the same as 3 4 5
                        (default: None)
  -r [REPEATS [REPEATS ...]], --repeats [REPEATS [REPEATS ...]]
                        The number of repeat runs of the model to perform for
                        each value of the adjustable parameters. By default
                        only a single run will be performed for each set of
                        adjustable parameters. This complements the 'repeat'
                        column in the input file (in which case the repeats
                        are multipled). Also, multiple repeat values can be
                        given, in which case each value corresponds to a
                        different line in the input file (default: None)
  -s SEED, --seed SEED  Random number seed for this run (default is to use a
                        random seed) (default: None)
                        File (or files) containing additional seed of outbreak
                        for the model. These are used to seed additional
                        infections on specific days at different locations
                        during a model run (default: None)
  -o OUTPUT, --output OUTPUT
                        Path to the directory in which to place all output
                        files (default 'output'). This directory will be
                        subdivided if multiple adjustable parameter sets or
                        repeats are used. (default: None)
  -d DISEASE, --disease DISEASE
                        Name of the disease to model (default is 'ncov')
                        (default: None)
  -m MODEL, --model MODEL
                        Name of the input model data set for the network
                        (default is '2011Data') (default: None)
                        Name of the demographics file that provides
                        information about how a population is modelled as
                        multiple demographics. If this is not supplied then
                        the population is modelled as a single demographic
                        (default: None)
  --start-date START_DATE
                        Date of the start of the model outbreak. This accepts
                        dates either is iso-format, or fuzzy dates such as
                        'monday', 'tomorrow' etc. This is used to work out
                        which days are weekends, or to make it easier to
                        specify time-based events. (default: None)
  --start-day START_DAY
                        The start day of the model outbreak. By default the
                        model outbreak starts on day zero (0), with each step
                        of the model representing an additional day. Use this
                        to start from a later day, which may be useful if you
                        want to more quickly reach time based events. Note
                        that the passed '--start-date' is always day 0, so day
                        10 has a date which is 10 days after start-date
                        (default: None)
  -p PARAMETERS, --parameters PARAMETERS
                        Name of the input parameter set used to control the
                        simulation (default 'march29') (default: None)
                        Path to the MetaWardsData repository. If unspecified
                        this defaults to the value in the environment variable
                        METAWARDSDATA or, if that isn't specified, to
                        $HOME/GitHub/MetaWardsData [env var: METAWARDSDATA]
                        (default: None)
                        Initial population (default 1000) (default: None)
  -n NSTEPS, --nsteps NSTEPS
                        Maximum number of steps (days) to run for the
                        simulation. Each step represents one day in the
                        outbreak (default is to run for a maximum of two years
                        - 730 days) (default: None)
  -u USER_VARIABLES, --user-variables USER_VARIABLES
                        Name of the file containing user-defined custom
                        variables. These provide extra information that can be
                        read by the custom integrators or custom extractors.
                        (default: None)
  --iterator ITERATOR   Name of the iterator to use to advance the outbreak at
                        each step (day). For a full explanation see the
                        tutorial at (default: None)
  --extractor EXTRACTOR
                        Name of the extractor to use to extract information
                        during a model run. For a full explanation see the
                        tutorial at (default: None)
  --mixer MIXER         Name of the mixer to use to mix information from
                        multiple demographics together during a model run. For
                        a full explanation see the tutorial at
               (default: None)
  --mover MOVER         Name of the mover to use to move the population
                        between demographics during a model run. For a full
                        explanation see the tutorial at
                        (default: None)
  --star-is-E           Set the state 0 (* state) as an extra latent state, as
                        opposed to an extra R state (default: None)
  --star-is-R           Set the state 0 (* state) as an extra R state (the
                        default). Individuals in this state are calculated as
                        'R', even though they will progress on the next day to
                        the E state (default: None)
  --disable-star        Disable the * state. Now state 0 is the first and only
                        latent state. There is no star state. (default: None)
  --UV UV               Value for the UV parameter for the model (default is
                        0.0) (default: None)
  --UV-max UV_MAX       Date when the seasonal adjustment should be at its
                        maximum. By default, this is January 1st on the
                        assumption that disease spread is stronger in the
                        (Northern) winter (default: None)
  --theme THEME         The theme to use to color the output. Use '--theme
                        simple' if you prefer a simple and colorless output.
                        (default: None)
  --no-spinner          Disable the spinner that spins when little output is
                        being printed to the screen. (default: None)
  --no-progress         Disable the progress bars that show progress.
                        (default: None)
  --debug               Enable debugging output. This is useful for MetaWards
                        developers or if you are writing your own iterators,
                        extractors etc. (default: None)
  --debug-level DEBUG_LEVEL
                        Limit debug output to the specified level. (default:
  --outdir-scheme OUTDIR_SCHEME
                        Set the naming scheme for output directory names for
                        multiple model runs. Options are either 'fingerprint'
                        to use the model fingerprint, 'sequential' for
                        sequential numbering, or 'uid' to generate a unique
                        ID. (default: None)
  --nthreads NTHREADS   Number of threads over which parallelise an individual
                        model run. The total number of cores used by metawards
                        will be nprocesses x nthreads [env var:
                        OMP_NUM_THREADS] (default: None)
  --nprocs NPROCS       The number of processes over which to parallelise the
                        different model runs for different adjustable
                        parameter sets and repeats. By default this will
                        automatically work out the number of processes based
                        on the way metawards is launched. Use this option if
                        you want to specify the number of processes manually.
                        (default: None)
  --hostfile HOSTFILE   The hostfile containing the names of the compute nodes
                        over which to run a parallel job. If this is not set,
                        the program will attempt to automatically get this
                        information from the cluster queueing system. Use this
                        if the auto-detection fails (default: None)
  --cores-per-node CORES_PER_NODE
                        Set the number of processor cores available on each of
                        the compute nodes in the cluster that will be used to
                        run the models (if a cluster is used). If this is not
                        set then the program will attempt to get this
                        information from the cluster queueing system. Use this
                        option if the auto-detection fails. (default: None)
  --auto-bzip           Automatically bz2 compress all output files as they
                        are written. (default: None)
  --no-auto-bzip        Do not automatically bz2 compress all output files as
                        they are written. (default: None)
                        Whether or not to force overwriting of any existing
                        output. Using this option will tell metawards that it
                        is safe to delete the contents of the output directory
                        specified in by '--output' if it already exists.
                        Dangerous as this can remove existing output files
                        (default: False)
  --max-nodes MAX_NODES
                        Maximum number of nodes that can be read (default:
  --max-links MAX_LINKS
                        Maximum number of links that can be read (default:
  --profile             Enable profiling of the code (default: None)
  --no-profile          Disable profiling of the code (default: None)
  --mpi                 Force use of MPI to parallelise across runs (default:
  --scoop               Force use of scoop to parallelise across runs
                        (default: None)