class Metric

Metric

The umami.Metric class calculates metrics on a Landlab model grid.

class Metric(grid, flow_accumulator_kwds=None, chi_finder_kwds=None, metrics=None)

Create a Metric class based on a Landlab model grid.

__init__(grid, flow_accumulator_kwds=None, chi_finder_kwds=None, metrics=None)

Parameters

• grid (Landlab model grid) –

• flow_accumulator_kwds (dict) – Parameters to pass to the Landlab FlowAccumulator to specify flow direction and accumulation.

• chi_finder_kwds (dict) – Parameters to pass to the Landlab ChiFinder to specify optional arguments. `

• metrics (dict) – A dictionary of desired metrics to calculate. See examples for required format.

Examples

>>> from io import StringIO
>>> from landlab import RasterModelGrid
>>> from umami import Metric
>>> grid = RasterModelGrid((10, 10))
>>> z = grid.add_zeros("node", "topographic__elevation")
>>> z += grid.x_of_node + grid.y_of_node
>>> file_like=StringIO('''
... me:
...     _func: aggregate
...     method: mean
...     field: topographic__elevation
... ep10:
...     _func: aggregate
...     method: percentile
...     field: topographic__elevation
...     q: 10
... oid1_mean:
...     _func: watershed_aggregation
...     field: topographic__elevation
...     method: mean
...     outlet_id: 1
... sn1:
...     _func: count_equal
...     field: drainage_area
...     value: 1
... ''')
>>> metric = Metric(grid)
>>> metric.add_from_file(file_like)
>>> metric.names
['me', 'ep10', 'oid1_mean', 'sn1']
>>> metric.calculate()
>>> metric.value('me')
9.0
>>> metric.values
[9.0, 5.0, 5.0, 8]

add_from_dict(params)

Add metrics to an umami.Metric from a dictionary.

Adding metrics through this method does not overwrite already existing metrics. New metrics are appended to the existing metric list.

Parameters

params (dict or OrderedDict) – Keys are metric names and values are a dictionary describing the creation of the metric. It will be convereted to an OrderedDict before metrics are added so as to preserve metric order.

add_from_file(file)

Add metrics to an umami.Metric from a file.

Parameters

file_like (file path or StringIO) – File will be parsed by yaml.safe_load and converted to an OrderedDict.

calculate()

Calculate metric values.

Calculated metric values are stored in the attribute Metric.values.

classmethod from_dict(params)

Create an umami Metric from a dictionary.

Parameters

params (dict or OrderedDict) – This dict must contain a key grid, the values of which will be passed to the Landlab function create_grid to create the model grid. It will be convereted to an OrderedDict before metrics are added so as to preserve metric order.

Examples

>>> from io import StringIO
>>> from umami import Metric
>>> params = {
...     "grid": {
...         "RasterModelGrid": [
...             [10, 10],
...             {
...                 "fields": {
...                     "node": {
...                         "topographic__elevation": {
...                             "plane": [
...                                 {"point": [0, 0, 0]},
...                                 {"normal": [-1, -1, 1]},
...                             ]
...                         }
...                     }
...                 }
...             },
...         ]
...     },
...     "metrics": {
...         "me": {
...             "_func": "aggregate",
...             "method": "mean",
...             "field": "topographic__elevation",
...         },
...         "ep10": {
...             "_func": "aggregate",
...             "method": "percentile",
...             "field": "topographic__elevation",
...             "q": 10,
...         },
...         "oid1_mean": {
...             "_func": "watershed_aggregation",
...             "field": "topographic__elevation",
...             "method": "mean",
...             "outlet_id": 1,
...         },
...         "sn1": {
...             "_func": "count_equal",
...             "field": "drainage_area",
...             "value": 1,
...         },
...     },
... }
>>> metric = Metric.from_dict(params)
>>> metric.names
['me', 'ep10', 'oid1_mean', 'sn1']
>>> metric.calculate()
>>> metric.value('me')
9.0
>>> metric.values
[9.0, 5.0, 5.0, 8]

classmethod from_file(file_like)

Create an umami Metric from a file-like object.

Parameters

file_like (file path or StringIO) – File will be parsed by yaml.safe_load and converted to an OrderedDict.

Returns

Return type

umami.Metric

Examples

>>> from io import StringIO
>>> from umami import Metric
>>> file_like=StringIO('''
... grid:
...     RasterModelGrid:
...         - [10, 10]
...         - fields:
...               node:
...                   topographic__elevation:
...                       plane:
...                           - point: [0, 0, 0]
...                           - normal: [-1, -1, 1]
... metrics:
...     me:
...         _func: aggregate
...         method: mean
...         field: topographic__elevation
...     ep10:
...         _func: aggregate
...         method: percentile
...         field: topographic__elevation
...         q: 10
...     oid1_mean:
...         _func: watershed_aggregation
...         field: topographic__elevation
...         method: mean
...         outlet_id: 1
...     sn1:
...         _func: count_equal
...         field: drainage_area
...         value: 1
... ''')
>>> metric = Metric.from_file(file_like)
>>> metric.names
['me', 'ep10', 'oid1_mean', 'sn1']
>>> metric.calculate()
>>> metric.value('me')
9.0
>>> metric.values
[9.0, 5.0, 5.0, 8]

property names

Names of metrics in metric order.

value(name)

Get a specific metric value.

Parameters

name (str) – Name of desired metric.

property values

Metric values in metric order.

write_metrics_to_file(path, style, decimals=3)

Write metrics to a file.

Parameters

• path –

• style (str) – yaml, dakota

• decimals (int) – Number of decimals to round output to.

Examples

>>> from io import StringIO
>>> from landlab import RasterModelGrid
>>> from umami import Metric
>>> grid = RasterModelGrid((10, 10))
>>> z = grid.add_zeros("node", "topographic__elevation")
>>> z += grid.x_of_node + grid.y_of_node
>>> file_like=StringIO('''
... me:
...     _func: aggregate
...     method: mean
...     field: topographic__elevation
... ep10:
...     _func: aggregate
...     method: percentile
...     field: topographic__elevation
...     q: 10
... oid1_mean:
...     _func: watershed_aggregation
...     field: topographic__elevation
...     method: mean
...     outlet_id: 1
... sn1:
...     _func: count_equal
...     field: drainage_area
...     value: 1
... ''')

First we ouput in dakota style, in which each metric is listed on its own line with its name as a comment.

>>> metric = Metric(grid)
>>> metric.add_from_file(file_like)
>>> metric.calculate()
>>> out = StringIO()
>>> metric.write_metrics_to_file(out, style="dakota")
>>> file_contents = out.getvalue().splitlines()
>>> for line in file_contents:
...     print(line.strip())
9.0 me
5.0 ep10
5.0 oid1_mean
8 sn1

Next we output in yaml style, in which each metric is serialized in YAML format.

>>> out = StringIO()
>>> metric.write_metrics_to_file(out, style="yaml")
>>> file_contents = out.getvalue().splitlines()
>>> for line in file_contents:
...     print(line.strip())
me: 9.0
ep10: 5.0
oid1_mean: 5.0
sn1: 8