earthkit.hydro.upstream.array¶

Module contents¶

earthkit.hydro.upstream.array.max(river_network, field, node_weights=None, edge_weights=None, return_type=None)[source]¶

Computes the weighted maximum of a field over all upstream nodes.

For each node in the river network, this function identifies all upstream nodes in the river network and accumulates their contributions downstream, weighted by both node and edge weights.

The weighted maximum is defined as:

\begin{align*} x'_i &= w'_i \cdot x_i \\ m_j &= \mathrm{max} (x'_j,~\mathrm{max}_{i \in \mathrm{Up}(j)} w_{ij} \cdot m_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\),
\(m_j\) is the weighted maximum at node \(j\).

Accumulation proceeds in topological order from the sources to the sinks.

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).
return_type (str, optional) – Either “masked”, “gridded” or None. If None (default), uses river_network.return_type.

Returns:

Array of maximum values for every river network node or gridcell, depending on return_type.

Return type:

array-like

earthkit.hydro.upstream.array.mean(river_network, field, node_weights=None, edge_weights=None, return_type=None)[source]¶

Computes the weighted mean of a field over all upstream nodes.

For each node in the river network, this function identifies all upstream nodes in the river network and accumulates their contributions downstream, weighted by both node and edge weights.

The weighted mean is defined as:

\begin{align*} x'_i &= w'_i \cdot x_i \\ n_j &= x'_j + \sum_{i \in \mathrm{Up}(j)} w_{ij} \cdot n_i \\ d_j &= w'_j + \sum_{i \in \mathrm{Up}(j)} w_{ij} \cdot d_i \\ \bar{x}_j &= \frac{n_j}{d_j} \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\),
\(n_j\) is the accumulated weighted value,
\(d_j\) is the accumulated weight (denominator),
\(\bar{x}_j\) is the weighted mean at node \(j\).

Accumulation proceeds in topological order from the sources to the sinks.

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).
return_type (str, optional) – Either “masked”, “gridded” or None. If None (default), uses river_network.return_type.

Returns:

Array of mean values for every river network node or gridcell, depending on return_type.

Return type:

array-like

earthkit.hydro.upstream.array.min(river_network, field, node_weights=None, edge_weights=None, return_type=None)[source]¶

Computes the weighted minimum of a field over all upstream nodes.

For each node in the river network, this function identifies all upstream nodes in the river network and accumulates their contributions downstream, weighted by both node and edge weights.

The weighted minimum is defined as:

\begin{align*} x'_i &= w'_i \cdot x_i \\ m_j &= \mathrm{min}(x'_j,~\mathrm{min}_{i \in \mathrm{Up}(j)} w_{ij} \cdot m_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\),
\(m_j\) is the weighted minimum at node \(j\).

Accumulation proceeds in topological order from the sources to the sinks.

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).
return_type (str, optional) – Either “masked”, “gridded” or None. If None (default), uses river_network.return_type.

Returns:

Array of minimum values for every river network node or gridcell, depending on return_type.

Return type:

array-like

earthkit.hydro.upstream.array.mode(river_network, field, node_weights=None, edge_weights=None, return_type=None)[source]¶

Computes the mode (most common value) of categorical data over all upstream nodes.

For each node in the river network, this function identifies all upstream nodes and finds the most frequent categorical value (spatial majority) among them. This is designed for categorical/integer data such as land cover classifications.

The mode is computed as:

\begin{align*} c_j^{(k)} &= \mathrm{count}(x_i = k,~i \in \{\mathrm{Up}(j) \cup \{j\}\}) \\ \mathrm{Mode}(x)_j &= \arg\max_{k} c_j^{(k)} \end{align*}

where:

\(x_i\) is the categorical value at node \(i\) (e.g., land cover class),
\(\mathrm{Up}(j)\) is the set of upstream nodes flowing into node \(j\),
\(c_j^{(k)}\) is the count of category \(k\) at node \(j\),
\(\mathrm{Mode}(x)_j\) is the most common category at node \(j\).

In case of ties, the smallest category value is returned. The computation is performed using a performant Rust implementation with parallel processing.

Parameters:

river_network (RiverNetwork) – A river network object.
field (array-like) – An array containing integer categorical values defined on river network nodes or gridcells. Values should be integers representing categories (e.g., 1=forest, 2=grassland, 3=urban).
node_weights (array-like, optional) – Not supported for mode calculation. Must be None.
edge_weights (array-like, optional) – Not supported for mode calculation. Must be None.
return_type (str, optional) – Either “masked”, “gridded” or None. If None (default), uses river_network.return_type.

Returns:

Array of mode (most common category) values for every river network node or gridcell, depending on return_type.

Return type:

array-like

Notes

Mode calculation currently only supports the numpy backend.
The Rust extension must be available for this function to work.
Node weights and edge weights are not supported for mode calculation.
Field values are converted to int64 internally.

Examples

>>> import earthkit.hydro as ekh
>>> # Compute mode of land cover categories
>>> mode_landcover = ekh.upstream.array.mode(river_network, landcover_field)

