earthkit.hydro.move.array

Module contents

earthkit.hydro.move.array.downstream(river_network, field, node_weights=None, edge_weights=None, metric='sum', return_type=None)

Moves a field downstream.

Computes a one-step neighbor accumulation (local aggregation) moving downstream only.

The accumulation is defined as:

\begin{align*} x'_i &= w'_i \cdot x_i \\ n_j &= \bigoplus_{i \in \mathrm{Up}(j)} w_{ij} \cdot x'_i \end{align*}

where:

• \(x_i\) is the input value at node \(i\) (e.g., rainfall),

• \(w'_i\) is the node weight (e.g., pixel area),

• \(w_{ij}\) is the edge weight from node \(i\) to node \(j\) (e.g. discharge partitioning ratio),

• \(\mathrm{Up}(j)\) is the set of upstream nodes flowing into node \(j\),

• \(\bigoplus\) is the aggregation function (e.g. a summation).

• \(n_j\) is the weighted aggregated value at node \(j\).

Sources are given a value of 0.

Parameters:

• river_network (RiverNetwork) – A river network object.

• field (array-like) – An array containing field values defined on river network nodes or gridcells.

• node_weights (array-like, optional) – Array of weights for each river network node or gridcell. Default is None (unweighted).

• edge_weights (array-like, optional) – Array of weights for each edge. Default is None (unweighted).

• metric (str, optional) – Aggregation function to apply. Options are ‘var’, ‘std’, ‘mean’, ‘sum’, ‘min’ and ‘max’. Default is ‘sum’.

• return_type (str, optional) – Either “masked”, “gridded” or None. If None (default), uses river_network.return_type.

Returns:

Array of values after movement down the river network for every river network node or gridcell, depending on return_type.

Return type:

array-like

earthkit.hydro.move.array.upstream(river_network, field, node_weights=None, edge_weights=None, metric='sum', return_type=None)

Moves a field upstream.

Computes a one-step neighbor accumulation (local aggregation) moving upstream only.

The accumulation is defined as:

\begin{align*} x'_i &= w'_i \cdot x_i \\ n_j &= \bigoplus_{i \in \mathrm{Down}(j)} w_{ij} \cdot x'_i \end{align*}

where:

• \(x_i\) is the input value at node \(i\) (e.g., rainfall),

• \(w'_i\) is the node weight (e.g., pixel area),

• \(w_{ij}\) is the edge weight from node \(i\) to node \(j\) (e.g. discharge partitioning ratio),

• \(\mathrm{Down}(j)\) is the set of downstream nodes flowing out of node \(j\),

• \(\bigoplus\) is the aggregation function (e.g. a summation).

• \(n_j\) is the weighted aggregated value at node \(j\).

Sinks are given a value of 0.

Parameters:

• river_network (RiverNetwork) – A river network object.

• field (array-like) – An array containing field values defined on river network nodes or gridcells.

• node_weights (array-like, optional) – Array of weights for each river network node or gridcell. Default is None (unweighted).

• edge_weights (array-like, optional) – Array of weights for each edge. Default is None (unweighted).

• metric (str, optional) – Aggregation function to apply. Options are ‘var’, ‘std’, ‘mean’, ‘sum’, ‘min’ and ‘max’. Default is ‘sum’.

• return_type (str, optional) – Either “masked”, “gridded” or None. If None (default), uses river_network.return_type.

Returns:

Array of values after movement up the river network for every river network node or gridcell, depending on return_type.

Return type:

array-like