priority_flow.fix_drainage
==========================

.. py:module:: priority_flow.fix_drainage

.. autoapi-nested-parse::

   Walk upstream from a point ensuring DEM is increasing by a minimum epsilon.

   Line-by-line translation of Fix_Drainage.R (FixDrainage) from the R PriorityFlow
   package. R uses 1-based indexing; we use 0-based. startpoint is (row, col) 0-based.



Functions
---------

.. autoapisummary::

   priority_flow.fix_drainage.fix_drainage


Module Contents
---------------

.. py:function:: fix_drainage(dem: numpy.ndarray, direction: numpy.ndarray, mask: numpy.ndarray, bank_epsilon: float, startpoint: Union[Tuple[int, int], list, numpy.ndarray], d4: Tuple[int, int, int, int] = (1, 2, 3, 4)) -> Dict[str, numpy.ndarray]

   Walk upstream from a point ensuring DEM is increasing by a minum epsilon.

   This walks upstream from a point following a flow direction file and checks that the elevation upstream
   is greater than or equal to the elvation at the point + epsilon
   Once the function reaches a point where upstream cells pass it stops

   NOTE: this is only processing the immediate neigborhood and does not recurse over the entire domain,
   For example if you did the entire overal prioirty flow processing with an espilon of 0 then ran this
   functon starting at a river point with an epsilon of 0.1 this function will traverse upstream from the
   river bottom checking that every cell conneting to the river cell is higher by at least this ammout but
   once it reaches a point where every connected cell passes this test it will stop. Therefore there could
   still be locations higher up on the hillslope with the original epsilon of zero still.  This  is on purpose
   and this script is not intended to gobally ensure a given epsilon.

   :param dem: 2D array of elevations for the domain (nx, ny).
   :type dem: np.ndarray
   :param direction: 2D array of D4 flow directions for each cell. Direction codes
                     follow the ``d4`` numbering scheme.
   :type direction: np.ndarray
   :param mask: 2D mask with ones for cells that are allowed to be processed and
                zeros elsewhere. Only neighbors within the mask can be adjusted.
   :type mask: np.ndarray
   :param bank_epsilon: Minimum elevation difference that upstream cells must have
                        relative to the current cell. If an upstream neighbor is lower
                        than ``current + bank_epsilon``, its elevation is raised to
                        ``current + bank_epsilon``.
   :type bank_epsilon: float
   :param startpoint: Starting grid cell given as ``(row, col)`` indices (0-based)
                      from which to begin walking upstream.
   :type startpoint: tuple[int, int] or list or np.ndarray
   :param d4: 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.
   :type d4: tuple of int, optional

   :returns: Dictionary containing:

             - ``"dem.adj"``: 2D elevation array after local adjustments.
             - ``"processed"``: 2D array marking cells that were adjusted
               (1) or visited during processing, and 0 elsewhere.
   :rtype: Dict[str, np.ndarray]