mask_aggregation: aggregate masked field values

mask_aggregation(grid, field, mask, method, **kwds)[source]

Aggregate a field value masked by a boolean field.

mask_aggregation calculates aggregate values on a field masked by a second, boolean field. It supports all methods in the numpy namespace that reduce an array to a scalar.

Parameters

  • grid (Landlab model grid) –

  • field (str) – An at-node Landlab grid field that is present on the model grid.

  • mask (str) – An at-node Landlab grid field of boolean type. Aggregation is done where the masked value is True.

  • method (str) – The name of a numpy namespace method.

  • **kwds – Any additional keyword arguments needed by the method.

Returns

out – The aggregate value.

Return type

float

Examples

First an example that only uses the mask_aggregation function.

>>> from landlab import RasterModelGrid
>>> from landlab.components import FlowAccumulator
>>> from umami.calculations import mask_aggregation
>>> grid = RasterModelGrid((10, 10))
>>> z = grid.add_zeros("node", "topographic__elevation")
>>> z += grid.x_of_node + grid.y_of_node

Create a boolean mask and add it to the grid.

>>> mask = grid.add_field("mask", z > 11, at="node")

mask_aggregation supports all functions in the numpy namespace. Here we show mean and percentile. The latter of which takes an additional argument, q.

>>> mask_aggregation(grid, "topographic__elevation", "mask",  "mean")
14.0
>>> mask_aggregation(
... grid,
... "topographic__elevation",
... "mask",
... "percentile",
... q=10)
12.0

Next, the same calculations are shown as part of an umami Metric.

>>> from io import StringIO
>>> from umami import Metric
>>> file_like=StringIO('''
... mask_mean:
...     _func: mask_aggregation
...     mask: mask
...     method: mean
...     field: topographic__elevation
... mask_10thptile:
...     _func: mask_aggregation
...     mask: mask
...     method: percentile
...     field: topographic__elevation
...     q: 10
... ''')
>>> metric = Metric(grid)
>>> metric.add_from_file(file_like)
>>> metric.names
['mask_mean', 'mask_10thptile']
>>> metric.calculate()
>>> metric.values
[14.0, 12.0]