API documentation for the axes module

The axes module handles the validation of data being loaded into the core data storage of the Virtual Ecosystem simulation. The main functionality in this module is ensuring that any loaded data is congruent with the core axes of the simulation and the configuration of a given simulation.

The AxisValidator class

The AxisValidator abstract base class provides an extensible framework for validating data arrays. Each subclass of the base class defines a particular core axis along with the name or names of dimensions in the input array that are expected to map onto that axis. So, for example, a validator can support the spatial axis using the x and y dimensions. Each individual subclass provides bespoke methods to test whether that validator can be applied to an input data array and then a validation routine to apply when it can.

When new AxisValidator subclasses are defined, they are automatically added to the AXIS_VALIDATORS registry. This maintains a list of the validators defined for each core axis.

Note that the set of validators defined for a specific core axis should be mutually exclusive: only one should be applicable to any given dataset being tested on that axis.

DataArray validation

The validate_dataarray() function takes an input Data Array and applies validation where applicable across all the core axes. The function returns the validated input (possibly altered to align with the core axes) along with a dictionary using the set of core axes as names: the value associated with each axis name is the name of the AxisValidator applied or None if the input did not match a validator on that axis.

Core axes

The ‘spatial’ axis

The AxisValidator subclasses defined for the ‘spatial’ axis standardise the spatial structure of the input data to use a single cell_id spatial axis, which maps data onto the cell IDs used for indexing in the Grid instance for the simulation. x

Data:

AXIS_VALIDATORS

A registry for different axis validators subclasses

Classes:

AxisValidator()	The AxisValidator abstract base class.
Spat_CellId_Coord_Any()	Validate cell_id coordinates on the spatial core axis.
Spat_CellId_Dim_Any()	Validate cell_id dimension on the spatial core axis.
Spat_XY_Coord_Square()	Validate x and y coordinates on the spatial core axis for a square grid.
Spat_XY_Dim_Square()	Validate x and y dimensions on the spatial core axis on a square grid.

Functions:

validate_dataarray(value, grid, **kwargs)

Validate a DataArray across the core axes.

virtual_ecosystem.core.axes.AXIS_VALIDATORS: dict[str, list[type[AxisValidator]]] = {'spatial': [<class 'virtual_ecosystem.core.axes.Spat_CellId_Coord_Any'>, <class 'virtual_ecosystem.core.axes.Spat_CellId_Dim_Any'>, <class 'virtual_ecosystem.core.axes.Spat_XY_Coord_Square'>, <class 'virtual_ecosystem.core.axes.Spat_XY_Dim_Square'>]}

A registry for different axis validators subclasses

This registry contains a dictionary of lists of AxisValidator subclasses. Each list contains all of AxisValidator subclasses that apply to a particular core axis, and the core axis names are used as the key to these lists.

Users defined AxisValidator subclasses will be automatically added to this registry by the __subclass_init__ method.

class virtual_ecosystem.core.axes.AxisValidator

The AxisValidator abstract base class.

This abstract base class provides the structure for axis validators. These are used to check that a DataArray to be added to a Data instance is congruent with the configuration of a Virtual Ecosystem simulation. The base class provides abstract methods that provide the following functionality:

• can_validate(): test that a given AxisValidator subclass can be applied to the inputs.

• run_validation(): run appropriate validation and standardisation on the input DataArray.

The can_validate() method should be used first to check that a particular DataArray can be validated, and then the run_validation() method can be used to validate that input if appropriate.

Methods:

__init_subclass__()	Adds new subclasses to the AxisValidator registry.
can_validate(value, grid, **kwargs)	Check if an AxisValidator subclass applies to inputs.
run_validation(value, grid, **kwargs)	Validate the input DataArray.

Attributes:

core_axis	Class attribute giving the name of the core axis for an AxisValidator.
dim_names	Class attribute giving the dimension names for an AxisValidator.

classmethod __init_subclass__() → None

Adds new subclasses to the AxisValidator registry.

When new subclasses are created this method automatically extends the AXIS_VALIDATORS registry. AxisValidators are arranged in the registry dictionary as lists keyed under core axis names, and the core axis name for a given subclass is set in the subclass core_axis class attribute.

Raises:

ValueError – if the subclass attributes are invalid.

abstract can_validate(value: DataArray, grid: Grid, **kwargs: Any) → bool

Check if an AxisValidator subclass applies to inputs.

A given AxisValidator subclass must provide a run_validation method that defines data validation that should be applied to the inputs. However, the validation for a particular subclass will only apply to inputs with particular features, such as an array with a given dimension name or a set grid type.

In a subclass, the implementation of this method should check whether the validation implemented in run_validation can be applied to the inputs.

Parameters:

• value – An input DataArray to check

• grid – A Grid object giving the spatial configuration of the simulation.

• kwargs – Other configuration details to be used.

