priority_flow.d4_traverse

Priority flow processing of D4 stream networks.

Line-by-line translation of D4_Traverse.R (D4TraverseB) from the R PriorityFlow package. R uses 1-based indexing; we use 0-based. Queue has columns (row, col, elevation).

Functions

d4_traverse_b(, printstep, nchunk, epsilon, printflag, ...)

Priority flow processing of D4 stream networks.

Module Contents

priority_flow.d4_traverse.d4_traverse_b(dem: numpy.ndarray, queue: numpy.ndarray, marked: numpy.ndarray, mask: numpy.ndarray | None = None, step: numpy.ndarray | None = None, direction: numpy.ndarray | None = None, basins: numpy.ndarray | None = None, d4: Tuple[int, int, int, int] = (1, 2, 3, 4), printstep: bool = False, nchunk: int = 100, epsilon: float = 0.0, printflag: bool = False, *, n_chunk: int | None = None) → Dict[str, numpy.ndarray][source]

Priority flow processing of D4 stream networks.

This function is a direct port of the R function D4TraverseB from the PriorityFlow package. It processes all stream-network cells by walking upstream along D4 (cross-shaped) neighbors inside a mask. Where no D4 neighbors exist, it looks for D8 (diagonal) neighbors and effectively creates D4 bridges to those diagonal cells by filling intervening elevations.

Parameters:

  • dem (np.ndarray) – 2D array of elevations for the domain in HydroFrame layout (nx, ny).

  • queue (np.ndarray) – Initial priority queue with shape (n, 3). Each row is (i, j, elevation) giving the row index, column index and elevation of a starting cell. Indices are 0-based.

  • marked (np.ndarray) – 2D array of the same shape as dem indicating which cells have already been marked (typically 1 for processed / queued cells and 0 otherwise).

  • mask (np.ndarray, optional) – 2D mask with ones for cells to be processed and zeros for everything else. If None, a mask of all ones with the same shape as dem is used.

  • step (np.ndarray, optional) – 2D array recording the step number at which each cell was processed. If None, initialized to all zeros.

  • direction (np.ndarray, optional) – 2D array of flow directions for processed cells. Direction codes follow the d4 numbering scheme. If None, initialized to np.nan everywhere.

  • basins (np.ndarray, optional) – 2D array of basin identifiers, typically created by an initialization script. When provided, any new cell added to the queue is assigned the same basin number as the cell that added it. If None, initialized to all zeros.

  • d4 (tuple of int, optional) – Direction numbering system for the D4 neighbors, given as (down, left, up, right). Defaults to (1, 2, 3, 4) to match the original R implementation.

  • printstep (bool, optional) – If True, print the step number and current queue sizes while traversing.

  • nchunk (int, optional) – Queue-splitting parameter. The top nchunk values are kept in the primary queue for initial processing; additional cells are placed into a secondary queue and merged in chunks.

  • epsilon (float, optional) – Small value added to filled areas to avoid creating flat regions when raising elevations. Defaults to 0.0.

  • printflag (bool, optional) – Optional flag preserved for API compatibility with the R function. Currently not used in the Python implementation.

  • n_chunk (int, optional) – Keyword alias for nchunk. If provided, overrides nchunk.

Returns:

Dictionary containing:

  • "dem": updated elevation array after filling.

  • "mask": mask used during processing.

  • "marked": updated marked array.

  • "step": step number at which each cell was processed.

  • "direction": flow direction codes for each cell.

  • "basins": basin identifier assigned to each cell.

Return type:

Dict[str, np.ndarray]

Notes

All arrays are 2D with shape (nx, ny) and use 0-based indexing. The traversal walks upstream, so direction codes point from each cell toward its downstream neighbor following the chosen d4 numbering.