wolfhece.eva.pyseries
=====================

.. py:module:: wolfhece.eva.pyseries

.. autoapi-nested-parse::

   EXTREME VALUES ANALYSIS - EVA

   @author : Pierre Archambeau - ULiege - HECE
   @date   : 2023









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

.. py:function:: change_font_size(ax: matplotlib.axes.Axes, fontsize)

   Adapte la taille de police d'un graphique


.. py:function:: set_style(color: Literal['b', 'g', 'r', 'c', 'm', 'y', 'k'], linestyle: Literal['solid', 'dotted', 'deshed', 'dashdot'] = 'solid', linewidth=1) -> dict['color':str, 'linestyle':str, 'linewidth':int]

.. py:function:: get_style(style: dict['color':str, 'linestyle':str, 'linewidth':int])

.. py:function:: cunnane(r, n)

   Calcul de la fréquence empirique selon Cunnane(1979)
   MAJ de la formulation de Weibull a priori mieux adaptée aux problèmes hydrologiques

   r : rang de la donnée 1<=r<=n
   n : nombre total de données dans l'échantillon


.. py:function:: weibull(r, n)

   Calcul de la fréquence empirique selon Weibull - loi "uniforme"

   r : rang de la donnée 1<=r<=n
   n : nombre total de données dans l'échantillon


.. py:function:: filliben(r, n)

   Calcul de la fréquence empirique selon Filliben

   r : rang de la donnée 1<=r<=n
   n : nombre total de données dans l'échantillon


.. py:function:: aic(mle, n, k=2, corrected=True)

   The Akaike information criterion (AIC) is a metric that is used to compare the fit of different regression models.

   It is calculated as:

   AIC = 2K – 2ln(L)

   where:

   K: The number of model parameters (including loc and scale)
   mle = ln(L): The log-likelihood of the model. This tells us how likely the model is, given the data.

   https://fr.wikipedia.org/wiki/Crit%C3%A8re_d%27information_d%27Akaike
   https://www.statology.org/aic-in-python/


.. py:function:: bic(mle, n, k=2)

   the Bayesian information criterion (BIC) or Schwarz information criterion (also SIC, SBC, SBIC) is a criterion for model selection among a finite set of models
   Models with lower BIC are generally preferred. It is based, in part, on the likelihood function and it is closely related to the Akaike information criterion (AIC).

   https://en.wikipedia.org/wiki/Bayesian_information_criterion
   https://fr.wikipedia.org/wiki/Crit%C3%A8re_d%27information_bay%C3%A9sien


.. py:function:: _get_hist_params(X, bins, mhist='numpy')

   Get histogram of original data


.. py:function:: rss(data, pdf, bins=100)

   Residual sum of squares

   based on pdf and data's histogram

   https://en.wikipedia.org/wiki/Residual_sum_of_squares


.. py:function:: _generate_clusters(exceedances: pandas.Series, r: Union[pandas.Timedelta, Any]) -> Generator[pandas.Series, None, None]

.. py:data:: MONTHS_WINTER
   :value: [10, 11, 12, 1, 2, 3]


.. py:data:: MONTS_SUMMER
   :value: [4, 5, 6, 7, 8, 9]


.. py:data:: SEASONS
   :value: ['annual', 'winter', 'summer']


.. py:data:: SEASONS_MARKERS
   :value: ['o', '*', 'x', '2']


.. py:data:: SEASONS_COLORS
   :value: ['r', 'g', 'b', 'c']


.. py:data:: SEASONS_ALL
   :value: ['annual', 'winter', 'summer', 'mixture', 'joint']


.. py:data:: RETURN_PERIOD_ESTIMATE

.. py:data:: INTERV_CI
   :value: [60, 75, 90, 95]


.. py:function:: sanitize_seasons(seasons=None, all=False)

.. py:data:: dists_4params

.. py:data:: dists_3params

.. py:data:: dists_2params

