topotoolbox.FlowObject#

class topotoolbox.FlowObject(grid: GridObject, bc: ndarray | GridObject | None = None, hybrid: bool = True)[source]#

Bases: object

A class containing containing (water-) flow information about a given digital elevation model (DEM).

__init__(grid: GridObject, bc: ndarray | GridObject | None = None, hybrid: bool = True)[source]#

The constructor for the FlowObject. Takes a GridObject as input, computes flow direction information and saves them as an FlowObject.

Parameters:

grid (GridObject) – The GridObject that will be the basis of the computation.
bc (ndarray or GridObject, optional) – Boundary conditions for sink filling. bc should be an array of np.uint8 that matches the shape of the DEM. Values of 1 indicate pixels that should be fixed to their values in the original DEM and values of 0 indicate pixels that should be filled.
hybrid (bool, optional) – Should hybrid reconstruction algorithm be used to fill sinks? Defaults to True. Hybrid reconstruction is faster but requires additional memory be allocated for a queue.

Notes

Large intermediate arrays are created during the initialization process, which could lead to issues when using very large DEMs.

Example

>>> import topotoolbox
>>> dem = topotoolbox.load_dem('perfectworld')
>>> flow = topotoolbox.FlowObject(dem)

Methods

`__init__`(grid[, bc, hybrid])	The constructor for the FlowObject.
`dependencemap`(l)	Delineate upslope area for specific locations in a DEM.
`downstream_distance`()	Calculates the horizontal distance from outlets and ridges along the flow network in the downstream direction.
`drainagebasins`([outlets])	Delineate drainage basins from a flow network.
`ezgetnal`(k[, dtype])	Retrieve a node attribute list
`flow_accumulation`([weights])	Computes the flow accumulation for a given flow network using optional weights.
`flowpathextract`(idx)	Extract linear indices of a single flowpath in a DEM
`getoutlets`()	Extract outlets from a flow network.
`influencemap`(l)	Delineate downslope area for specific locations in a DEM.
`node_to_node_distance`()	Compute the distance between each node in the flow network
`unravel_index`(idxs)	Unravel the provided linear indices so they can be used to index grids.
`upstream_distance`()	Calculates the horizontal distance from outlets and ridges along the flow network in the upstream direction.
`vertdistance2stream`(stream, grid)	Calculates relative elevation from rivers defined by a stream object.

Attributes

`dims`	The dimensions of the grid in the correct order for libtopotoolbox
`source_indices`	The row and column indices of the sources of each edge in the flow network.
`target_indices`	The row and column indices of the targets of each edge in the flow network.

dependencemap(l) → GridObject[source]#

Delineate upslope area for specific locations in a DEM.

Parameters:

fd (FlowObject)
l (GridObject) – logical grid

Returns:

i – logical influence grid (GRIDobj)

Return type:

GridObject

property dims#: The dimensions of the grid in the correct order for libtopotoolbox

downstream_distance() → GridObject[source]#

Calculates the horizontal distance from outlets and ridges along the flow network in the downstream direction.

Returns:: down_d – A new GridObject containing the distance grid
Return type:: GridObject

drainagebasins(outlets=None)[source]#

Delineate drainage basins from a flow network.

Parameters:: outlets (np.ndarray) – An array containing the linear indices of the outlet nodes.
Returns:: An integer-valued GridObject with a unique label for each drainage basin.
Return type:: GridObject

Example

>>> import topotoolbox
>>> import matplotlib.pyplot as plt
>>> dem = topotoolbox.load_dem('perfectworld')
>>> fd = topotoolbox.FlowObject(dem)
>>> basins = fd.drainagebasins()
>>> _= basins.shufflelabel().plot(cmap="Pastel1",interpolation="nearest")
>>> plt.show()

(Source code, png, hires.png, pdf)

ezgetnal(k, dtype=None) → GridObject | ndarray[source]#

Retrieve a node attribute list

Parameters:: k (GridObject or np.ndarray or scalar) – The object from which node values will be extracted. If k is a GridObject or an ndarray with the same shape as this FlowObject, then a copy is returned. If it is a scalar, an ndarray with the appropriate shape, filled with k, is returned.
Return type:: GridObject or np.ndarray
Raises:: ValueError – The supplied input is not aligned with the FlowObject.

Example

>>> import topotoolbox
>>> import matplotlib.pyplot as plt
>>> dem = topotoolbox.load_dem('bigtujunga')
>>> fd = topotoolbox.FlowObject(dem)
>>> _= fd.ezgetnal(dem).plot()
>>> plt.show()

(Source code, png, hires.png, pdf)

flow_accumulation(weights: ndarray | float = 1.0)[source]#

Computes the flow accumulation for a given flow network using optional weights. The flow accumulation represents the amount of flow each cell receives from its upstream neighbors.

