metawards.Ward

class metawards.Ward(id: Optional[int] = None, name: Optional[str] = None, code: Optional[str] = None, authority: Optional[str] = None, region: Optional[str] = None, info: Optional[metawards._wardinfo.WardInfo] = None, auto_assign_players: bool = True)

This class holds all of the information about a Ward. It is used to create and edit Networks

__init__(id: Optional[int] = None, name: Optional[str] = None, code: Optional[str] = None, authority: Optional[str] = None, region: Optional[str] = None, info: Optional[metawards._wardinfo.WardInfo] = None, auto_assign_players: bool = True)

Construct a new Ward, optionally supplying information about the ward

Parameters

• id (int) – The identifier for the ward. This must be an integer that is greater or equal to 1. Every ward in a network must have a unique ID. Typically the IDs should be contiguous, as this ID is used as the index into the Network array

• name (str) – The name of this ward. This can be used to find the ward.

• code (str) – The code of this ward. This is used when wards are identified by codes, rather than names

• authority (str) – The local authority name for this node

• region (str) – The name of the region containing this ward

• info (WardInfo) – The complete WardInfo used to identify this ward.

• auto_assign_players (bool) – Whether or not to automatically ensure that all remaining player weight is assigned to players who play in their home ward

Methods

__add__(other)
__delattr__(name, /)	Implement delattr(self, name).
__dir__()	Default dir() implementation.
__eq__(other)	Return self==value.
__format__(format_spec, /)	Default object formatter.
__ge__(value, /)	Return self>=value.
__getattribute__(name, /)	Return getattr(self, name).
__gt__(value, /)	Return self>value.
__imul__(scale)	In-place multiply the number of workers and players by ‘scale’
__init__([id, name, code, authority, …])	Construct a new Ward, optionally supplying information about the ward
__init_subclass__	This method is called when a class is subclassed.
__le__(value, /)	Return self<=value.
__lt__(value, /)	Return self<value.
__mul__(scale)	Scale the number of workers and players by ‘scale’
__ne__(value, /)	Return self!=value.
__new__(**kwargs)	Create and return a new object.
__reduce__()	Helper for pickle.
__reduce_ex__(protocol, /)	Helper for pickle.
__repr__()	Return repr(self).
__rmul__(scale)	Scale the number of workers and players by ‘scale’
__setattr__(name, value, /)	Implement setattr(self, name, value).
__sizeof__()	Size of object in memory, in bytes.
__str__()	Return str(self).
__subclasshook__	Abstract classes can override this to customize issubclass().
_harmonise_links(other)	Make sure that this ward has exactly the same links as ‘other’.
_resolve_destination([destination])	Resolve the passed destination into either an ID or a WardInfo object
add_player_weight(weight[, destination])	Add the weight for players who will randomly move to the specified destination to play(or to play in the home ward if destination is not set).
add_workers(number[, destination])	Add some workers to this ward, specifying their destination if they work out of ward
assert_sane()	Assert that the data in this ward is sane
authority()	Return the local authority of this ward
auto_assign_players()	Return whether or not the remaining player weight is automatically added to the home-ward player weight
bg_foi()	Return the background force of infection (FOI).
code()	Return the code of this ward
custom(key[, default])	Return the per-ward custom parameter at key ‘key’, returning ‘default’ if this has not been set.
cutoff()	Return the cutoff parameter for this ward.
depopulate([zero_player_weights])	Return a copy of this Ward with exact same details, but with zero population.
dereference(wards[, _inplace])	Dereference the IDs and convert those back to WardInfo objects.
from_data(data)	Return a Ward that has been created from the passed dictionary (e.g.
from_json(s)	Return the Ward constructed from the passed json.
get_player_lists([no_auto_assign])	Return a pair of arrays, containing the destination wards and player weights for this ward.
get_players([destination])	Return the fraction of players who will play in the specified destination ward (or who play in their home ward if destination is not set)
get_worker_lists()	Return a pair of arrays, containing the destination wards and worker populations for this ward
get_workers([destination])	Return the number of workers who commute to the specified destination ward (or who commute to their home ward if destination is not set)
id()	Return the ID of this ward
info()	Return (a copy of) the WardInfo containing all ward identifying metadata
is_null()
is_resolved()	Return whether or not any of the worker or player links in this ward are unresolved, or whether the ID of this ward is None
merge(other)	Merge in the data from ‘other’ into this Ward.
name()	Return the name of this ward
num_play_links()	Return the total number of play links
num_players()	Return the total number of players who make their home in this ward
num_work_links()	Return the total number of work links
num_workers()	Return the total number of workers who make their home in this ward
play_connections()	Return the full list of play connections for this ward
population()	Return the total population of this ward
position()	Return the position of the center of this ward.
region()	Return the region containing this ward
resolve(wards[, _inplace])	Resolve any unresolved links using the passed Wards object ‘wards’
scale([work_ratio, play_ratio, _inplace])	Return a copy of these wards where the number of workers and players have been scaled by ‘work_ratios’ and ‘play_ratios’ respectively.
scale_uv()	Return the scale_uv parameter for this ward.
set_authority(authority)	Set the local authority of this ward
set_auto_assign_players([auto_assign_players])	Return whether or not the remaining player weight is automatically assigned to the home-ward player weight
set_bg_foi(bg_foi)	Set the background force of infection (FOI).
set_code(code)	Set the code of this ward
set_custom(key, value)	Set the value of the custom ward parameter to ‘value’.
set_cutoff(cutoff)	Set the cutoff distance (in km) for this ward.
set_id(id)	Set the ID of this ward
set_info(info)	Set the info of this ward
set_name(name)	Set the name of this ward
set_num_players(number)	Set the number of players in this ward
set_num_workers(number)	Set the number of workers in this ward.
set_position([x, y, lat, long, units])	Set the position of the centre of this ward.
set_region(region)	Set the region of this ward
set_scale_uv(scale_uv)	Set the scale_uv parameter for this ward.
subtract_player_weight(weight[, destination])	Subtract the weight for players who will randomly move to the specified destination to play (or to play in the home ward if destination is not set).
subtract_workers(number[, destination])	Remove some workers from this ward, specifying their destination if they work out of ward
to_data()	Return a dictionary that can be serialised to JSON
to_json([filename, indent, auto_bzip])	Serialise the ward to JSON.
work_connections()	Return the full list of work connections for this ward

Attributes

__dict__
__doc__
__hash__
__module__
__weakref__	list of weak references to the object (if defined)

__eq__(other)

Return self==value.

__imul__(scale: float) → metawards._ward.Ward

In-place multiply the number of workers and players by ‘scale’

__init__(id: Optional[int] = None, name: Optional[str] = None, code: Optional[str] = None, authority: Optional[str] = None, region: Optional[str] = None, info: Optional[metawards._wardinfo.WardInfo] = None, auto_assign_players: bool = True)

Construct a new Ward, optionally supplying information about the ward

Parameters

• id (int) – The identifier for the ward. This must be an integer that is greater or equal to 1. Every ward in a network must have a unique ID. Typically the IDs should be contiguous, as this ID is used as the index into the Network array

• name (str) – The name of this ward. This can be used to find the ward.

• code (str) – The code of this ward. This is used when wards are identified by codes, rather than names

• authority (str) – The local authority name for this node

• region (str) – The name of the region containing this ward

• info (WardInfo) – The complete WardInfo used to identify this ward.

• auto_assign_players (bool) – Whether or not to automatically ensure that all remaining player weight is assigned to players who play in their home ward

__mul__(scale: float) → metawards._ward.Ward

Scale the number of workers and players by ‘scale’

__repr__()

Return repr(self).

__rmul__(scale: float) → metawards._ward.Ward

Scale the number of workers and players by ‘scale’

__str__()

Return str(self).

add_player_weight(weight: float, destination: Optional[int] = None)

Add the weight for players who will randomly move to the specified destination to play(or to play in the home ward if destination is not set). Note that the sum of player weights cannot be greater than 1.0.

add_workers(number: int, destination: Optional[Union[int, metawards._wardinfo.WardInfo]] = None)

Add some workers to this ward, specifying their destination if they work out of ward

assert_sane()

Assert that the data in this ward is sane

authority()

Return the local authority of this ward

auto_assign_players() → bool

Return whether or not the remaining player weight is automatically added to the home-ward player weight

bg_foi() → float

Return the background force of infection (FOI). This is the starting value for ward FOI calculations. It defaults to 0.0. Positive values are used when you want the ward to have some background effect that drives infections independently of the number of infecteds. Negative values imply a background effect that reduces the risk of infection, regardless of the number of infecteds

code()

Return the code of this ward

custom(key: str, default: float = 0.0) → float

Return the per-ward custom parameter at key ‘key’, returning ‘default’ if this has not been set. Note that all custom parameters are stored as floats

cutoff() → float

Return the cutoff parameter for this ward. This sets the maximum distance that residents (or travellers) to this ward can travel

depopulate(zero_player_weights: bool = False) → metawards._ward.Ward

Return a copy of this Ward with exact same details, but with zero population. If ‘zero_player_weights’ is True, then this will also zero the player weights for all connected wards

dereference(wards: Wards, _inplace: bool = False) → Ward

Dereference the IDs and convert those back to WardInfo objects. This is the opposite of self.resolve(wards). This will return the dereferenced ward.

static from_data(data)

Return a Ward that has been created from the passed dictionary (e.g. which has been deserialised from JSON)

static from_json(s: str)

Return the Ward constructed from the passed json. This will either load from a passed json string, or from json loaded from the passed file

get_player_lists(no_auto_assign: bool = False)

Return a pair of arrays, containing the destination wards and player weights for this ward.

If ‘no_auto_assign’ is set then do not include any auto-assigned weights. This normally should be false, as it is only used when serialising

get_players(destination: Optional[int] = None)

Return the fraction of players who will play in the specified destination ward (or who play in their home ward if destination is not set)

get_worker_lists()

Return a pair of arrays, containing the destination wards and worker populations for this ward

get_workers(destination: Optional[int] = None)

Return the number of workers who commute to the specified destination ward (or who commute to their home ward if destination is not set)

id()

Return the ID of this ward

info()

Return (a copy of) the WardInfo containing all ward identifying metadata

is_resolved()

Return whether or not any of the worker or player links in this ward are unresolved, or whether the ID of this ward is None

merge(other) → None

Merge in the data from ‘other’ into this Ward. The ‘info’ and the ID numbers must match (or be None).

This will add the workers from ‘other’ to this ward, plus will average the player weights between the two

This will do nothing to the scale_uv, cutoff, bg_foi or custom parameters

name()

Return the name of this ward

num_play_links()

Return the total number of play links

num_players()

Return the total number of players who make their home in this ward

num_work_links()

Return the total number of work links

num_workers()

Return the total number of workers who make their home in this ward

play_connections()

Return the full list of play connections for this ward

population()

Return the total population of this ward

position()

Return the position of the center of this ward. This will return a dictionary containing either the {“x”, “y”} coordinates (in kilometers) or containing the {“lat”, “long”} coordinates, or an empty dictionary if cooordinates have not been set.

region()

Return the region containing this ward

resolve(wards: Wards, _inplace: bool = None) → Ward

Resolve any unresolved links using the passed Wards object ‘wards’

scale(work_ratio: float = 1.0, play_ratio: float = 1.0, _inplace: bool = False) → metawards._ward.Ward

Return a copy of these wards where the number of workers and players have been scaled by ‘work_ratios’ and ‘play_ratios’ respectively. These can be greater than 1.0, e.g. if you want to scale up the number of workers and players

Parameters

• work_ratio (float) – The scaling ratio for workers

• play_ratio (float) – The scaling ratio for players

Returns

Wards

Return type

A copy of this Wards scaled by the requested amount

scale_uv() → float

Return the scale_uv parameter for this ward. This is the amount by which to scale the force of infection (FOI) during the FOI calculation

set_authority(authority: str)

Set the local authority of this ward

set_auto_assign_players(auto_assign_players: bool = True)

Return whether or not the remaining player weight is automatically assigned to the home-ward player weight

set_bg_foi(bg_foi: float)

Set the background force of infection (FOI). This is the starting value for ward FOI calculations. It defaults to 0.0. Positive values are used when you want the ward to have some background effect that drives infections independently of the number of infecteds. Negative values imply a background effect that reduces the risk of infection, regardless of the number of infecteds

set_code(code: str)

Set the code of this ward

set_custom(key: str, value: float)

Set the value of the custom ward parameter to ‘value’. Note that this must be convertible to a float as all custom parameters are stored as floats

set_cutoff(cutoff: float)

Set the cutoff distance (in km) for this ward. This is the maximum distance that residents (or travellers to) this ward are allowed to travel. This defaults to 99999.99, which is larger than any point to point distance on earth

set_id(id: int)

Set the ID of this ward

set_info(info: metawards._wardinfo.WardInfo)

Set the info of this ward

set_name(name: str)

Set the name of this ward

set_num_players(number: int)

Set the number of players in this ward

set_num_workers(number: int)

Set the number of workers in this ward.

set_position(x: Optional[float] = None, y: Optional[float] = None, lat: Optional[float] = None, long: Optional[float] = None, units: str = 'm')

Set the position of the centre of this ward. This can be set either as x/y coordinates or latitude/longitude coordinates.

Parameters

• x (float) – The x coordinates if x/y are used. The units are set via the ‘units’ argument

• y (float) – The y coordinates if x/y are used. The units are set via the ‘units’ argument

• units (str) – The units for x/y coordinates. This should be “m” for meters or “km” for kilometers

• lat (float) – The latitude if lat/long coordinates are used

• long (float) – The longitude if lat/long coordinates are used

set_region(region: str)

Set the region of this ward

set_scale_uv(scale_uv: float)

Set the scale_uv parameter for this ward. This is the amount by which to scale the FOI when caclulating the FOI. This defaults to 1.0

subtract_player_weight(weight: float, destination: Optional[int] = None)

Subtract the weight for players who will randomly move to the specified destination to play (or to play in the home ward if destination is not set).

subtract_workers(number: int, destination: Optional[int] = None)

Remove some workers from this ward, specifying their destination if they work out of ward

to_data()

Return a dictionary that can be serialised to JSON

to_json(filename: Optional[str] = None, indent: Optional[int] = None, auto_bzip: bool = True) → str

Serialise the ward to JSON. This will write to a file if filename is set, otherwise it will return a JSON string.

Parameters

• filename (str) – The name of the file to write the JSON to. The absolute path to the written file will be returned. If filename is None then this will serialise to a JSON string which will be returned.

• indent (int) – The number of spaces of indent to use when writing the json

• auto_bzip (bool) – Whether or not to automatically bzip2 the written json file

Returns

Returns either the absolute path to the written file, or the json-serialised string

Return type

str

work_connections()

Return the full list of work connections for this ward