smif.metadata package

Metadata describes the details of data structures to be exchanged between models.

class smif.metadata.Coordinates(name, elements)[source]

Bases: object

Coordinates provide the labels to index a dimension, along with metadata that may be useful to describe, visualise or convert between dimensions.

Coordinate element names are used to label each position along a finite dimension.

A dict mapping dimension name to list of coordinate elements can be passed to a Spec (or xarray.DataArray) as coords.

name

Dimension name

Type:

str

dim

Alias for dimension name

Type:

str

ids

List of labels

Type:

list

elements

List of labels with metadata

Type:

list[dict]

Parameters:

  • name (str) – Name to identify the dimension that these coordinates index

  • elements (list) – List of simple data types (used to identify elements), or a list of dicts with ‘name’ key and other metadata

Raises:

  • ValueError – If the list of elements is empty, or infinite

  • KeyError – If the elements are not a list of simple data types or a list of dicts with a ‘name’ key

property dim

Dim (dimension) is an alias for Coordinates.name

property elements

Elements are a list of dicts with at least a ‘name’ key

Coordinate elements should not be changed.

property ids

Element ids is a list of coordinate identifiers

property names

Names is an alias for Coordinates.ids

class smif.metadata.RelativeTimestep(*values)[source]

Bases: Enum

Specify current, previous or base year timestep

ALL = 'ALL'
BASE = 'BASE'
CURRENT = 'CURRENT'
PREVIOUS = 'PREVIOUS'
classmethod from_name(name)[source]
resolve_relative_to(timestep: int, timesteps: List[int]) → None | int[source]

Resolve a relative timestep with respect to a given timestep and sequence of timesteps.

Parameters:
class smif.metadata.Spec(name=None, dims=None, coords=None, dtype=None, abs_range=None, exp_range=None, unit=None, description=None)[source]

Bases: object

N-dimensional metadata.

Spec labels each dimension with coordinates and enforces data type, units and absolute and expected ranges.

The API here is modelled on xarray.DataArray: dtype and shape describe a numpy.ndarray; dims and coords follow the xarray conventions for labelled axes; and unit, abs_range and exp_range are introduced as supplementary metadata to help validate connections between models.

name

The name of the data that this spec describes

Type:

str

description

A human-friendly description

Type:

str

dtype

Data type for data values

Type:

str

abs_range

Absolute range of data values

Type:

tuple

exp_range

Expected range of data values

Type:

tuple

shape

Tuple of dimension sizes

Type:

tuple[int]

ndim

Number of dimensions

Type:

int

dims

Dimension names

Type:

list[str]

coords

Dimension coordinate labels

Type:

list[Coordinates]

unit

Units of data values

Type:

str

Parameters:

  • name (str, optional) – Name to identifiy the variable described (typically an input, output or parameter)

  • description (str, optional) – Short description

  • dims (list[str], optional) – List of dimension names, must be provided if coords is a dict

  • coords (list[Coordinates] or dict[str, list], optional) – A list of :class`Coordinates` or a dict mapping each dimension name to a list of names which label that dimension.

  • dtype (str) – String suitable for contructing a simple numpy.dtype

  • abs_range (tuple, optional) – (min, max) absolute range for numeric values - can be used to raise errors

  • exp_range (tuple, optional) – (min, max) expected range for numeric values - can be used to raise warnings

  • unit (str, optional) – Unit to be used for data values

property abs_range

The absolute range of data values that this spec describes.

as_dict()[source]

Serialise to dict representation

property coords

Coordinate labels for each dimension.

property description

A human-friendly description

dim_coords(dim: str)[source]

Coordinates for a given dimension

dim_elements(dim: str)[source]

Elements of each coordinate in a given dimension

dim_names(dim: str)[source]

Names of each coordinate in a given dimension

property dims

Names for each dimension

property dtype

The dtype of the data that this spec describes.

property exp_range

The expected range of data values that this spec describes.

classmethod from_dict(data_provided)[source]

Create a Spec from a dict representation

property name

The name of the data that this spec describes.

property ndim

The number of dimensions of the data that this spec describes.

property shape

Tuple of dimension sizes. The shape of the data that this spec describes.

property unit

The unit for all data points.

Submodules

smif.metadata.coordinates module

Each dimension of a multi-dimensional dataset can be indexed by a set of coordinates.

Dimensions might be represented as Euclidean coordinates over a grid:

>>> x = Coordinates('x', range(0, 100))
>>> y = Coordinates('y', range(0, 100))

A subset of Local Authority Districts in England would be a region-based spatial dimension:

>>> local_authority_districts = Coordinates('LADs', ['E07000128', 'E07000180'])

The hours of an average annual day would be a temporal dimension:

>>> hours = Coordinates('daily_hours', [
...     {'name': 0, 'interval': [['PT0H', 'PT1H']]}
...     {'name': 1, 'interval': [['PT1H', 'PT2H']]}
...     {'name': 2, 'interval': [['PT2H', 'PT3H']]}
... ])

The economic sectors from the International Standard Industrial Classification of All Economic Activities (ISIC), revision 4 would be a categorical dimension:

