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

__init__(id, name, code, authority, region, …)	Construct a new Ward, optionally supplying information about the ward
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
code()	Return the code of 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.
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_code(code)	Set the code of 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
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

__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: Union[int, metawards._wardinfo.WardInfo, None] = 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

code()

Return the code of this ward

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

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

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_code(code: str)

Set the code of this ward

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

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