earthkit.hydro.distance.array¶

Module contents¶

earthkit.hydro.distance.array.max(river_network, locations, field=None, upstream=False, downstream=True, return_type=None)[source]¶

Calculates the maximum distance to all points from a set of start locations.

For each node in the network, calculates the maximum distance starting from any of the start locations.

The distance is defined as:

\begin{align*} d_j &= 0 ~\text{for start locations}\\ d_j &= \mathrm{max}(-\infty,~\mathrm{max}_{i \in \mathrm{Neighbour}(j)} (d_i + w_{ij}) ) \end{align*}

where:

\(w_{ij}\) is the edge distance (e.g., downstream distance),
\(\mathrm{Neighbour}(j)\) is the set of neighbouring nodes to node \(j\), which can include upstream and/or downstream nodes depending on passed arguments.
\(d_j\) is the total distance at node \(j\).

Unreachable nodes are given a distance of \(-\infty\).

Parameters:

river_network (RiverNetwork) – A river network object.
locations (array-like or dict) – A list of source nodes.
field (array-like, optional) – An array containing length values defined on river network edges. Default is xp.ones(river_network.n_edges).
upstream (bool, optional) – Whether or not to consider upstream distances. Default is False.
downstream (bool, optional) – Whether or not to consider downstream distances. Default is True.
return_type (str, optional) – Either “masked”, “gridded” or None. If None (default), uses river_network.return_type.

Returns:

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

Return type:

array-like

earthkit.hydro.distance.array.min(river_network, locations, field=None, upstream=False, downstream=True, return_type=None)[source]¶

Calculates the minimum distance to all points from a set of start locations.

For each node in the network, calculates the minimum distance starting from any of the start locations.

The distance is defined as:

\begin{align*} d_j &= 0 ~\text{for start locations}\\ d_j &= \mathrm{min}(\infty,~\mathrm{min}_{i \in \mathrm{Neighbour}(j)} (d_i + w_{ij}) ) \end{align*}

where:

\(w_{ij}\) is the edge distance (e.g., downstream distance),
\(\mathrm{Neighbour}(j)\) is the set of neighbouring nodes to node \(j\), which can include upstream and/or downstream nodes depending on passed arguments.
\(d_j\) is the total distance at node \(j\).

Unreachable nodes are given a distance of \(\infty\).

Parameters:

river_network (RiverNetwork) – A river network object.
locations (array-like or dict) – A list of source nodes.
field (array-like, optional) – An array containing length values defined on river network edges. Default is xp.ones(river_network.n_edges).
upstream (bool, optional) – Whether or not to consider upstream distances. Default is False.
downstream (bool, optional) – Whether or not to consider downstream distances. Default is True.
return_type (str, optional) – Either “masked”, “gridded” or None. If None (default), uses river_network.return_type.

Returns:

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

Return type:

array-like

earthkit.hydro.distance.array.to_sink(river_network, field=None, path='shortest', return_type=None)[source]¶

Calculates the maximum distance to all points from the river network sinks.

For each node in the network, calculates the maximum distance starting from any sink.

The distance is defined as:

\begin{align*} d_j &= 0 ~\text{for sinks}\\ d_j &= \bigoplus \left(-\infty,~\bigoplus_{i \in \mathrm{Neighbour}(j)} (d_i + w_{ij}) \right) \end{align*}

where:

\(w_{ij}\) is the edge distance (e.g., downstream distance),
\(\mathrm{Neighbour}(j)\) is the set of neighbouring nodes to node \(j\), which can include upstream and/or downstream nodes depending on passed arguments.
\(\bigoplus\) is the aggregation function (max for longest path or min for shortest path).
\(d_j\) is the total distance at node \(j\).

Unreachable nodes are given a distance of \(-\infty\) if \(\bigoplus\) is a maximum, and \(\infty\) if \(\bigoplus\) is a minimum.

Parameters:

river_network (RiverNetwork) – A river network object.
field (array-like, optional) – An array containing length values defined on river network edges. Default is xp.ones(river_network.n_edges).
path (str, optional) – Whether to compute the longest or shortest path. Default is “shortest”.
return_type (str, optional) – Either “masked”, “gridded” or None. If None (default), uses river_network.return_type.

Returns:

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

Return type:

array-like

earthkit.hydro.distance.array.to_source(river_network, field=None, path='shortest', return_type=None)[source]¶

Calculates the maximum distance to all points from the river network sources.

For each node in the network, calculates the maximum distance starting from any source.

The distance is defined as:

\begin{align*} d_j &= 0 ~\text{for sources}\\ d_j &= \bigoplus \left(-\infty,~\bigoplus_{i \in \mathrm{Neighbour}(j)} (d_i + w_{ij}) \right) \end{align*}

where:

\(w_{ij}\) is the edge distance (e.g., downstream distance),
\(\mathrm{Neighbour}(j)\) is the set of neighbouring nodes to node \(j\), which can include upstream and/or downstream nodes depending on passed arguments.
\(\bigoplus\) is the aggregation function (max for longest path or min for shortest path).
\(d_j\) is the total distance at node \(j\).

Unreachable nodes are given a distance of \(-\infty\) if \(\bigoplus\) is a maximum, and \(\infty\) if \(\bigoplus\) is a minimum.

Parameters:

river_network (RiverNetwork) – A river network object.
field (array-like, optional) – An array containing length values defined on river network edges. Default is xp.ones(river_network.n_edges).
path (str, optional) – Whether to compute the longest or shortest path. Default is “shortest”.
return_type (str, optional) – Either “masked”, “gridded” or None. If None (default), uses river_network.return_type.

Returns:

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

Return type:

array-like