pyflwdir.FlwdirRaster#
- class pyflwdir.FlwdirRaster(idxs_ds: ndarray, shape: tuple, ftype: Literal['d8', 'ldd', 'nextxy'], idxs_pit: ndarray | None = None, idxs_outlet: ndarray | None = None, idxs_seq: ndarray | None = None, nnodes: int | None = None, transform: Affine = Affine(1.0, 0.0, 0.0, 0.0, -1.0, 0.0), latlon: bool = False, cache: bool = True)[source]#
Flow-direction raster parsed into a common actionable format.
Initialize a flow-direction raster from downstream-cell indices.
- Parameters:
idxs_ds (1D-array of int) – Linear index of the next downstream cell for each raster cell.
shape (tuple of int) – Raster dimensions as (height, width).
ftype ({'d8', 'ldd', 'nextxy'}) – Flow-direction convention.
idxs_pit (np.ndarray of int, optional) – Indices of pit or outlet cells. idxs_outlet excludes pits of incomplete basins at the domain boundary.
idxs_outlet (np.ndarray of int, optional) – Indices of pit or outlet cells. idxs_outlet excludes pits of incomplete basins at the domain boundary.
idxs_seq (np.ndarray of int, optional) – Valid cell indices ordered from downstream to upstream.
nnodes (int, optional) – Number of valid cells. Calculated when needed if omitted.
transform (Affine, optional) – Affine transform mapping pixel coordinates to map coordinates, by default the identity transform.
latlon (bool, optional) – Whether coordinates use the WGS84 geographic coordinate system. If True, cell areas are converted from degrees to square metres; otherwise coordinates are assumed to use metres, by default False.
cache (bool, optional) – Whether to cache derived arrays, by default True.
- __init__(idxs_ds: ndarray, shape: tuple, ftype: Literal['d8', 'ldd', 'nextxy'], idxs_pit: ndarray | None = None, idxs_outlet: ndarray | None = None, idxs_seq: ndarray | None = None, nnodes: int | None = None, transform: Affine = Affine(1.0, 0.0, 0.0, 0.0, -1.0, 0.0), latlon: bool = False, cache: bool = True)[source]#
Initialize a flow-direction raster from downstream-cell indices.
- Parameters:
idxs_ds (1D-array of int) – Linear index of the next downstream cell for each raster cell.
shape (tuple of int) – Raster dimensions as (height, width).
ftype ({'d8', 'ldd', 'nextxy'}) – Flow-direction convention.
idxs_pit (np.ndarray of int, optional) – Indices of pit or outlet cells. idxs_outlet excludes pits of incomplete basins at the domain boundary.
idxs_outlet (np.ndarray of int, optional) – Indices of pit or outlet cells. idxs_outlet excludes pits of incomplete basins at the domain boundary.
idxs_seq (np.ndarray of int, optional) – Valid cell indices ordered from downstream to upstream.
nnodes (int, optional) – Number of valid cells. Calculated when needed if omitted.
transform (Affine, optional) – Affine transform mapping pixel coordinates to map coordinates, by default the identity transform.
latlon (bool, optional) – Whether coordinates use the WGS84 geographic coordinate system. If True, cell areas are converted from degrees to square metres; otherwise coordinates are assumed to use metres, by default False.
cache (bool, optional) – Whether to cache derived arrays, by default True.
Methods
__init__(idxs_ds, shape, ftype[, idxs_pit, ...])Initialize a flow-direction raster from downstream-cell indices.
accuflux(data[, nodata, direction])Return accumulated data values along the flow directions.
add_pits([idxs, xy, streams])Add pits to the flow-direction raster.
basin_bounds([basins])Return the bounding boxes of basins.
basin_outlets(basins)Return basin IDs and the linear index of each outlet cell.
basins([idxs, xy, ids])Return a basin map with a unique ID for each basin.
classify_estuaries(elevtn, rivwth[, rivdst, ...])Classify estuaries based on river-width convergence.
dem_adjust(elevtn)Returns the hydrologically adjusted elevation where each downstream cell has the same or lower elevation as the current cell.
dem_dig_d4(elevtn[, rivmsk, nodata])Return elevation adjusted to satisfy D4 connectivity along river cells.
downstream(data)Return the next downstream node's value for each node.
dump(fn)Serialize the flow-direction graph to a file using pickle.
fillnodata(data, nodata[, direction, how])Fill no-data nodes with values from valid upstream or downstream neighbors.
floodplains(elevtn[, uparea, upa_min, b])Identify floodplain cells using an upstream-area-scaled HAND threshold.
geofeatures(flowpaths[, xs, ys])Return geographic features for flow paths represented by linear indices.
hand(drain, elevtn)Return the height above the nearest drain (HAND).
index(xs, ys, **kwargs)Returns linear cell indices based on x, y coordinates.
inflow_idxs(region)Return linear indices of the most upstream cells within a region.
interbasin_mask(region[, stream])Return a mask for the most downstream contiguous area within a region.
load(fn)Load serialized FlwdirRaster object from file
main_upstream([uparea])Return the main upstream node for each node.
moving_average(data, n[, weights, ...])Take the moving weighted average over the flow direction network
moving_median(data, n[, restrict_strord, ...])Take the moving median over the flow direction network
order_cells([method])Order cells from down- to upstream.
outflow_idxs(region)Return linear indices of the most downstream cells within a region.
path([idxs, xy, mask, max_length, unit, ...])Trace paths downstream or upstream from starting cells.
Repair loops by setting a pit at every cell which does not drain to a pit.
river_depth(qbankfull, rivwth[, zs, rivdst, ...])Estimate river depth from Manning's equation or a gradually varied-flow solver.
set_transform(transform[, latlon])Set the affine transform and coordinate-system type.
smooth_rivlen(rivlen, min_rivlen[, ...])Return smoothed river length, by taking the window average of river length.
snap([idxs, xy, mask, max_length, unit, ...])Snap starting cells to a downstream or upstream target.
stream_distance([mask, unit])Return the distance to the outlet or the next downstream True cell in mask.
stream_order([type, mask])Return the Strahler (default) or classic stream-order map.
streams([mask, min_sto, xs, ys, idxs_out, ...])Return stream segments as LineString geographic features.
subbasins(riv_mask)Return a subbasin map with unique IDs starting from 1.
subbasins_area(area_min[, uparea])Return subbasins with a minimum contributing area of area_min.
subbasins_pfafstetter([depth, uparea, upa_min])Return subbasins using the Pfafstetter coding system.
subbasins_streamorder([strord, mask, min_sto])Return subbasins defined by stream-order changes and their outlet indices.
subgrid_rivavg(idxs_out, data[, weights, ...])Return the average value over the subgrid river at unit-catchment outlets.
subgrid_rivlen(idxs_out[, mask, direction, unit])Returns the subgrid river length [m] based on unit catchment outlet locations.
subgrid_rivmed(idxs_out, data[, weights, ...])Return the median value over the subgrid river at unit-catchment outlets.
subgrid_rivslp(idxs_out, elevtn[, length, ...])Return the subgrid river slope [m/m] estimated at unit-catchment outlets.
to_array([ftype])Return 2D flow direction raster.
ucat_area(idxs_out[, unit])Return the high-resolution unit-catchment map and low-resolution cell areas.
ucat_outlets(cellsize[, uparea, method])Return linear indices of unit-catchment outlet pixels.
ucat_volume(idxs_out, hand[, depths])Return the high-resolution unit-catchment map and flood volumes by depth.
upscale(scale_factor[, method, uparea])Upscale a flow-direction network to a lower resolution.
upscale_error(other, idxs_out)Return an error map for the upscaled flow directions.
upstream_area([unit])Return the upstream-area raster for the flow directions.
upstream_sum(data[, mv])Return the sum of values at each node's immediate upstream neighbors.
vectorize([mask, xs, ys, direction])Return each selected flow path as a LineString feature.
xy(idxs, **kwargs)Returns x, y coordinates of the cell center based on linear cell indices.
Attributes
Cell area [m2].
Returns the raster bounding box [xmin, ymin, xmax, ymax].
Distance to outlet [m]
Returns the raster extent in cartopy format [xmin, xmax, ymin, ymax].
Linear indices of downstream cell.
Linear indices of pits/outlets.
Linear indices of valid cells ordered from down- to upstream.
Linear indices of main upstream cell, i.e. the upstream cell with the largest contributing area.
True if the flow direction map is valid.
Boolean array of valid cells in flow direction raster.
Number of immediate upstream connections for each node.
Number of valid cells in the flow-direction raster.
Number of valid cells.
Cell Rank, i.e. distance to the outlet in no.