topotoolbox.StreamObject

class topotoolbox.StreamObject(flow: FlowObject, units: str = 'pixels', threshold: int | float | GridObject | ndarray = 0, stream_pixels: GridObject | ndarray | None = None)

Bases: object

A class to represent stream flow accumulation based on a FlowObject.

__init__(flow: FlowObject, units: str = 'pixels', threshold: int | float | GridObject | ndarray = 0, stream_pixels: GridObject | ndarray | None = None) → None

Initializes the StreamObject by processing flow accumulation.

Parameters:

• flow (FlowObject) – The input flow object containing source, target, direction, and other properties related to flow data.

• units (str, optional) – Units of measurement for the flow data. Can be ‘pixels’, ‘mapunits’, ‘m2’, or ‘km2’. Default is ‘pixels’.

• threshold (int | float | GridObject | np.ndarray, optional) – The upslope area threshold for flow accumulation. This can be an integer, float, GridObject, or a NumPy array. If more water than in the threshold has accumulated in a cell, it is part of the stream. Default is 0, which will result in the threshold being generated based on this formula: threshold = (avg^2)*0.01 where shape = (n,m).

• stream_pixels (GridObject | np.ndarray, optional) – A GridObject or np.ndarray made up of zeros and ones to denote where the stream is located. Using this will overwrite any use of the threshold argument.

Raises:

• ValueError – If the units parameter is not ‘pixels’, ‘mapunits’, ‘m2’, or ‘km2’.

• ValueError – If the shape of the threshold does not match the flow object shape.

Methods

__init__(flow[, units, threshold, stream_pixels])	Initializes the StreamObject by processing flow accumulation.
chitransform(upstream_area[, a0, mn, k, ...])	Coordinate transformation using the integral approach
distance()	Compute the pixel-to-pixel distance for each edge.
downstream_distance()	Compute the maximum distance between a node in the stream network and the channel head.
ezgetnal(k)	Retrieve a node attribute list from k
klargestconncomps([k])	Extract the k largest connected components of the stream network
plot([ax])	Plot the StreamObject
plotdz(z[, ax, dunit, doffset])	Plot a node attribute list against upstream distance
trunk([downstream_distance, flow_accumulation])	Reduces a stream network to the longest streams in each stream network tree (e.g. connected component).
xy([data])	Compute the x and y coordinates of continuous stream segments

chitransform(upstream_area: GridObject | ndarray, a0: float = 1000000.0, mn: float = 0.45, k: GridObject | ndarray | None = None, correctcellsize: bool = True)

Coordinate transformation using the integral approach

Transforms the horizontal spatial coordinates of a river longitudinal profile using an integration in upstream direction of drainage area (chi, see Perron and Royden, 2013).

Parameters:

• upstream_area (GridObject | np.ndarray) – Raster with the upstream areas. Must be the same size and projection as the GridObject used to create the StreamObject.

• a0 (float, optional) – Reference area in the same units as the upstream_area raster. Defaults to 100_000.

• mn (float, optional) – mn-ratio. Defaults to 0.45.

• k (GridObject | np.ndarray | None, optional) – Erosional efficiency, which may vary spatially. If k is supplied, then chitransform returns the time needed for a signal (knickpoint) propagating upstream from the outlet of the stream network. If k has units of m^(1 - 2m) / y, then time will have units of y. Note that calculating the response time requires the assumption that n=1. Defaults to None, which does not use the erosional efficiency.

• correctcellsize (bool, optional) – If true, multiplies the upstream_area raster by self.cellsize**2. Use if a0 has the same units of self.cellsize**2 and upstream_area has units of pixels, such as the default output from flow_accumulation. If the units of upstream_area are already m^2, then set correctcellsize to False. Defaults to True.

Raises:

• ValueError – If upstream_area or k does not have the right shape to be indexed by the StreamObject.

• TypeError – If upstream_area or k does not represent a type of data that can be extracted into a node attribute list.

• TypeError – If the modified upstream area is not a supported floating point type.

distance() → ndarray

