wolfhece.PyHydrographs
======================

.. py:module:: wolfhece.PyHydrographs

.. autoapi-nested-parse::

   Author: HECE - University of Liege, Pierre Archambeau, Utashi Ciraane Docile
   Date: 2024

   Copyright (c) 2024 University of Liege. All rights reserved.

   This script and its content are protected by copyright law. Unauthorized
   copying or distribution of this file, via any medium, is strictly prohibited.





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

.. py:class:: Constants(*args, **kwds)

   Bases: :py:obj:`enum.Enum`

   .. autoapi-inheritance-diagram:: wolfhece.PyHydrographs.Constants
      :parts: 1
      :private-bases:


   Contain the constants used throughout
   the module.


   .. py:attribute:: SEPARATOR
      :value: '\t'



.. py:class:: Hydrograph(data=None, index=None, dtype=None, name=None, copy=None, file_path: str = '')

   Bases: :py:obj:`pandas.Series`

   .. autoapi-inheritance-diagram:: wolfhece.PyHydrographs.Hydrograph
      :parts: 1
      :private-bases:


   A pandas series containing discharges (values)
   with their respective times of observation (indices).

   @ The class is inherited which means
   all series method are available in this
   class escorted by a few other functions useful in
   the interaction with wolfhece tools.



   .. py:method:: write_as_wolf_file(file_path: str, writing_method: Literal['continuous', 'stepwise'] = 'continuous', epsilon: float = 1.0)

      Write the hydrograph on the infiltration format
      of wolf models -> infil[n].tv file.



   .. py:method:: read_from_wolf_file(file_path: str, separator: Literal[',', ';', '\t'] = Constants.SEPARATOR.value) -> dict

      Read a wolf file at the format infil[n].tv and
      return its data as a dictionnary where:
       - keys are times and,
       - values are discharges.




   .. py:method:: _convert_date_format_to_duration_format(to_format: Literal['s', 'm', 'h', 'd'] = ['s'])

      Convert a date format of indexes to a duration format.



   .. py:method:: set_zero_as_start()

      Set the first time of the hydrograph as zero.



   .. py:method:: set_zero_and_convert_format(to_format: Literal['s', 'm', 'h', 'd'] = 's')

      Set the first time of the hydrograph as zero and convert
      the format to a duration format.



.. py:class:: HydrOperations

   Contains the operations that can be performed on Hydrographs.


   .. py:method:: substract_hydrograph(hydrograph1: Hydrograph, hydrograph2: Hydrograph) -> Hydrograph

      Substract two hydrographs and return the difference.
      The second hydrograph is substracted from the first.

      .. note:: The Nan values in the difference are dropped to avoid
      constraints of hydrographs index.

      :param hydrograph1: The first hydrograph.
      :type hydrograph1: Hydrograph
      :param hydrograph2: The second hydrograph.
      :type hydrograph2: Hydrograph
      :return: The difference between the two hydrographs.
      :rtype: Hydrograph



   .. py:method:: add_hydrograph(hydrograph1: Hydrograph, hydrograph2: Hydrograph) -> Hydrograph

      Add two hydrographs and return the sum.
      The second hydrograph is added to the first.

      .. note:: The Nan values in the sum are dropped to avoid
      constraints of hydrographs index.

      :param hydrograph1: The first hydrograph.
      :type hydrograph1: Hydrograph
      :param hydrograph2: The second hydrograph.
      :type hydrograph2: Hydrograph
      :return: The sum of the two hydrographs.
      :rtype: Hydrograph



   .. py:method:: add_list_of_hydrographs(hydrographs: list) -> Hydrograph

      Add a list of hydrographs and return the sum.
      The hydrographs are added one after the other  to the first one.

      .. note:: The Nan values in the sum are dropped to avoid
      constraints of hydrographs index.

      :param hydrographs: The list of hydrographs.
      :type hydrographs: list
      :return: The sum of the hydrographs.
      :rtype: Hydrograph



   .. py:method:: substract_list_of_hydrographs(hydrographs: list) -> Hydrograph

      Substract a list of hydrographs and return the difference.
      The hydrographs are substracted one after the other from the first one.

      .. note:: The Nan values in the difference are dropped to avoid
      constraints of hydrographs index.

      :param hydrographs: The list of hydrographs.
      :type hydrographs: list
      :return: The difference between the hydrographs.
      :rtype: Hydrograph



   .. py:method:: as_stepwise_Hydrograph(hydrograph: Hydrograph | pandas.Series, epsilon=1) -> Hydrograph
      :staticmethod:


      Return a stepwise hydrograph from a given hydrograph.

      The steps are made by shifting uniformly the time index by an epsilon value (default 1 is subtracted)
      while keeping the same discharge value.
      This is useful for harmonizing  a hydrograph in a stepwise manner.

      :param hydrograph: The hydrograph to be converted to stepwise format.
      :type hydrograph: Hydrograph or Pandas Series
      :param epsilon: The value subtracted from each index of the hydrograph (each timestep), defaults to 1
      :type epsilon: int, optional
      :return: the stepwise hydrograph
      :rtype: Hydrograph



   .. py:method:: find_conversion_factor_from_seconds(convert_to: Literal['weeks', 'days', 'hours', 'minutes', 'seconds'] = 'seconds') -> int
      :staticmethod:


      Find the conversion factor of a given time format to seconds.

      :param convert_to: The time format to convert to.
      :type convert_to: Literal['days', 'hours', 'minutes', 'seconds']
      :return: The conversion factor.
      :rtype: int



   .. py:method:: create_one_matplolib_axis(time: float, convert_to: Literal['weeks', 'days', 'hours', 'minutes', 'seconds'] = 'seconds', figsize: tuple = (30, 5), ylabel: str = 'Discharge ($m^3$/s)', tick_spacing: int = 1, x_start: int = 0, x_end: int = None, ax=None) -> matplotlib.axes.Axes

      Create a matplotlib axis with a date format
      of the number of days passed as argument.