Hierarchy#

Navigate the hierarchical structure of the BNG index system.

The British National Grid (BNG) is structured using a hierarchical system of grid squares at various resolutions. At its highest level, the grid divides GB into 100 km by 100 km squares, each identified by a two-letter code. Successive levels of resolution further subdivide the grid squares into finer detail, down to individual 1-meter squares. This module allows for the traversal of this hierarchy by providing methods to return the parent and children of BNGReference objects at specified resolutions.

Parent and child definitions:

  • Parent: The parent of a BNGReference object is the grid square at the next higher (coarser) resolution level that contains the current reference. For example, the parent of a 1km grid square reference would be the 5km grid square that contains it.

  • Children: The children of a BNGReference object are the grid squares at the next lower (finer) resolution level that are contained within the current reference. For example, the children of a 10km grid square reference would be the 5km grid squares that it contains.

Notes

While parent and child derivation defaults to the next higher and lower resolution, any supported resolution in the hierarchy can be specified.

Supported Resolutions:

  • The module supports the ‘standard’ and ‘intermediate’ quadtree resolutions, including 100km, 50km, 10km, 5km, 1km, 500m, 100m, 50m, 10m, 5m and 1m.

  • These resolutions passed to hierarchy functions are validated and normalised using the resolution mapping defined in the Resolution module.

osbng.hierarchy.bng_to_children(bng_ref: BNGReference, *, resolution: int | str | None = None) → list[BNGReference][source]#

Returns a list of child BNGReference objects of a BNGReference.

By default, the children of the BNGReference object is defined as the BNGReference objects in the next resolution down from the input BNGReference resolution . For example, 100km -> 50km.

Notes

Any valid resolution can be provided as the child resolution, provided it is less than the resolution of the input BNGReference .

Parameters:

bng_ref (BNGReference) – The BNGReference object to derive children from.

Keyword Arguments:

resolution (int | str | None, optional) – The resolution of the children BNGReference objects expressed either as a metre-based integer or as a string label. Defaults to None.

Returns:

A list of BNGReference objects that are children of the input BNGReference object .

Return type:

list[BNGReference]

Raises:

Examples

>>> bng_to_children(BNGReference("SU"))
[BNGReference(bng_ref_formatted=SU SW, resolution_label=50km),
BNGReference(bng_ref_formatted=SU SE, resolution_label=50km),
BNGReference(bng_ref_formatted=SU NW, resolution_label=50km),
BNGReference(bng_ref_formatted=SU NE, resolution_label=50km)]
>>> bng_to_children(BNGReference("SU36"))
[BNGReference(bng_ref_formatted=SU 3 6 SW, resolution_label=5km),
BNGReference(bng_ref_formatted=SU 3 6 SE, resolution_label=5km),
BNGReference(bng_ref_formatted=SU 3 6 NW, resolution_label=5km),
BNGReference(bng_ref_formatted=SU 3 6 NE, resolution_label=5km)]

See also

osbng.hierarchy.bng_to_parent(bng_ref: BNGReference, *, resolution: int | str | None = None) → BNGReference[source]#

Returns the BNGReference`that is the parent of a ``BNGReference`.

By default, the parent of the BNGReference object is defined as the BNGReference in the next BNG resolution up from the input BNGReference resolution. For example , 50km -> 100km.

Notes

Any valid resolution can be provided as the parent resolution, provided it is greater than the resolution of the input BNGReference.

Parameters:

bng_ref (BNGReference) – The BNGReference object to derive parent from.

Keyword Arguments:

resolution (int | str | None, optional) – The resolution of the parent BNGReference objects expressed either as a metre-based integer or as a string label. Defaults to None.

Returns:

A BNGReference object that is the parent of the input BNGReference object.

Return type:

BNGReference

Raises:

Examples

>>> bng_to_parent(BNGReference("SU 3 6 SW"))
BNGReference(bng_ref_formatted=SU 3 6, resolution_label=10km)
>>> bng_to_parent(BNGReference("SU 342 567"))
BNGReference(bng_ref_formatted=SU 34 56 NW, resolution_label=500m)
>>> bng_to_parent(BNGReference("SU 342 567"), resolution=10000)
BNGReference(bng_ref_formatted=SU 3 5, resolution_label=10km)

See also