Bag_of_Floods.md

+
+This project ":moneybag: bag of floods" is a spinoff of its French counterpart ":flag_fr: Sac de Crues". 
+It started in jan. 2023 and will gradually catch up with the french projet.
+
+[TOC]
+
+Of course, every app needs its doc.
+The translation of the french wiki will take some time, but a summary is due soon. We trust that professionnals working in the field of flood management will be able to use it already.
+
+### First step : draw marbles from a bag to help understand flood probabilities... and use an app to mimick series of draws
+So far, we are working the first step of the project : help to convey messages about **flood probability on a given year** and  **on N years**, because you don't buy a house or design a flood mitigation project for one year.
+
+#### Tools : a real bag... and an app
+This can be achieved by drawing from a bag marbles colour-coded with respect to their probability. How can this colour be understood as this year's flood return period ? 
+
+This stage is the opportunity to discuss these notions, and understand that colors represent a class of return periods.
+
+- **90 black marbles** on a total of 100 marbles : they are drawn on average 9 times out of 10. If we think of floods, 9 floods in ten years are "SMALLER" THAN the 10-yr return period flood. 
+
+- the **remaining 10 marbles** represent therefore floods "BIGGER" THAN the 10-yr return period flood. 
+
+Among these 10 marbles : 
+- $`\textcolor{red}{ \text{a single red marble}}`$ represents  : $`\textcolor{red}{ \text{ floods with a return period OVER 100-yr.}}`$ 
+In other words, the red marble represents the 1% highest floods, so it does not represent a "100-yr flood" but all the floods above it. This means that the "100-yr flood" is not occurring once in 100 years, as such, but it represents a level EXCEEDED once in 100 years.
+- $`\textcolor{blue}{ \text{a single blue marble}}`$  represents floods with a return period between the 50-yr and the 100-yr return period.Explanation : the 50_yr return period flood has a probability to be exceeded of 1/50, which is 2/100, but the red marble already represents the class of floods above the 100-yr flood. It means that we need only one marble more, representing the floods above the 50-yr one but under the 100-yr one (the floods above are already represented by the red one)
+- $`\textcolor{green}{ \text{the 8 green marbles}}`$ mean floods with a return period between the 10-yr and the 50-yr return period. Explanation : The 10-yr return period flood has an exceedance probability of 1/10, which is 10/100, but the red and blue marbles already represents the floods above the 50-yr flood. It means that we need 8 marble more, representing the floods above the 10-yr one but under the 50-yr one.
+
+:bulb: probability can only be used for classes of floods. Keep in mind that :
+- the **exceedance probability** of the "N-yr return period flood" is **one in N**.
+- therefore, the probability to have a flood between the N-yr and the M-yr flood, with N < M,  is : $`(\frac 1 N - \frac 1 M)`$
+
+
+<details><summary>definition of exceedance</summary>
+Probability of exceedance is a statistical metric describing the probability that a particular value will be met or exceeded.
+https://www.sciencedirect.com/topics/engineering/exceedance
+</details>
+
+We can also begin to discuss how we can "order" floods (we can sort discharges, but not so easily flood events), and if a flood event really has a return period strictly speaking.
+
+After this, we can move on to series of N years, and for this an app is very useful to automatically generate series of "floods". 
+
+The HTML version is not yet as complete as the Python code (in French only so far), but it does provide the results of N draws visually (one token per drawn marble) and as stats (number and empirical frequency for each colour). HTML has the huge advantage to be easier for anyone to use : just download the file and drag-and-drop it in your browser's navigation bar !
+
+
+### Other parts of the project not yet available in English :disappointed: 
+The french "Sac de Crues" project also offers small apps and texts to discuss:
+- interpretation of probabilistic floodmaps with several flood extent maps overlayed one atop the other (more tricky than it seems if the legend is deceivingly simple ! ) ;
+- understanding Gumbel distributions (for students and professionnals) and the confidence intervals.
+
+### Available apps : "bag of flood" as `".html"` files
+Two versions are available.
+
+`bag_of_floods.html` : in the [`Bag_of_floods_Simple` directory](https://gitlab.irstea.fr/hydrotools_demosandprocessing/bag-of-floods/-/tree/main/Bag_of_floods_Simple). Simple version, buttons at the top and conclusions under the history. Only "round" tokens.
+	
+This first and simplest app also works on mobile phones ; it consists in :
+- at the top : a few buttons to draw one or a series of N marbles ;
+- coloured circle for each past draws ;
+- underneath : a few lines to sum up the stats of past draws.
+
+Another version is [now proposed](https://gitlab.irstea.fr/hydrotools_demosandprocessing/bag-of-floods/-/tree/main/Bag_of_floods_under_developpement), with a better layout to see all information, and additionnal features like :
+- explanations about bag composition and links to this wiki ;
+- stats about past draws in a table (on the left) ;
+- choice between three shapes for the tokens : circles, ticks (or crosses) and "event-like" shapes with one or two peaks.
+It is still under development, and does not currently work on a mobile device.
+
+Screenshots of the simple version :
+
+![image](uploads/1520955d3ab882a2e409c515ddebe7e7/image.png)
+
+![image](uploads/8094e55e77b441c1cd96a25b1ab67fc1/image.png)
+
+Second version, with "pseudo-events' (simplified hydrograph shapes)
+
+![image](uploads/32e7745b86b1c28e3faacbba97a7b6c4/image.png)
\ No newline at end of file