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 ofGrid
.- 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.
- values_to_route:
- 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.
- values_routed:
Examples
Warning
Given that Y and X
Grid
coordinates are ordered increasingly northwards and eastwards, respectively, and given that a 2Dnumpy.ndarray
origin (i.e. [0, 0]) is in the upper-left corner when visualising the content of an array (i.e. usingprint
), 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]]