priority_flow.river_slope
=========================

.. py:module:: priority_flow.river_slope

.. autoapi-nested-parse::

   Apply minimum slope and secondary scaling to river cells.

   Line-by-line translation of River_Slope.R (RivSlope) from the R PriorityFlow
   package. R uses 1-based indexing; we use 0-based.



Functions
---------

.. autoapisummary::

   priority_flow.river_slope.riv_slope


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

.. py:function:: riv_slope(direction: numpy.ndarray, slopex: numpy.ndarray, slopey: numpy.ndarray, minslope: float, river_mask: Optional[numpy.ndarray] = None, remove_sec: bool = False) -> Dict[str, numpy.ndarray]

   Apply minimum slope and secondary scaling to river cells.

   A funtion that will apply a minimum slope threshold for the primary
   flow direciton along river cells. This function can also limit secondary
   slopes out of river cells to zero.

   :param direction: 2D array of D4 flow directions for each cell, using the
                     convention ``1 = down``, ``2 = left``, ``3 = up``, ``4 = right``.
   :type direction: np.ndarray
   :param slopex: 2D array of face-centered slopes in the x-direction. These
                  should be the same slopes produced by ``slope_calc_standard``.
   :type slopex: np.ndarray
   :param slopey: 2D array of face-centered slopes in the y-direction, compatible
                  with ``slope_calc_standard``.
   :type slopey: np.ndarray
   :param minslope: Threshold for slope adjustment. For each river cell, the
                    absolute value of the primary-direction slope is adjusted so
                    that ``abs(slope) >= minslope``.
   :type minslope: float
   :param river_mask: 2D mask indicating which cells are treated as river cells
                      (typically 1 for river, 0 for non-river). Only these cells are
                      subject to minimum-slope and secondary-slope adjustments.
   :type river_mask: np.ndarray, optional
   :param remove_sec: If ``True``, any secondary outflows from river cells (i.e.
                      positive slopes in non-primary directions) are set to zero.
                      Defaults to ``False``.
   :type remove_sec: bool, optional

   :returns: Dictionary containing:

             - ``"slopex"``: adjusted x-direction slope field.
             - ``"slopey"``: adjusted y-direction slope field.
             - ``"adj_mask"``: mask of cells that were adjusted (non-zero
               where primary or secondary slopes were modified).
             - ``"SlopeOutlet"``: original primary outlet slope at each
               river cell before adjustment.
             - ``"SlopeOutletNew"``: primary outlet slope at each river
               cell after adjustment.
   :rtype: Dict[str, np.ndarray]