priority_flow.downstream_extract
================================

.. py:module:: priority_flow.downstream_extract

.. autoapi-nested-parse::

   Walk downstream from a point and extract values from a matrix.

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



Functions
---------

.. autoapisummary::

   priority_flow.downstream_extract.path_extract


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

.. py:function:: path_extract(input: numpy.ndarray, direction: numpy.ndarray, mask: Optional[numpy.ndarray] = None, startpoint: Optional[Union[Tuple[int, int], list, numpy.ndarray]] = None, d4: Tuple[int, int, int, int] = (1, 2, 3, 4)) -> Dict[str, numpy.ndarray]

   Walk downstream from a starting point and extract values from a matrix.

   This is a port of the R function ``PathExtract`` from the PriorityFlow
   package. Starting from a given grid cell, it follows the D4 flow-direction
   grid ``direction`` downstream, collecting values from ``input`` until the
   path leaves the domain or exits the processing mask.

   :param input: 2D array of values from which to extract the stream-path sequence
                 (for example, elevation, drainage area, or any other field defined
                 on the same grid as ``direction``).
   :type input: 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 part of the path
                and zeros elsewhere. If ``None``, a mask of all ones with the same
                shape as ``direction`` is used.
   :type mask: np.ndarray, optional
   :param startpoint: Starting grid cell given as ``(row, col)`` indices (0-based). If an
                      array-like object is provided, only the first two elements are used.
   :type startpoint: tuple[int, int] or list or np.ndarray, optional
   :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:

             - ``"data"``: 1D array of values extracted from ``input`` along the
               downstream path, in order.
             - ``"path_mask"``: 2D array with non-zero entries indicating the
               step number at each cell visited along the path.
             - ``"path_list"``: 2D array of ``(row, col)`` indices for the cells
               visited along the path, in traversal order.
   :rtype: Dict[str, np.ndarray]