>>> economic_sector = Coordinates('ISICrev4', [
...     {'name': 'A', 'desc': 'Agriculture, forestry and fishing'},
...     {'name': 'B', 'desc': 'Mining and quarrying'},
...     {'name': 'C', 'desc': 'Manufacturing'},
...     {'name': 'D', 'desc': 'Electricity, gas, steam and air conditioning supply'}
... ])
class smif.metadata.coordinates.Coordinates(name, elements)[source]

Bases: object

Coordinates provide the labels to index a dimension, along with metadata that may be useful to describe, visualise or convert between dimensions.

Coordinate element names are used to label each position along a finite dimension.

A dict mapping dimension name to list of coordinate elements can be passed to a Spec (or xarray.DataArray) as coords.

name

Dimension name

Type:

str

dim

Alias for dimension name

Type:

str

ids

List of labels

Type:

list

elements

List of labels with metadata

Type:

list[dict]

Parameters:

  • name (str) – Name to identify the dimension that these coordinates index

  • elements (list) – List of simple data types (used to identify elements), or a list of dicts with ‘name’ key and other metadata

Raises:

  • ValueError – If the list of elements is empty, or infinite

  • KeyError – If the elements are not a list of simple data types or a list of dicts with a ‘name’ key

property dim

Dim (dimension) is an alias for Coordinates.name

property elements

Elements are a list of dicts with at least a ‘name’ key

Coordinate elements should not be changed.

property ids

Element ids is a list of coordinate identifiers

property names

Names is an alias for Coordinates.ids

smif.metadata.spec module

Data is typically multi-dimensional. Spec is used to describe each dataset which is supplied to - or output from - each Model in a CompositeModel

class smif.metadata.spec.Spec(name=None, dims=None, coords=None, dtype=None, abs_range=None, exp_range=None, unit=None, description=None)[source]

Bases: object

N-dimensional metadata.

Spec labels each dimension with coordinates and enforces data type, units and absolute and expected ranges.

The API here is modelled on xarray.DataArray: dtype and shape describe a numpy.ndarray; dims and coords follow the xarray conventions for labelled axes; and unit, abs_range and exp_range are introduced as supplementary metadata to help validate connections between models.

name

The name of the data that this spec describes

Type:

str

description

A human-friendly description

Type:

str

dtype

Data type for data values

Type:

str

abs_range

Absolute range of data values

Type:

tuple

exp_range

Expected range of data values

Type:

tuple

shape

Tuple of dimension sizes

Type:

tuple[int]

ndim

Number of dimensions

Type:

int

dims

Dimension names

Type:

list[str]

coords

Dimension coordinate labels

Type:

list[Coordinates]

unit

Units of data values

Type:

str

Parameters:

  • name (str, optional) – Name to identifiy the variable described (typically an input, output or parameter)

  • description (str, optional) – Short description

  • dims (list[str], optional) – List of dimension names, must be provided if coords is a dict

  • coords (list[Coordinates] or dict[str, list], optional) – A list of :class`Coordinates` or a dict mapping each dimension name to a list of names which label that dimension.

  • dtype (str) – String suitable for contructing a simple numpy.dtype

  • abs_range (tuple, optional) – (min, max) absolute range for numeric values - can be used to raise errors

  • exp_range (tuple, optional) – (min, max) expected range for numeric values - can be used to raise warnings

  • unit (str, optional) – Unit to be used for data values

property abs_range

The absolute range of data values that this spec describes.

as_dict()[source]

Serialise to dict representation

property coords

Coordinate labels for each dimension.

property description

A human-friendly description

dim_coords(dim: str)[source]

Coordinates for a given dimension

dim_elements(dim: str)[source]

Elements of each coordinate in a given dimension

dim_names(dim: str)[source]

Names of each coordinate in a given dimension

property dims

Names for each dimension

property dtype

The dtype of the data that this spec describes.

property exp_range

The expected range of data values that this spec describes.

classmethod from_dict(data_provided)[source]

Create a Spec from a dict representation

property name

The name of the data that this spec describes.

property ndim

The number of dimensions of the data that this spec describes.

property shape

Tuple of dimension sizes. The shape of the data that this spec describes.

property unit

The unit for all data points.

smif.metadata.timestep module

smif runs models over a series of planning timesteps.

RelativeTimestep is used to specify one timestep relative to another in the context of the set of planning timesteps.

For example, if a model needs to know its own outputs from a previous year, we can specify the self-dependency using a relative timestep.

class smif.metadata.timestep.RelativeTimestep(*values)[source]

Bases: Enum

Specify current, previous or base year timestep

ALL = 'ALL'
BASE = 'BASE'
CURRENT = 'CURRENT'
PREVIOUS = 'PREVIOUS'
classmethod from_name(name)[source]
resolve_relative_to(timestep: int, timesteps: List[int]) → None | int[source]

Resolve a relative timestep with respect to a given timestep and sequence of timesteps.

Parameters:
smif.metadata.timestep.element_before(element: int, list_: List[int]) → int[source]

Return the element before a given element in a list, or None if the given element is first or not in the list.