priority_flow.drainage_area
===========================

.. py:module:: priority_flow.drainage_area

.. autoapi-nested-parse::

   Calculated drainage area.

   Line-by-line translation of drainage_area.R (drainageArea) from the R PriorityFlow package.
   Calculates the number of cells draining to any cell given a flow direction file.
   R uses 1-based indexing; we use 0-based.



Functions
---------

.. autoapisummary::

   priority_flow.drainage_area.drainage_area


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

.. py:function:: drainage_area(direction: numpy.ndarray, mask: Optional[numpy.ndarray] = None, d4: Tuple[int, int, int, int] = (1, 2, 3, 4), printflag: bool = False) -> numpy.ndarray

   Calculate drainage area (number of upstream cells) for each grid cell given a flow direction file.

   :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 to be processed and zeros for everything
                else. Cells outside the mask are excluded from the drainage-area
                computation. If ``None``, a mask of all ones with the same shape as
                ``direction`` is used.
   :type mask: 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
   :param printflag: If ``True``, print basic progress information as the algorithm walks
                     downstream through the queue of cells.
   :type printflag: bool, optional

   :returns: 2D array of drainage areas with the same shape as ``direction``. Each
             entry gives the number of cells (including itself) that drain to that
             cell, multiplied by ``mask`` so cells outside the mask have value 0.
   :rtype: np.ndarray