topotoolbox.StreamObject

class topotoolbox.StreamObject(flow: FlowObject, units: str = 'pixels', threshold: int | float | GridObject | ndarray = 0, stream_pixels: ndarray | GridObject | 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: ndarray | GridObject | 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.
ezgetnal(k)	Retrieve a node attribute list from k
show([cmap, overlay, overlay_cmap, alpha])	Display the StreamObject instance as an image using Matplotlib.

chitransform(upstream_area: GridObject | ndarray, a0: float = 1000000.0, mn: float = 0.45, k: ndarray | GridObject | 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

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.

show(cmap='hot', overlay: GridObject | None = None, overlay_cmap: str = 'binary', alpha: float = 0.8) → None

Display the StreamObject instance as an image using Matplotlib.

Parameters:

• cmap (str, optional) – Matplotlib colormap that will be used for the stream.

• overlay_cmap (str, optional) – Matplotlib colormap that will be used in the background plot.

• overlay (GridObject | None, optional) – To overlay the stream over a dem to better visualize the stream.

• alpha (float, optional) – When using an dem to overlay, this controls the opacity of the dem.