unifhy.LatLonGrid.flow_direction

LatLonGrid.flow_direction

The information necessary to move any variable laterally (i.e. along Y and/or X) to its nearest receiving neighbour in the Grid given as a cf.Field and returned as a processed numpy.ndarray.

Parameters

directions: cf.Field

The field containing flow direction. The supported kinds of directional information are listed in the table below. The shape of the array must be the same as the Grid, except for the relative kind, where an additional trailing axis of size two holding the pairs must be present.

kind	information
cardinal	The field data contains the direction using str for the eight following cardinal points: ‘N’ for North, ‘NE’ for North-East, ‘E’ for East, ‘SE’ for South East, ‘S’ for South, ‘SW’ for South West, ‘W’ for West, ‘NW’ for North West.
digits	The field data contains the direction using int for the eight following cardinal points: 1 for North, 2 for North-East, 3 for East, 4 for South East, 5 for South, 6 for South West, 7 for West, 8 for North West.
relative	The field data contains the direction using pairs of int (Y, X) for the eight following cardinal points: (1, 0) for North, (1, 1) for North-East, (0, 1) for East, (-1, 1) for South East, (-1, 0) for South, (-1, -1) for South West, (0, -1) for West, (1, -1) for North West.

Returns

numpy.ndarray

The information to route any variable to its destination in the Grid in the relative format (see table above). If not set, return None.

Examples

Assigning flow direction to grid using cardinal values:

>>> import numpy
>>> grid = LatLonGrid.from_extent_and_resolution(
...     latitude_extent=(51, 55),
...     latitude_resolution=1,
...     longitude_extent=(-2, 1),
...     longitude_resolution=1
... )
>>> print(grid.flow_direction)
None
>>> directions = grid.to_field()
>>> directions.set_data(numpy.array([['SE', 'S', 'E'],
...                                  ['NE', 'E', 'N'],
...                                  ['S', 'S', 'W'],
...                                  ['NW', 'E', 'SW']]))
>>> grid.flow_direction = directions
>>> print(grid.flow_direction)
[[[-1  1]
  [-1  0]
  [ 0  1]]

 [[ 1  1]
  [ 0  1]
  [ 1  0]]

 [[-1  0]
  [-1  0]
  [ 0 -1]]

 [[ 1 -1]
  [ 0  1]
  [-1 -1]]]
>>> print(grid)
LatLonGrid(
    shape {Y, X}: (4, 3)
    Y, latitude (4,): [51.5, ..., 54.5] degrees_north
    X, longitude (3,): [-1.5, -0.5, 0.5] degrees_east
    Y_bounds (4, 2): [[51.0, ..., 55.0]] degrees_north
    X_bounds (3, 2): [[-2.0, ..., 1.0]] degrees_east
    flow_direction (4, 3, 2): [[[-1, ..., -1]]]
)

Assigning flow direction to grid using digits:

>>> flow_direction = grid.flow_direction
>>> directions.set_data(numpy.array([[4, 5, 3],
...                                  [2, 3, 1],
...                                  [5, 5, 7],
...                                  [8, 3, 6]]))
>>> grid.flow_direction = directions
>>> numpy.array_equal(flow_direction, grid.flow_direction)
True

Assigning flow direction to grid using relative values:

>>> import cf
>>> ax = directions.set_construct(cf.DomainAxis(2))
>>> dim = cf.DimensionCoordinate(
...     properties={'name': 'relative flow direction along y and x components',
...                 'units': '1'},
...     data=cf.Data(['y_rel', 'x_rel'])
... )
>>> dim = directions.set_construct(dim, axes=ax)
>>> directions.set_data(
...     numpy.array([[[-1, 1], [-1, 0], [0, 1]],
...                  [[1, 1], [0, 1], [1, 0]],
...                  [[-1, 0], [-1, 0], [0, -1]],
...                  [[1, -1], [0, 1], [-1, -1]]]
...     ),
...     axes=('Y', 'X', dim)
... )
>>> grid.flow_direction = directions
>>> numpy.array_equal(flow_direction, grid.flow_direction)
True

Assigning masked flow direction to grid:

>>> directions = grid.to_field()
>>> directions.set_data(
...     numpy.ma.array(
...         [['SE', 'S', 'E'],
...          ['NE', 'E', 'N'],
...          ['S', 'S', 'W'],
...          ['NW', 'E', 'SW']],
...         mask=[[1, 0, 0],
...               [1, 0, 0],
...               [1, 1, 0],
...               [0, 0, 0]]
...     )
... )
>>> grid.flow_direction = directions
>>> print(grid.flow_direction)
[[[-- --]
  [-1 0]
  [0 1]]

 [[-- --]
  [0 1]
  [1 0]]

 [[-- --]
  [-- --]
  [0 -1]]

 [[1 -1]
  [0 1]
  [-1 -1]]]