unifhy.BritishNationalGrid.route

BritishNationalGrid.route(values_to_route)

Move the given values from their current location in the Grid to their downstream/downslope location according to the flow_direction property of Grid.

Parameters

values_to_route: numpy.ndarray

The values to route following the flow direction, e.g. how river discharge to route. The shape of this array must be the same as of the grid.

Returns

values_routed: numpy.ndarray

The values routed following the flow direction, e.g. how much river discharge is coming into each grid element from their upstream grid elements. The shape of this array is the same as of the grid.

values_out: numpy.ndarray

The values that routed following the flow direction would have left the domain (a value is considered to leave the domain if it is directed towards beyond the bounds of of the domain, or towards a masked location within the domain, if the flow_direction is masked), e.g. how much river discharge has not been routed towards the downstream grid element because this one is not defined (i.e. outside the grid) or masked (i.e. outside the drainage area or into the sea). The shape of this array is the same as of the grid.

Examples

Warning

Given that Y and X Grid coordinates are ordered increasingly northwards and eastwards, respectively, and given that a 2D numpy.ndarray origin (i.e. [0, 0]) is in the upper-left corner when visualising the content of an array (i.e. using print), routing a value northwards will result in visualising it “moving down” the array (and not up), and routing a value eastwards will result in visualising it “moving right”.

Using grid routing functionality with basic domain and flow direction:

>>> import numpy
>>> grid = LatLonGrid.from_extent_and_resolution(
...     latitude_extent=(51, 55),
...     latitude_resolution=1,
...     longitude_extent=(-2, 1),
...     longitude_resolution=1
... )
>>> values = numpy.arange(12).reshape(4, 3) + 1
>>> print(values)
[[ 1  2  3]
 [ 4  5  6]
 [ 7  8  9]
 [10 11 12]]
>>> directions = grid.to_field()
>>> directions.set_data(numpy.array([['NE', 'N', 'E'],
...                                  ['SE', 'E', 'S'],
...                                  ['N', 'N', 'W'],
...                                  ['SW', 'E', 'NW']]))
>>> grid.flow_direction = directions
>>> moved, out = grid.route(values)
>>> print(moved)
[[ 0  4  6]
 [ 0  3  5]
 [ 0  9  0]
 [ 7  8 11]]
>>> print(out)
[[ 0  0  3]
 [ 0  0  0]
 [ 0  0  0]
 [10  0 12]]

Using grid routing functionality with masked flow direction:

>>> directions.set_data(
...     numpy.ma.array(
...         [['NE', 'N', 'E'],
...          ['SE', 'E', 'S'],
...          ['N', 'N', 'W'],
...          ['SW', 'E', 'NW']],
...         mask=[[1, 0, 0],
...               [1, 0, 0],
...               [1, 1, 0],
...               [0, 0, 0]]
...     )
... )
>>> grid.flow_direction = directions
>>> moved, out = grid.route(values)
>>> print(moved)
[[-- 0 6]
 [-- 2 5]
 [-- -- 0]
 [0 0 11]]
>>> print(out)
[[-- 0 3]
 [-- 0 0]
 [-- -- 9]
 [10 0 12]]

Using grid routing functionality with a wrap-around domain:

>>> grid = LatLonGrid.from_extent_and_resolution(
...     latitude_extent=(-90, 90),
...     latitude_resolution=45,
...     longitude_extent=(-180, 180),
...     longitude_resolution=120
... )
>>> values = numpy.arange(12).reshape(4, 3) + 1
>>> print(values)
[[ 1  2  3]
 [ 4  5  6]
 [ 7  8  9]
 [10 11 12]]
>>> directions = grid.to_field()
>>> directions.set_data(numpy.array([['NE', 'N', 'E'],
...                                  ['SE', 'E', 'S'],
...                                  ['N', 'N', 'W'],
...                                  ['SW', 'E', 'NW']]))
>>> grid.flow_direction = directions
>>> moved, out = grid.route(values)
>>> print(moved)
[[ 3 16  6]
 [ 0  3  5]
 [ 0  9 10]
 [ 7  8 11]]
>>> print(out)
[[0 0 0]
 [0 0 0]
 [0 0 0]
 [0 0 0]]

Using grid routing functionality on a whole cartesian domain:

>>> grid = BritishNationalGrid.from_extent_and_resolution(
...     projection_y_coordinate_extent=(0, 1300000),
...     projection_y_coordinate_resolution=325000,
...     projection_x_coordinate_extent=(0, 700000),
...     projection_x_coordinate_resolution=700000/3
... )
>>> values = numpy.arange(12).reshape(4, 3) + 1
>>> directions = grid.to_field()
>>> directions.set_data(numpy.array([['NE', 'N', 'E'],
...                                  ['SE', 'E', 'S'],
...                                  ['N', 'N', 'W'],
...                                  ['SW', 'E', 'NW']]))
>>> grid.flow_direction = directions
>>> moved, out = grid.route(values)
>>> print(moved)
[[ 0  4  6]
 [ 0  3  5]
 [ 0  9  0]
 [ 7  8 11]]
>>> print(out)
[[ 0  0  3]
 [ 0  0  0]
 [ 0  0  0]
 [10  0 12]]