Parameters:: weights (np.ndarray | float, optional) – An array of the same shape as the flow grid representing weights for each cell, or a constant float value used as the weight for all cells. If weights=1.0 (default), the flow accumulation is unweighted. If an ndarray is provided, it must match the shape of the flow grid., by default 1.0
Returns:: A new GridObject containing the flow accumulation grid.
Return type:: GridObject
Raises:: ValueError – If the shape of the weights array does not match the shape of the flow network grid.

Example

>>> import topotoolbox
>>> import matplotlib.pyplot as plt
>>> dem = topotoolbox.load_dem('perfectworld')
>>> fd = topotoolbox.FlowObject(dem)
>>> acc = fd.flow_accumulation()
>>> _= acc.plot(cmap='Blues',norm="log")
>>> plt.show()

(Source code, png, hires.png, pdf)

flowpathextract(idx: int)[source]#

Extract linear indices of a single flowpath in a DEM

The flow path downstream of idx is extracted from the flow directions recorded in FlowObject.

Parameters:: idx (int) – The column-major linear index of the starting pixel of the flowpath.
Returns:: An array containing column-major linear indices into the DEM identifying the flow path.
Return type:: np.ndarray

Example

>>> import topotoolbox
>>> dem = topotoolbox.load_dem('bigtujunga')
>>> fd = topotoolbox.FlowObject(dem)
>>> print(fd.flowpathextract(12345)) 

(Source code)

getoutlets()[source]#

Extract outlets from a flow network.

These are defined as nodes that have no downstream neighbor in the network. This includes any internal sinks as well as outlets where flow exits the DEM.

Returns:: A list of linear indices of outlets. Use FlowObject.unravel_index to convert to multidimensional indices to index into a GridObject.
Return type:: ndarray

Example

>>> import topotoolbox
>>> import matplotlib.pyplot as plt
>>> from matplotlib.colors import ListedColormap
>>> dem = topotoolbox.load_dem("bigtujunga")
>>> fd = topotoolbox.FlowObject(dem)
>>> outlets = fd.getoutlets()
>>> j, i = fd.unravel_index(outlets)
>>> x, y = fd.transform * (i, j)
>>> _ = dem.plot_hs(cmap=ListedColormap([0.9, 0.9, 0.9]), exaggerate=3)
>>> _ = plt.scatter(x, y)
>>> plt.show()

(Source code, png, hires.png, pdf)

influencemap(l) → GridObject[source]#

Delineate downslope area for specific locations in a DEM.

Parameters:

fd (FlowObject)
l (GridObject) – logical grid

Returns:

i – logical influence grid (GRIDobj)

Return type:

GridObject

node_to_node_distance()[source]#

Compute the distance between each node in the flow network

Returns:: An array (edge attribute list) with the interpixel distance. This will be either cellsize or sqrt(2)*cellsize
Return type:: np.ndarray

Example

>>> import topotoolbox
>>> dem = topotoolbox.load_dem('bigtujunga')
>>> fd = topotoolbox.FlowObject(dem)
>>> print(fd.node_to_node_distance()) 

(Source code)

property source_indices: tuple[ndarray, ...]#

The row and column indices of the sources of each edge in the flow network.

Returns:

tuple of ndarray – A tuple of arrays containing the row indices and column
indices of the sources of each edge in the flow
network. Each of these arrays is an edge attribute lists and
have a length equal to the number of edges in the flow
network. This tuple of arrays is suitable for indexing
GridObjects or arrays shaped like the GridObject from which
this FlowObject was derived.

property target_indices: tuple[ndarray, ...]#

The row and column indices of the targets of each edge in the flow network.

Returns:

tuple of ndarray – A tuple of arrays containing the row indices and column
indices of the sources of each edge in the flow
network. Each of these arrays is an edge attribute lists and
have a length equal to the number of edges in the flow
network. This tuple of arrays is suitable for indexing
GridObjects or arrays shaped like the GridObject from which
this FlowObject was derived.

unravel_index(idxs: int | ndarray) → tuple[ndarray, ...][source]#

Unravel the provided linear indices so they can be used to index grids.

Returns:

tuple of ndarray – A tuple of arrays containing the row indices and column
indices of the sources of each pixel in the idxs array.

upstream_distance() → GridObject[source]#

Calculates the horizontal distance from outlets and ridges along the flow network in the upstream direction.

Returns:: up_d – A new GridObject containing the distance grid
Return type:: GridObject

vertdistance2stream(stream, grid: GridObject) → GridObject[source]#

Calculates relative elevation from rivers defined by a stream object. Follows the flow paths, not the shortest euclidian distance. Also called hand (height above nearest drainage)

Returns:: up_z – A new GridObject containing the relative elevation grid
Return type:: GridObject

topotoolbox.FlowObject

Contents

topotoolbox.FlowObject#