Returns:

A boolean showing if the run_validation method of the subclass can be applied to the inputs.

core_axis: str

Class attribute giving the name of the core axis for an AxisValidator.

dim_names: set[str]

Class attribute giving the dimension names for an AxisValidator.

abstract run_validation(value: DataArray, grid: Grid, **kwargs: Any) → DataArray

Validate the input DataArray.

The implementation for an AxisValidator subclass should define a set of checks on the inputs that are used to validate that the input DataArray value is congruent with the simulation configuration. The method can also perform standardisation and return a modified input value that has been aligned to the simulation structure.

Parameters:

• value – An input DataArray to check

• grid – A Grid object giving the spatial configuration of the simulation.

• kwargs – Other configuration details to be used.

Returns:

A DataArray that passes validation, possibly modified to align with internal data structures.

class virtual_ecosystem.core.axes.Spat_CellId_Coord_Any

Validate cell_id coordinates on the spatial core axis.

Applies to:

An input DataArray that provides coordinate values along a cell_id dimension is assumed to map data onto the cells values defined in the Grid configured for the simulation. The coordinate values are tested to check they provide a one-to-one map onto the cell_id values defined for each cell in the Grid. Because cell_id values are defined for cells in all grid types, this validator does not require a particular grid geometry.

Methods:

can_validate(value, grid, **kwargs)	Check the validator applies to the inputs.
run_validation(value, grid, **kwargs)	Run validation on the inputs.

Attributes:

core_axis	Class attribute giving the name of the core axis for an AxisValidator.
dim_names	Class attribute giving the dimension names for an AxisValidator.

can_validate(value: DataArray, grid: Grid, **kwargs: Any) → bool

Check the validator applies to the inputs.

Parameters:

• value – An input DataArray to check

• grid – A Grid object giving the spatial configuration of the simulation.

• kwargs – Other configuration details to be used.

Returns:

A boolean showing if this subclass can be applied to the inputs.

core_axis: str = 'spatial'

Class attribute giving the name of the core axis for an AxisValidator.

dim_names: set[str] = {'cell_id'}

Class attribute giving the dimension names for an AxisValidator.

run_validation(value: DataArray, grid: Grid, **kwargs: Any) → DataArray

Run validation on the inputs.

Validation will fail if the cell_id coordinate values:

• are not unique, or

• do not provide a one-to-one mapping onto the set of cell_id values defined in the configured Grid object.

Parameters:

• value – An input DataArray to check

• grid – A Grid object giving the spatial configuration of the simulation.

• kwargs – Other configuration details to be used.

Raises:

ValueError – when cell_id values are not congruent with the Grid.

Returns:

A DataArray standardised to match the cell_id values in the Grid object.

class virtual_ecosystem.core.axes.Spat_CellId_Dim_Any

Validate cell_id dimension on the spatial core axis.

Applies to:

The input DataArray for this validator has a cell_id dimension but there are no cell_id values provided as coordinates along that dimension. The cell_id dimension name means that the array is assumed to provide data for the cells defined in the Grid configured for the simulation. The data are then assumed to be in the same order as the cells in the Grid. As a one-dimensional array of cells is defined for all grid configurations, this validator does not require a particular grid geometry.

Methods:

can_validate(value, grid, **kwargs)	Check the validator applies to the inputs.
run_validation(value, grid, **kwargs)	Run validation on the inputs.

Attributes:

core_axis	Class attribute giving the name of the core axis for an AxisValidator.
dim_names	Class attribute giving the dimension names for an AxisValidator.

can_validate(value: DataArray, grid: Grid, **kwargs: Any) → bool

Check the validator applies to the inputs.

Parameters:

• value – An input DataArray to check

• grid – A Grid object giving the spatial configuration of the simulation.

• kwargs – Other configuration details to be used.

Returns:

A boolean showing if this subclass can be applied to the inputs.

core_axis: str = 'spatial'

Class attribute giving the name of the core axis for an AxisValidator.

dim_names: set[str] = {'cell_id'}

Class attribute giving the dimension names for an AxisValidator.

run_validation(value: DataArray, grid: Grid, **kwargs: Any) → DataArray

Run validation on the inputs.

Validation will fail when the cell_id dimension:

• is not of exactly the same length as the list of cells defined in the configured Grid object.

Parameters:

• value – An input DataArray to check

• grid – A Grid object giving the spatial configuration of the simulation.

• kwargs – Other configuration details to be used.

Raises:

ValueError – when cell_id values are not congruent with the Grid.

Returns:

A DataArray standardised to match the cell_id values in the Grid object.

class virtual_ecosystem.core.axes.Spat_XY_Coord_Square

Validate x and y coordinates on the spatial core axis for a square grid.

Applies to:

An input DataArray that provides coordinates along x and y dimensions is assumed to map data onto the cells defined in a Grid configured for the simulation with a square cell geometry. The pairwise combinations of x and y coordinates in the data are expected to provide a one-to-one mapping onto grid cell geometries.

This validator also remaps x and y dimensions onto the internal cell_id dimension used in the grid module.

Methods:

can_validate(value, grid, **kwargs)	Check the validator applies to the inputs.
run_validation(value, grid, **kwargs)	Run validation on the inputs.

Attributes:

core_axis	Class attribute giving the name of the core axis for an AxisValidator.
dim_names	Class attribute giving the dimension names for an AxisValidator.

can_validate(value: DataArray, grid: Grid, **kwargs: Any) → bool

Check the validator applies to the inputs.

Parameters:

• value – An input DataArray to check

• grid – A Grid object giving the spatial configuration of the simulation.

• kwargs – Other configuration details to be used.

Returns:

A boolean showing if this subclass can be applied to the inputs.

core_axis: str = 'spatial'

Class attribute giving the name of the core axis for an AxisValidator.

dim_names: set[str] = {'x', 'y'}

Class attribute giving the dimension names for an AxisValidator.

run_validation(value: DataArray, grid: Grid, **kwargs: Any) → DataArray

Run validation on the inputs.

Validation will fail when the x and y coordinates:

• Fall on cell geometry boundaries: unambiguous coordinates within the geometry, such as cell centroids, should be used.

• The coordinate pairs do not provide a one-to-one mapping onto the cells: multiple coordinates map onto a single cell, there is not a coordinate pair for each cell, or some coordinate pairs do not map onto a cell.

Parameters:

• value – An input DataArray to check

• grid – A Grid object giving the spatial configuration of the simulation.

• kwargs – Other configuration details to be used.

Raises:

ValueError – when x and y values are not congruent with the Grid.

Returns:

A DataArray with the x and y dimensions remapped onto the internal cell_id dimension used in the grid module.

class virtual_ecosystem.core.axes.Spat_XY_Dim_Square

Validate x and y dimensions on the spatial core axis on a square grid.

Applies to:

An input DataArray with x and y dimensions specifies the size of the array along those dimensions but does not provide coordinates for the cells. The input is then assumed to provide an array with the same shape as a the cell grid of a Grid configured for the simulation with a square cell geometries.

This validator also remaps x and y dimensions onto the internal cell_id dimension used in the grid module.

Methods:

can_validate(value, grid, **kwargs)	Check the validator applies to the inputs.
run_validation(value, grid, **kwargs)	Run validation on the inputs.

Attributes:

core_axis	Class attribute giving the name of the core axis for an AxisValidator.
dim_names	Class attribute giving the dimension names for an AxisValidator.

can_validate(value: DataArray, grid: Grid, **kwargs: Any) → bool

Check the validator applies to the inputs.

Parameters:

• value – An input DataArray to check

• grid – A Grid object giving the spatial configuration of the simulation.

• kwargs – Other configuration details to be used.

Returns:

A boolean showing if this subclass can be applied to the inputs.

core_axis: str = 'spatial'

Class attribute giving the name of the core axis for an AxisValidator.

dim_names: set[str] = {'x', 'y'}

Class attribute giving the dimension names for an AxisValidator.

run_validation(value: DataArray, grid: Grid, **kwargs: Any) → DataArray

Run validation on the inputs.

Validation will fail when the x and y dimensions:

• do not have exactly the same shape - numbers of rows (y) and columns (x) as the configured square Grid.

Parameters:

• value – An input DataArray to check

• grid – A Grid object giving the spatial configuration of the simulation.

• kwargs – Other configuration details to be used.

Raises:

ValueError – when x and y values are not congruent with the Grid.

Returns:

A DataArray with the x and y dimensions remapped onto the internal cell_id dimension used in the grid module.

virtual_ecosystem.core.axes.validate_dataarray(value: DataArray, grid: Grid, **kwargs: Any) → tuple[DataArray, dict]

Validate a DataArray across the core axes.

The AXIS_VALIDATORS registry provides a list of AxisValidators subclasses for each core axis. This function loops over the core axes, and checks whether to apply validation for that axis to the input DataArray.

For each axis in turn, the function first checks if the dimension names of the input DataArray overlap with the set of dimension names used across the AxisValidators for that axis. If not, then the next axis is checked without altering the input array. If the dimension names do match the axis then the appropriate AxisValidator is then used to validate the input array and the validated array is passed on to the next axis for further validation.

Parameters:

• value – An input DataArray for validation

• grid – A Grid object giving the spatial configuration.

• kwargs – Further configuration details to be passed to AxisValidators

Returns:

The function returns the validated data array and a dictionary recording which AxisValidator classes were applied to each of the core axes.

Raises:

• ValueError – If the input data array uses dimension names required for an axis without matching a registered validator.

• RuntimeError – If more than one validator reports that it can validate an input.