home.md

+This is a demo tool developped in Python mainly to illustate basic notions in frequential analysis in Hydrology, with the example of annual maximum discharges, denoted QY. It involves matplotlib widgets implementation (sliders) of toolbar customisation.
+
+The authors share this code because it might be helpful to others although it can (and will) be improved.
+Please feel free to send feedback.
+
+Note : the icons do not appear on the toolbar for Linux users and the "menu" button of the toolbar does not work , but it only displays what the other tools do... 
+
+Poulard Christine et Leblois Etienne, Inrae, Unité de recherche Riverly 
+
+
+## about Hydrology :
+This demo tool was initially designed for a first contact with frequential analysis in hydrology, Master level (french Engineering School).
+Let us consider the maximal flood discharge of each year, QY (max in a calendar year or, better, hydrological year), and let us assume this variable follows a known Gumbel distribution (the assumption is correct for return period under a given thresholk, largely ex...).
+
+Initial figure : sample of 10 QY
+     The sample corresponding to 10 years of observation is represented as a time-series and with plotting positions in another graph with respect to the return period, denoted T, where a Gumbel distribution fitted on the sample is compared to the "theoretical" Gumbel one.
+ to estimate the "right" Gumbel distribution parameters.  Of course, withe only a few years of obervation the QY(T) relationship estimated by fitting Gumbel parameters has no reason to be very good ; the Confidence Interval is very thick at first.
+
+### :tools:  tools added in the TOOLBAR 
+added TOOLBAR icons :
+:warning:  :mouse_three_button: clicking is sometimes annoying ; move your mouse on the upper half of the icons (you should see the "hint" when hovering in the proper area)
+
+
+- :stop_button: icon MENU : a very brief summary of the functions of the added tools
+- :stop_button: icon "+ 10" :  add 10 new obs, see how the estimated Gumbel graph evolves (the estimated Gumbel should be closer to the theoretical one). 
+     Only the 10 highest values are represented with a marker "X" in the graph, to compare with the sample plotted uing plotting positions
+- :stop_button: icon "NEW" : starts with a new 10-year observation series
+Check with several tries the variability of the samples and resulting estimated QY(T). However, the plotting position remains identical with any 10-year sample (it is obvious, they only depend on the RANK of the observations, but this code illustrates this.
+- :stop_button: icon "write QT" : write in Python console current numerical values of QY samples and the related T (plotted positions, Gumbel estimates), as well as fresquencies
+- :stop_button: icon  frequency <=> return period : toggles the x axis of the 2nd graph between frequency and return period. Frequency is interesting to better understant plotting position theory.
+- :stop_button: icon  C.I. : shows/hide Confidence Intervals for Estimated Gumbel distribution.
+
+
+### :tools:  slider widgets
+Sliders allow to modify a and b parameters of the plotting position formula. Defaults value are Chegodayev's parameters. 
+
+### Differences between this code and a real-life hydrological analysis... 
+Annual Maximum are interesting as a first contact with flood frequency analyses, but for real studies "Peak-Over-Threshold" sampling is recommanded.
+Also, as stated in the introduction, the Gumbel distribution is widely used in hydrology, but it is not valid for extreme floods. This is why in the graphs the confidence intervals do not go further than T=100 years and the x axis in return period is limited in range, eventhough highest observed values are out of the graph. To see them all, toggle to "x axis as frequency" (and back...).
+ 
+
+### Todo list... 
+:moneybag: :money_with_wings: It is planned to add damage to each flood, through a damage-frequency relationship, and to plot the average damages on a given duration so as to illustrate the variability of damages on a restricted set of observations.
+ 
+Maybe a fork with POT Sample generation (with fitted exponential law) can be proposed.
+Other tools are developped to sample and process real data (as time series) with both annual maxima and POT methods. The use of pandas for coding has the advantage of yielding very readable code, but "default" arguments of resample methods are sometimes questionable ; a tool should be on line soon, with a control of missing values (to validate sampled peak or aggregation for multiduration analysis).
+
+
+### Main references
+ 
+[Renard Benjamin, Probabilités et Statistiques appliquées à l'Hydrologie](https://cel.archives-ouvertes.fr/hal-02597049/), 90 p (in french)
+Inrae UR HHLY - Hydrologie-Hydraulique (now at Inrae Riverly)
+
+
+Poulard Christine et Leblois Etienne, Inrae, Unité de recherche Riverly Dimensionnement d’un aménagement de gestion des inondations, Cours de Sciences de l’eau , 19 p. (in French)
+
+
+
+## about Python : matplotlib as a robust visualization tool, using plot, scatter, stem...
+   Features that can be interesting :
+#### multiple plots, with gridspec.GridSpec &  height_ratios
+#### custom legend to show color code of QY sample with respect to "theoritical" quantile (top graph), placed in a specific subplot
+#### legend of 2nd graph placed in another subplot in order not to hide plots 
+#### use of matplotlib widgets (Slider) : not as good as Tkinter of PyQT, but easier and handy for a little demo [see matplotlib doc](https://matplotlib.org/stable/api/widgets_api.html)
+#### add tools to mpl toolbar [see matplotlib doc](https://matplotlib.org/stable/api/backend_tools_api.htm)
+#### plots updates with set_data (update is not as easy for graphs other than "plot", the others were simply "removed" and redrawn
+