priority_flow.define_subbasins
==============================

.. py:module:: priority_flow.define_subbasins

.. autoapi-nested-parse::

   Define subbasins and stream segments from flow direction and drainage area.

   Line-by-line translation of Define_Subbasins.R (CalcSubbasins) from the R
   PriorityFlow package. R uses 1-based indexing; we use 0-based for array
   indexing; summary coordinate columns are 0-based.



Functions
---------

.. autoapisummary::

   priority_flow.define_subbasins.calc_subbasins


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

.. py:function:: calc_subbasins(direction: numpy.ndarray, area: numpy.ndarray, mask: Optional[numpy.ndarray] = None, d4: Tuple[int, int, int, int] = (1, 2, 3, 4), riv_th: int = 50, printflag: bool = False, merge_th: int = 0) -> Dict[str, numpy.ndarray]

   Define subbasins and stream segments from flow direction and drainage area.

   This function is a port of the R function ``CalcSubbasins`` from the
   PriorityFlow package. It divides the domain into subbasins and individual
   stream segments using a flow-direction grid and a drainage-area grid.

   :param direction: 2D array of D4 flow directions for each cell. Direction codes follow
                     the ``d4`` numbering scheme.
   :type direction: np.ndarray
   :param area: 2D array of drainage area values for every cell (typically in number of
                contributing cells or an equivalent measure).
   :type area: np.ndarray
   :param mask: 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
                ``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 riv_th: Drainage-area threshold used to classify river cells. Cells with
                  ``area >= riv_th`` are treated as part of the river network. Defaults
                  to ``50``.
   :type riv_th: int, optional
   :param printflag: If ``True``, print basic progress information while growing subbasins
                     upstream from the river network.
   :type printflag: bool, optional
   :param merge_th: After all subbasins have been defined, subbasins with total area
                    smaller than ``merge_th`` are merged into their downstream neighbors.
                    A value of ``0`` (the default) disables merging.
   :type merge_th: int, optional

   :returns: Dictionary containing:

             - ``"segments"``: 2D array with a unique ID for each stream segment.
             - ``"subbasins"``: 2D array with a unique ID for each subbasin
               (segment plus its contributing area).
             - ``"RiverMask"``: 2D mask of river cells derived from ``area`` and
               ``riv_th``.
             - ``"summary"``: 2D array where each row summarizes a subbasin/segment
               (segment ID, representative coordinates, downstream segment ID and
               cell count). Coordinates are stored using 0-based indexing.
   :rtype: Dict[str, np.ndarray]