earthkit.hydro.catchments.array

Module contents

earthkit.hydro.catchments.array.find(river_network, locations, overwrite=True, return_type=None)

Delineates catchment areas.

Given a field indicating one or more start locations (e.g., outlet points or pour points), this function delineates the catchments upstream of each start location by grouping all cells that flow into these points.

Parameters:

• river_network (RiverNetwork) – A river network object.

• locations (array-like or dict) – A list of catchment sink nodes (start locations).

• overwrite (bool, optional) – Whether to overwrite subcatchments or not. Default is True.

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

Returns:

Array of labelled catchments for every river network node or gridcell, depending on return_grid.

Return type:

array-like

earthkit.hydro.catchments.array.max(river_network, field, locations, node_weights=None, edge_weights=None)

Computes the weighted maximum of a field over the upstream catchment of each specified location.

For each location, 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.

• locations (array-like or dict) – A list of nodes at which to compute.

• 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 river network edge. Default is None (unweighted).

Returns:

Array of maximum values for each location in locations.

Return type:

array-like

earthkit.hydro.catchments.array.mean(river_network, field, locations, node_weights=None, edge_weights=None)

Computes the weighted mean of a field over the upstream catchment of each specified location.

For each location, 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.

• locations (array-like or dict) – A list of nodes at which to compute.

• 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 river network edge. Default is None (unweighted).

Returns:

Array of mean values for each location in locations.

Return type:

array-like

earthkit.hydro.catchments.array.min(river_network, field, locations, node_weights=None, edge_weights=None)

Computes the weighted minimum of a field over the upstream catchment of each specified location.

For each location, 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.

• locations (array-like or dict) – A list of nodes at which to compute.

• 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 river network edge. Default is None (unweighted).

Returns:

Array of minimum values for each location in locations.

Return type:

array-like

earthkit.hydro.catchments.array.mode(river_network, field, locations, node_weights=None, edge_weights=None)

Computes the mode (most frequent categorical value) of a field over the upstream catchment of each specified location.

For each location, this function identifies all upstream nodes in the river network and computes the mode (spatial majority) of categorical values.

The mode is defined as the categorical value that appears most frequently in the upstream catchment. For categorical data (e.g., land use classes, soil types), mode provides the dominant category. When multiple categories have the same maximum frequency (a tie), the smallest category value is returned.

\begin{align*} \mathrm{Mode}(x)_j &= \mathrm{arg\,max}_c \left( \sum_{i \in C_j} \mathbb{1}_{x_i = c} \right) \end{align*}

where:

• \(x_i\) is the categorical value at node \(i\) (e.g., land use class),

• \(C_j\) is the set of all upstream nodes in the catchment of location \(j\),

• \(\mathbb{1}_{x_i = c}\) is an indicator function (1 if \(x_i = c\), 0 otherwise),

• \(\mathrm{Mode}(x)_j\) is the most frequent category in catchment \(j\).

Note: Mode calculation does not support node weights or edge weights, as it operates on categorical data. If weights are provided, they will be ignored.

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 must be integers representing categories (e.g., 1=forest, 2=urban, 3=water).

• locations (array-like or dict) – A list of nodes at which to compute the catchment mode.

• node_weights (array-like, optional) – Not supported for mode. Will be ignored if provided.

• edge_weights (array-like, optional) – Not supported for mode. Will be ignored if provided.

Returns:

Array of mode (most frequent categorical) values for each location in locations.

Return type:

array-like

earthkit.hydro.catchments.array.percentile(river_network, field, p, locations, node_weights=None, edge_weights=None)

Computes the weighted percentile of a field over the upstream catchment of each specified location.

For each location, 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).

• locations (array-like or dict) – A list of nodes at which to compute.

• 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 river network edge. Default is None (unweighted). Currently unsupported.

Returns:

Array of percentile values for each location in locations.

Return type:

array-like

earthkit.hydro.catchments.array.std(river_network, field, locations, node_weights=None, edge_weights=None)

Computes the weighted standard deviation of a field over the upstream catchment of each specified location.

For each location, 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.

• locations (array-like or dict) – A list of nodes at which to compute.

• 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 river network edge. Default is None (unweighted).

Returns:

Array of standard deviation values for each location in locations.

Return type:

array-like

earthkit.hydro.catchments.array.sum(river_network, field, locations, node_weights=None, edge_weights=None)

Computes the weighted sum of a field over the upstream catchment of each specified location.

For each location, 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.

• locations (array-like or dict) – A list of nodes at which to compute.

• 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 river network edge. Default is None (unweighted).

Returns:

Array of sum values for each location in locations.

Return type:

array-like

earthkit.hydro.catchments.array.var(river_network, field, locations, node_weights=None, edge_weights=None)

Computes the weighted variance of a field over the upstream catchment of each specified location.

For each location, 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:

\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 \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\).

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.

• locations (array-like or dict) – A list of nodes at which to compute.

• 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 river network edge. Default is None (unweighted).

Returns:

Array of variance values for each location in locations.

Return type:

array-like