earthkit.hydro.upstream.array.percentile(river_network, field, p, node_weights=None, edge_weights=None, return_type=None)[source]¶

Computes the weighted percentile of a field over all upstream nodes.

For each node in the river network, this function identifies all upstream nodes (the contributing area) and computes the requested percentile from the field values, optionally weighted by node weights.

The weighted percentile is defined as:

\begin{align*} \mathcal{A}(j) &= \{j\} \cup \bigcup_{i \in \mathrm{Up}(j)} \mathcal{A}(i) \\ P_p(x)_j &= \mathrm{percentile}_p \bigl(\{ w'_i \cdot x_i : i \in \mathcal{A}(j) \}\bigr) \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),
\(\mathrm{Up}(j)\) is the set of immediate upstream nodes flowing into node \(j\),
\(\mathcal{A}(j)\) is the full contributing area of node \(j\) (all upstream nodes including \(j\) itself),
\(P_p(x)_j\) is the \(p\)-th percentile at node \(j\).

Parameters:

river_network (RiverNetwork) – A river network object.
field (array-like) – An array containing field values defined on river network nodes or gridcells.
p (float) – Requested percentile expressed as a fraction between 0 and 1 inclusive (e.g. 0.5 for median, 0.95 for the 95th percentile).
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). Currently unsupported.
return_type (str, optional) – Either “masked”, “gridded” or None. If None (default), uses river_network.return_type.

Returns:

Array of percentile values for every river network node or gridcell, depending on return_type.

Return type:

array-like

earthkit.hydro.upstream.array.std(river_network, field, node_weights=None, edge_weights=None, return_type=None)[source]¶

Computes the weighted standard deviation of a field over all upstream nodes.

For each node in the river network, this function identifies all upstream nodes in the river network and accumulates their contributions downstream, weighted by both node and edge weights.

The weighted standard deviation is defined as:

\begin{align*} x'_i &= w'_i \cdot x_i \\ q'_i &= w'_i \cdot x_i^2 \\ n_j &= x'_j + \sum_{i \in \mathrm{Up}(j)} w_{ij} \cdot n_i \\ q_j &= q'_j + \sum_{i \in \mathrm{Up}(j)} w_{ij} \cdot q_i \\ d_j &= w'_j + \sum_{i \in \mathrm{Up}(j)} w_{ij} \cdot d_i \\ \bar{x}_j &= \frac{n_j}{d_j} \\ \mathrm{Var}(x)_j &= \frac{q_j}{d_j} - \bar{x}_j^2 \\ \mathrm{Std}(x)_j &= \sqrt{\mathrm{Var}(x)_j} \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\),
\(n_j\) is the accumulated weighted value,
\(q_j\) is the accumulated weighted squared value,
\(d_j\) is the accumulated weight (denominator),
\(\bar{x}_j\) is the weighted average at node \(j\),
\(\mathrm{Var}(x)_j\) is the weighted variance at node \(j\).
\(\mathrm{Std}(x)_j\) is the weighted standard deviation at node \(j\).

Accumulation proceeds in topological order from the sources to the sinks. This formulation computes the population standard deviation.

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).
return_type (str, optional) – Either “masked”, “gridded” or None. If None (default), uses river_network.return_type.

Returns:

Array of standard deviation values for every river network node or gridcell, depending on return_type.

Return type:

array-like

earthkit.hydro.upstream.array.sum(river_network, field, node_weights=None, edge_weights=None, return_type=None)[source]¶

Computes the weighted sum of a field over all upstream nodes.

For each node in the river network, this function identifies all upstream nodes in the river network and accumulates their contributions downstream, weighted by both node and edge weights.

The weighted sum is defined as:

\begin{align*} x'_i &= w'_i \cdot x_i \\ n_j &= x'_j + \sum_{i \in \mathrm{Up}(j)} w_{ij} \cdot n_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\),
\(n_j\) is the weighted sum at node \(j\).

Accumulation proceeds in topological order from the sources to the sinks.

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).
return_type (str, optional) – Either “masked”, “gridded” or None. If None (default), uses river_network.return_type.

Returns:

Array of sum values for every river network node or gridcell, depending on return_type.

Return type:

array-like

earthkit.hydro.upstream.array.var(river_network, field, node_weights=None, edge_weights=None, return_type=None)[source]¶

Computes the weighted variance of a field over all upstream nodes.

For each node in the river network, this function identifies all upstream nodes in the river network and accumulates their contributions downstream, weighted by both node and edge weights.

The weighted variance is defined as:

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\),
\(n_j\) is the accumulated weighted value,
\(q_j\) is the accumulated weighted squared value,
\(d_j\) is the accumulated weight (denominator),
\(\bar{x}_j\) is the weighted average at node \(j\),
\(\mathrm{Var}(x)_j\) is the weighted variance at node \(j\).

Accumulation proceeds in topological order from the sources to the sinks. This formulation computes the population variance.

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).
return_type (str, optional) – Either “masked”, “gridded” or None. If None (default), uses river_network.return_type.

Returns:

Array of variance values for every river network node or gridcell, depending on return_type.

Return type:

array-like