earthkit.hydro.length¶

Subpackages¶

earthkit.hydro.length.array
- Module contents

Module contents¶

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

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

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

The length is defined as:

\begin{align*} l_j &= w_j ~\text{for start locations}\\ l_j &= \mathrm{max}(-\infty,~\mathrm{max}_{i \in \mathrm{Neighbour}(j)} l_i) + w_j \end{align*}

where:

\(w_i\) is the node length (e.g., pixel length),
\(\mathrm{Neighbour}(j)\) is the set of neighbouring nodes to node \(j\), which can include upstream and/or downstream nodes depending on passed arguments.
\(l_j\) is the total length at node \(j\).

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

Parameters:

river_network (RiverNetwork) – A river network object.
locations (array-like or dict) – A list of source nodes.
field (array-like or xarray object, optional) – An array containing length values defined on river network nodes or gridcells. Default is xp.ones(river_network.n_nodes).
upstream (bool, optional) – Whether or not to consider upstream lengths. Default is False.
downstream (bool, optional) – Whether or not to consider downstream lengths. Default is True.
return_type (str, optional) – Either “masked”, “gridded” or None. If None (default), uses river_network.return_type.
input_core_dims (sequence of sequence, optional) – List of core dimensions on each input xarray argument that should not be broadcast. Default is None, which attempts to autodetect input_core_dims from the xarray inputs. Ignored if no xarray inputs passed.

Returns:

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

Return type:

xarray object

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

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

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

The length is defined as:

\begin{align*} l_j &= w_j ~\text{for start locations}\\ l_j &= \mathrm{min}(\infty,~\mathrm{min}_{i \in \mathrm{Neighbour}(j)} l_i) + w_j \end{align*}

where:

\(w_i\) is the node length (e.g., pixel length),
\(\mathrm{Neighbour}(j)\) is the set of neighbouring nodes to node \(j\), which can include upstream and/or downstream nodes depending on passed arguments.
\(l_j\) is the total length at node \(j\).

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

Parameters:

river_network (RiverNetwork) – A river network object.
locations (array-like or dict) – A list of source nodes.
field (array-like or xarray object, optional) – An array containing length values defined on river network nodes or gridcells. Default is xp.ones(river_network.n_nodes).
upstream (bool, optional) – Whether or not to consider upstream lengths. Default is False.
downstream (bool, optional) – Whether or not to consider downstream lengths. Default is True.
return_type (str, optional) – Either “masked”, “gridded” or None. If None (default), uses river_network.return_type.
input_core_dims (sequence of sequence, optional) – List of core dimensions on each input xarray argument that should not be broadcast. Default is None, which attempts to autodetect input_core_dims from the xarray inputs. Ignored if no xarray inputs passed.

Returns:

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

Return type:

xarray object

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

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

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

The length is defined as:

\begin{align*} l_j &= w_j ~\text{for sinks}\\ l_j &= \bigoplus \left(-\infty,~\bigoplus_{i \in \mathrm{Neighbour}(j)} l_i \right) + w_j \end{align*}

where:

\(w_i\) is the node length (e.g., pixel length),
\(\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).
\(l_j\) is the total length 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 or xarray object, optional) – An array containing length values defined on river network nodes or gridcells. Default is xp.ones(river_network.n_nodes).
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.
input_core_dims (sequence of sequence, optional) – List of core dimensions on each input xarray argument that should not be broadcast. Default is None, which attempts to autodetect input_core_dims from the xarray inputs. Ignored if no xarray inputs passed.

Returns:

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

Return type:

xarray object

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

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

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

The length is defined as:

\begin{align*} l_j &= w_j ~\text{for sources}\\ l_j &= \bigoplus \left(-\infty,~\bigoplus_{i \in \mathrm{Neighbour}(j)} l_i \right) + w_j \end{align*}

where:

\(w_i\) is the node length (e.g., pixel length),
\(\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).
\(l_j\) is the total length 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 or xarray object, optional) – An array containing length values defined on river network nodes or gridcells. Default is xp.ones(river_network.n_nodes).
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.
input_core_dims (sequence of sequence, optional) – List of core dimensions on each input xarray argument that should not be broadcast. Default is None, which attempts to autodetect input_core_dims from the xarray inputs. Ignored if no xarray inputs passed.

Returns:

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

Return type:

xarray object