Compute the pixel-to-pixel distance for each edge.

Returns:

An edge attribute list with the distance between pixels

Return type:

np.ndarray, float32

downstream_distance() → ndarray

Compute the maximum distance between a node in the stream network and the channel head.

Returns:

A node attribute list with the downstream distances

Return type:

np.ndarray, float32

ezgetnal(k: GridObject | ndarray | float)

Retrieve a node attribute list from k

Parameters:

k (GridObject | np.ndarray | float) – The object from which node values will be extracted. If k is a GridObject or an np.ndarray with the same shape as the underlying DEM of this StreamObject, the node values will be extracted from the grid by indexing. If k is an array with the same shape as the node attribute list, ezgetnal returns k. If k is a scalar value, ezgetnal returns an array of the right shape filled with k.

Raises:

• ValueError – If k does not have the right shape to be indexed by the StreamObject.

• TypeError – If k does not represent a type of data that can be extracted into a node attribute list.

klargestconncomps(k=1) → StreamObject

Extract the k largest connected components of the stream network

Components are ordered by the number of stream network pixels.

Parameters:

k (integer, optional) – The number of components to keep. The default is 1

Returns:

A new StreamObject containing only the k largest connected components

Return type:

StreamObject

plot(ax=None, **kwargs)

Plot the StreamObject

Stream segments as computed by StreamObject.xy are plotted using a LineCollection. Note that collections are not used in autoscaling the provided axis. If the axis limits are not already set, by another underlying plot, for example, call ax.autoscale_view() on the returned axes to show the plot.

Parameters:

• ax (matplotlib.axes.Axes, optional) – The axes in which to plot the StreamObject. If no axes are given, the current axes are used.

• **kwargs – Additional keyword arguments are forwarded to LineCollection

Returns:

The axes into which the StreamObject has been plotted.

Return type:

matplotlib.axes.Axes

plotdz(z, ax=None, dunit: str = 'm', doffset: float = 0, **kwargs)

Plot a node attribute list against upstream distance

Note that collections are not used in autoscaling the provided axis. If the axis limits are not already set, by another underlying plot, for example, call ax.autoscale_view() on the returned axes to show the plot.

Parameters:

• z (GridObject, np.ndarray) – The node attribute list that will be plotted

• ax (matplotlib.axes.Axes, optional) – The axes in which to plot the StreamObject. If no axes are given, the current axes are used.

• dunit (str, optional) – The unit to plot the upstream distance. Should be either ‘m’ for meters or ‘km’ for kilometers.

• doffset (float, optional) – An offset to be applied to the upstream distance. doffset should be in the units specified by dunit.

• **kwargs – Additional keyword arguments are forwarded to LineCollection

Returns:

The axes into which the plot as been added

Return type:

matplotlib.axes.Axes

Raises:

ValueError – If dunit is not one of ‘m’ or ‘km’.

trunk(downstream_distance: ndarray | None = None, flow_accumulation: GridObject | None = None) → StreamObject

Reduces a stream network to the longest streams in each stream network tree (e.g. connected component). The algorithm identifies the main trunk by sequently tracing the maximum downstream distance in upstream direction.

Parameters:

• flow_accumulation (Gridobject, optional) – A GridObject filled with flow accumulation values (as returned by the function FlowObject.flow_accumulation). Defaults to None.

• downstream_distance (np.ndarray, optional) – A numpy ndarray node-attribute list as generated by ezgetnal(). This argument overwrites the flow_accumulation if used. Defaults to None.

Returns:

StreamObject with truncated streams.

Return type:

StreamObject

xy(data=None)

Compute the x and y coordinates of continuous stream segments

Parameters:

data (tuple, optional) – A tuple of two node attribute lists representing the desired x and y values for each pixel in the stream network. If this argument is not supplied, the returned x and y values are the indices of the pixel in the DEM in the second and first dimension respectively. This reversal of dimensions corresponds to the orientation used by pyplot’s imshow, and allows plotting the stream network over a corresponding GridObject.

Returns:

A list of lists of (x,y) pairs.

Return type:

list