.. py:data:: LAWS_FULL
   :value: ['Gumbel', 'Normal', 'Gibrat', 'Exponentielle', 'GEV', 'Weibull', 'Fréchet', 'Log normale',...


.. py:data:: LAWS_POPULAR
   :value: ['GEV', 'Log normale', 'Gumbel', 'Exponentielle', 'Pearson3', 'Gamma inverse', 'Weibull',...


.. py:class:: EVA_Serie(data, datetime_index=None, datetime_format='%Y%m%d%H%M%S', data_headers=('#DateHeure', 'Debit'), duration=1, startmonth_winter=10, startmonth_summer=4, hydrol=True, verbose=True)

   One time serie


   .. py:attribute:: duration
      :value: 1



   .. py:attribute:: startmonth_winter
      :value: 10



   .. py:attribute:: startmonth_summer
      :value: 4



   .. py:attribute:: hydrological_year
      :value: True



   .. py:attribute:: best
      :value: None



   .. py:attribute:: index_NaN
      :value: []



   .. py:attribute:: index_NA
      :value: []



   .. py:attribute:: nb


   .. py:attribute:: index_isnan


   .. py:attribute:: index_neg


   .. py:attribute:: index_zero


   .. py:attribute:: nodata


   .. py:attribute:: nbneg


   .. py:attribute:: nbzero


   .. py:attribute:: nbnan


   .. py:attribute:: years_bounds


   .. py:attribute:: maxima


   .. py:attribute:: pot


   .. py:attribute:: tz_info


   .. py:method:: check_dupliactes()

      Check if there are duplicates in the data



   .. py:method:: filter()

      Set zero, negative, NaN, Nat to np.nan



   .. py:method:: get_date_max(year, seasons=None) -> list

      Récupère la date du maximum de l'année "year"
      Possibilité de traiter plusieurs saisons



   .. py:method:: get_one_maxevent(year, seasons=None) -> list

      Récupération de l'événement max pour une année spécifique
      Possibilité de traiter plusieurs saisons



   .. py:method:: get_nb_maxevents(nbevents: int, seasons=None) -> dict[str, pandas.DataFrame]

      Récupère les nbevents lus grands pics de crue



   .. py:method:: get_nb_max_hydro(nbevents: int, seasons=None) -> dict[str, pandas.DataFrame]

      Récupère les nbevents plus grands hydrogrammes de crue



   .. py:method:: save_max_events(filename, years_bounds: list = None, seasons=None)

      Enregistrement des crues maximales dans un fichier CSV



   .. py:method:: _select_dict(method: Literal['BM', 'POT'] = 'BM')


   .. py:method:: _get_dates(year=None, hydrol=True, season=None)

      Compute date for current year and season

      :param year: If None, the complete interval will be used. Defaults to None.
      :type year: integer, optional
      :param hydrol: Hydrological year or not. Defaults to True.
      :type hydrol: bool, optional
      :param season: None == 'annual'. Defaults to None.
      :type season: 'annual', 'winter' or 'summer', optional



   .. py:method:: _get_max(year=None, hydrol=True, season=None, method: Literal['BM', 'POT'] = 'BM', threshold=0.0, r: Union[pandas.Timedelta, Any] = '24H')

      Find maxima in specific period



   .. py:method:: get_data_for_one_season(method: Literal['BM', 'POT'] = 'BM', season=None)


   .. py:method:: get_fit_one_season(method: Literal['BM', 'POT'] = 'BM', season=None)


   .. py:method:: save_fit_one_season(filename: str, method: Literal['BM', 'POT'] = 'BM', season=None, fit_method='MLE', sep=';')


   .. py:method:: find_maxima(hydrol=True, excluded_years=[], method: Literal['BM', 'POT'] = 'BM', threshold: float = 0.0, r: Union[pandas.Timedelta, Any] = '24H', verbose=True)

      Find maxima in whole data



   .. py:method:: extract_oneevent(datecenter, before=1, after=2)

      Extract hydrograph around a date

      :param before: number of days before center
      :param after: number of days after center



   .. py:method:: extract_maxevents(before=1, after=2)

      Extract hydrograph for each maximum

      :param before: number of days before maximum
      :param after: number of days after maximum



   .. py:method:: sort_maxima(seasons=None)

      Sort maxima in increasing order to calculate empirical frequency



   .. py:method:: _fit_multistarts(data, fdist, nb=0, method='MLE')

      Fit de la loi en adaptant éventuellement le point de départ
      Ceci n'est sans doute réellement utile que pour la loi de Weibull



   .. py:method:: _evaluate_ci(data, fdist, nboot=500, method='MLE')

      Evaluate confidence interval based on bootstrap method

      REMARK : CI for MLE can be analyzed by Fisher coefficients



   .. py:method:: get_fitted_params(season=None, law='GEV', method='MLE')


   .. py:method:: get_T_from_q(q: list, season: str = 'best', law: str = 'best', method: str = 'MLE', ic=False) -> pandas.DataFrame


   .. py:method:: get_q_from_T(return_periods: list = [5, 10, 15, 20, 25, 50, 75, 100, 200, 500, 1000], season: str = 'best', law: str = 'best', method: str = 'MLE', ic=False) -> pandas.DataFrame


   .. py:method:: save_q_from_T(filename: str = '', return_periods=[5, 10, 15, 20, 25, 50, 75, 100, 200, 500, 1000], season='best', law='best', method='MLE', ic=False)


   .. py:method:: save_T_from_q(filename: str = '', q=[5, 10, 15, 20, 25, 50, 75, 100, 200, 500, 1000], season='best', law='best', method='MLE', ic=False)


   .. py:method:: fit(seasons=None, laws=['GEV'], init_EVA=None, methods=['MLE'], ic=False, nboot=100, verbose=True)

      Fitting of selected laws



   .. py:method:: select_best_func(season, law, method)

      Select one function as best fit



   .. py:method:: distfit(seasons=None, laws='popular', smooth=0, bins=100)

      Laws can be 'full', 'popular'

      ***
      Be carefull, fit of law is based on default scipy.stats parames. In our implementation, non-default initial conditions are used for specific laws, including GEV.
      ***

      https://erdogant.github.io/distfit/pages/html/Parametric.html
      https://erdogant.github.io/distfit



   .. py:method:: set_mixture(laws=['GEV'], methods=['MLE'])

      Set mixture model based on "50-50" "winter-summer" fitted models



   .. py:method:: set_joint(laws=['GEV'], methods=['MLE'])

      Set joint model based on product probability of fitted models



   .. py:method:: set_empfreq(seasons=None)

      Compute empirical frequency based on sorted maxima



   .. py:method:: compute_median_event(seasons=None, before: int = 1, after: int = 2)

      Evaluation de la crue mediane
      Stockage dans "self.maxima[curseason]['median_event']"



   .. py:method:: get_median_event(seasons=None, before=1, after=2) -> dict[str, pandas.DataFrame]

      Get median hydrograph



   .. py:method:: plot_median_event(scale: float, seasons=None, before=1, after=2, fig: matplotlib.figure.Figure = None, ax: matplotlib.axes.Axes = None, color: str = 'red', alpha=1.0) -> tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

      Plot median hydrograph scale by constant



   .. py:method:: plot_classified_flowrate_curve(fig: matplotlib.figure.Figure = None, ax: matplotlib.axes.Axes = None, label='', textvalues=True, show=False) -> tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]


   .. py:method:: plot_distfit(seasons=None, n_top=20, show=False)

      Plots of distfit module



   .. py:method:: plot_ci(seasons=None, laws=['GEV'], methods=['MLE'], fig: matplotlib.figure.Figure = None, ax: matplotlib.axes.Axes = None, show=False, alpha=0.1) -> tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

      Plotting confidence interval



   .. py:method:: plot_annual(years=None, hydrol=True, fig: matplotlib.figure.Figure = None, ax: matplotlib.axes.Axes = None, show=False, withdatemax=True) -> tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

      Tracé en superposition des différentes années sur l'emprise d'une année civile ou hydrologique



   .. py:method:: plot_serie(fig: matplotlib.figure.Figure = None, ax: matplotlib.axes.Axes = None, show=False, background=True, backcolor='lemonchiffon') -> tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

      Tracé de l'ensemble de la série pour toutes les années



   .. py:method:: plot_cdf(seasons=None, fig: matplotlib.figure.Figure = None, ax: matplotlib.axes.Axes = None, show=False, n_bins=100) -> tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

      Plotting empirical cdf



   .. py:method:: plot_T_Qmaxima(seasons=None, empirical_func='Cunnane', fig: matplotlib.figure.Figure = None, ax: matplotlib.axes.Axes = None, show=False, alpha=1.0, color_marker_label=None) -> tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

      Plotting Q vs return period



   .. py:method:: plot_maxevents(seasons=None, before=1, after=2, adim=True, fig: matplotlib.figure.Figure = None, ax: matplotlib.axes.Axes = None, show=False, alpha=0.2, nbevents=None) -> tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

      Tracé des événements/hydrogrammes associés aux maxima identifiés
      Les ordonnées sont adimensionnaliées sur base de la valeur maximale



   .. py:method:: plot_comp_maxevents(seasons=None, before=1, after=2, fig: matplotlib.figure.Figure = None, ax: matplotlib.axes.Axes = None, show=False, alpha=0.2, nbevents=None) -> tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

      Tracé des événements médians
      Les ordonnées sont adimensionnaliées sur base de la valeur maximale



   .. py:method:: plot_one_event(datecenter, before=1, after=2, adim=True, color='k', fig: matplotlib.figure.Figure = None, ax: matplotlib.axes.Axes = None, show=False, alpha=0.2) -> tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

      Tracé d'un événement quelconque autour d'une date



   .. py:method:: plot_one_maxevents(season, year, before=1, after=2, adim=True, color='k', fig: matplotlib.figure.Figure = None, ax: matplotlib.axes.Axes = None, show=False, alpha=0.2) -> tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

      Tracé d'un événement spécifique associés au maxima identifié
      Les ordonnées sont adimensionnaliées sur base de la valeur maximale



   .. py:method:: plot_fit(seasons=None, laws=['GEV'], methods=['MLE'], fig: matplotlib.figure.Figure = None, ax: matplotlib.axes.Axes = None, show=False, alpha=1.0, styles: dict = None) -> tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

      Plotting fitted models



   .. py:method:: plot_qq(seasons=None, laws=['GEV'], methods=['MLE'], fig: matplotlib.figure.Figure = None, ax: matplotlib.axes.Axes = None) -> tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

      Q-Q Plot

      Comparaison de la valeur théorique avec la mesure (attention scipy.probploit n'utilise pas Cunnane mais Filliben cf https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.probplot.html)



   .. py:method:: plot_summary(seasons=None, nb_laws=None, forced_laws=[], sort: Literal['RSS', 'AICc', 'AIC', 'BIC'] = 'RSS', fig: matplotlib.figure.Figure = None, ax: matplotlib.axes.Axes = None, show=False) -> tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

      Plot summary results.

      :param n_top: Show the top number of results. The default is None.
      :type n_top: int, optional
      :param figsize: The figure size.
      :type figsize: tuple, optional (default: (10,8))
      :param ylim: Limit figure in y-axis.
      :type ylim: Float, optional (default: None)
      :param fig: Matplotlib figure
      :type fig: Figure, optional (default: None)
      :param ax: Matplotlib Axes object
      :type ax: Axes, optional (default: None)

      :rtype: tuple (fig, ax)



   .. py:method:: summary_max(seasons=None)


.. py:class:: EVA_Series(data, datetime_index=None, datetime_format='%Y%m%d%H%M%S', data_headers=('#DateHeure', 'Debit'), startmonth_winter=10, startmonth_summer=4, hydrol=True)

   .. py:attribute:: base_serie


   .. py:attribute:: all_series
      :type:  dict[str, EVA_Serie]


   .. py:attribute:: MFSH


   .. py:attribute:: hydrological_year
      :value: True



   .. py:attribute:: startmonth_winter
      :value: 10



   .. py:attribute:: startmonth_summer
      :value: 4



   .. py:attribute:: _current_serie


   .. py:method:: activate_serie(key: int = 1)


   .. py:method:: plot_T_Qmaxima(seasons=None, empirical_func='Cunnane', fig: matplotlib.figure.Figure = None, ax: matplotlib.axes.Axes = None, show=False, alpha=1.0, color_marker_label=None) -> tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]


   .. py:method:: plot_fit(seasons=None, laws=['GEV'], methods=['MLE'], fig: matplotlib.figure.Figure = None, ax: matplotlib.axes.Axes = None, show=False, alpha=1.0, styles: dict = None) -> tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]


   .. py:method:: get_q_from_T(return_periods: list = [5, 10, 15, 20, 25, 50, 75, 100, 200, 500, 1000], season: str = 'best', law: str = 'best', method: str = 'MLE', ic=False) -> pandas.DataFrame


   .. py:method:: get_T_from_q(q: list, season: str = 'best', law: str = 'best', method: str = 'MLE', ic=False) -> pandas.DataFrame


   .. py:method:: save_q_from_T(filename: str = '', return_periods=[5, 10, 15, 20, 25, 50, 75, 100, 200, 500, 1000], season='best', law='best', method='MLE', ic=False)


   .. py:method:: save_T_from_q(filename: str = '', q=[5, 10, 15, 20, 25, 50, 75, 100, 200, 500, 1000], season='best', law='best', method='MLE', ic=False)


   .. py:method:: get_serie(key=1) -> EVA_Serie


   .. py:method:: find_maxima(excluded_years=[], hydrol=True, method: Literal['BM', 'POT'] = 'BM', threshold: float = 0.0, r: Union[pandas.Timedelta, Any] = '24H', verbose=True)

      Recherche des maxima pour toutes les saisons et toutes les durées



   .. py:method:: create_all_durations(durations=[1], verbose=True)

      Création des chroniques pour toutes les durées souhaitées [heures]



   .. py:method:: bake_data(durations=[1], excluded_years=[], hydrol=True, method: Literal['BM', 'POT'] = 'BM', threshold: float = 0.0, r: Union[pandas.Timedelta, Any] = '24H', verbose=True)


   .. py:method:: plot_series(durations=None, oneyear=True, show=False, background=True, backcolor='lemonchiffon')

      Viauslaisation des chroniques



   .. py:method:: plots_spw(stationcode: str, fontsize: int = 12, width=20, height=10, durations=[1], backcolor='lemonchiffon')


   .. py:method:: eva(durations=[1], laws='popular', hydrol=True, excluded_years=[], plot=True, method: Literal['BM', 'POT'] = 'BM', threshold: float = 0.0, r: Union[pandas.Timedelta, Any] = '24H', verbose=True, show=False) -> dict[str, tuple]

      Extreme Value Analysis

      durations : (list) durations in hours - default [1]
      laws : (str) laws to fit - default 'GEV'
      hydrol : (bool) use hydrological year - default True
      excluded_years : (list) years to exclude
      plot : (bool) creation of different plots
      method : (str) selection of maxima - default 'BM' == Block Maxima

      return : dict of tuples (fig,axes) of the plots



   .. py:method:: evaluate_ci(seasons=None, durations=[1], laws=['GEV'], nboot=100, show=False) -> dict

      Intervalles de confiance

      Retourne une liste contenant des tuples (fig,ax) pour chaque durée et chaque saison

      La boucle principale est sur les durées
      La boucle interne est sur les saisons



   .. py:method:: evaluate_ic(seasons=None, durations=[1], laws=['GEV'], nboot=100, show=False) -> dict

      alias evaluate_ci



   .. py:method:: test_distfit(durations=[1], plot=True)

      Ajustement de lois avec la toolbox distfit



   .. py:method:: plot_qdf(seasons=None, durations=None, law='GEV', show=False)

      Graphique de toutes les relations fittées pour chaque durée sur une même figure



   .. py:method:: select_best_func(season='mixture', law='GEV', method='MLE')

      Sélection de la fonction à retenir comme meilleur ajustement



   .. py:method:: get_one_MFSH(rising_time: float = 6.0, return_period: float = 50.0, deltat: float = 1.0) -> wolfhece.eva.hydrogramme_mono.Hydro_HSMF


   .. py:method:: opti_mfsh(label, rising_time=6, return_period=[2, 5, 10, 25, 50, 100, 200, 500, 1000], deltat=1)

      #############################
      ## CALCUL DES HYDROGRAMMES ##
      #############################



   .. py:method:: plot_msfh(label, return_period=[2, 5, 10, 25, 50, 100, 200, 500, 1000], ref_season='annual', ylim=None, before=1, after=3, show=False) -> tuple[matplotlib.figure.Figure, matplotlib.axes.Axes, matplotlib.axes.Axes]

      ################
      ## GRAPHIQUES ##
      ################



   .. py:method:: plot_msfh_mainplot(label, return_period=[2, 5, 10, 25, 50, 100, 200, 500, 1000], ref_season='annual', ylim=None, before=1, after=2, show=False) -> tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

      ################
      ## GRAPHIQUES ##
      ################



   .. py:method:: save_max_event(filename: str, years_bounds: list, seasons=None)


   .. py:method:: save_msfh(label, filename, return_period=[2, 5, 10, 25, 50, 100, 200, 500, 1000])

      ################
      ## SAUVEGARDE ##
      ################



   .. py:method:: plot_one_fit(seasons=None, durations=None, laws='popular', split_duration=True, split_season=True, xbounds=None, ybounds=None, show=False) -> tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]


   .. py:method:: print_summary(seasons=None, durations=None, show=False)


   .. py:method:: plot_selected_max(seasons=None, durations=None, split_seasons=False, scaling=False, show=False) -> tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

      Graphique des dates des événements sélectionnés pour chaque durée (par défaut, toutes les durées)



.. py:function:: example1()

.. py:function:: example1bis()

.. py:function:: example2()

.. py:function:: example3()

.. py:function:: example4()

.. py:function:: example5()

.. py:function:: example6_POT()

.. py:data:: strPath
   :value: b'.'