Merge pull request #50 from Deltares-research/feature/gebruikershandl…

…eiding-dashboard

Feature/gebruikershandleiding dashboard

vrtool_docs/Achtergronden/Optimalisatie/BepalingTrajectfaalkansen.rst

@@ -22,11 +22,11 @@ Hierbij correspondeert :math:`P_1` met de kans bij onafhankelijkheid tussen vakk
        :width: 100%
        :class: borderless
 
-       * - .. image:: img/EqualComponents.png
+       * - .. figure:: img/EqualComponents.png
               :width: 100%
               :alt: Equal Components
 
-         - .. image:: img/UnequalComponents.png
+         - .. figure:: img/UnequalComponents.png
               :width: 100%
               :alt: Unequal Components
 

vrtool_docs/Gebruikershandleiding/Postprocessing/BerekeningenMetDashboard.rst

@@ -1,4 +1,60 @@
 Berekeningen aansturen via het dashboard
 ========================================
-*Volgt na release van versie 1.0.0*
 
+Vanuit het dashboard kunnen nieuwe berekeningen worden aangestuurd. Daarvoor moet eerst een database met resultaten van een basisberekening worden geïmporteerd. Vervolgens kan met het dashboard een nieuwe berekening worden geconfigureerd. De pagina hiervoor is te benaderen door bovenin bij `paginas` te kiezen voor `Draaien optimalisatieberekeningen`. Zie ook onderstaand screenshot.
+
+.. figure:: img/berekening_dashboard_1.png
+    :width: 50%
+    :align: center
+
+Aan- en uitzetten van maatregelen
+----------------------------------
+
+Via het tabblad `Run Optimize` kan met de knoppen een nieuwe berekening worden geconfigureerd. In onderstaand voorbeeld is bijvoorbeeld aangegeven dat op dijkvak 3 alleen een grondversterking kan worden uitgevoerd, en op dijkvakken 4 t/m 8 geen versterking. Op dijkvak 3 kan ook alleen in het jaar 2030 worden versterkt.
+
+.. figure:: img/instellingen_dashboard_berekening.png
+    :width: 100%
+    :align: center
+
+De berekening is `Aangepaste optimalisatie v0.1` genoemd. De berekening kan worden gestart door op de knop `Start optimalisatieberekening` te klikken. De berekening wordt nu gestart en de voortgang is te volgen in de live logging. Een berekening kan enige tijd duren, de voortgang wordt gelogd in een pop-up scherm zoals hieronder weergegeven. Hier is bijvoorbeeld te zien dat er in stap 2 van de berekening een maatregel is gekozen met een BC-ratio van 11381.77.
+
+.. figure:: img/live_logging.png
+    :width: 50%
+    :align: center
+
+.. tip::
+    Met name het importeren van alle gegevens kan even tijd kosten. Daardoor kan het soms even duren voordat er logging verschijnt. Dat betekent echter niet dat er niets gebeurt op de achtergrond.
+
+De duur van de berekening is sterk afhankelijk van de computer waarop deze wordt uitgevoerd, en het aantal maatregelen en dijkvakken dat wordt meegenomen in de berekening. In het algemeen duurt het optimalisatiedeel van de berekeningen wel meer dan 5 minuten per analyse (tot circa 1 uur voor trajecten met veel dijkvakken en maatregelen). Een berekening is klaar als dit wordt aangegeven in het venster, en als er in het tabblad in de browser geen `updating...` meer staat.
+
+.. tip::
+    Het draaien van een berekening vanuit het dashboard kan alleen worden uitgevoerd als eerst in ieder geval ``measures`` is doorgerekend omdat er gegevens over de maatregelen beschikbaar moeten zijn. Zie ook `hier <../VRTool/index.html#uitvoeren-van-een-berekening>`_.
+
+Het draaien van aangepaste berekeningen kan handig zijn wanneer:
+
+* Met een specifiek versterkingsjaar moet worden gerekend (voor bepaalde dijkvakken). Het kan dan inzicht geven in de mate waarop de timing van de maatregelen de maatregelen op het betreffende vak of andere vakken beïnvloedt.
+* Een specifieke maatregel moet worden uitgezet of afgedwongen. Dit kan bijvoorbeeld zijn omdat een maatregel niet mogelijk is door beperkingen die niet anderszins worden meegenomen, of omdat vanuit omgeving juist een specifiek type maatregel wenselijk is.
+* Men wil kijken naar het beperken van de geografische scope door specifieke dijkvakken uit te zetten en daarmee uit te sluiten van versterking.
+
+
+Werken met custom maatregelen
+-----------------------------
+Naast het rekenen met de standaard maatregelen is het ook mogelijk om met custom maatregelen te rekenen. Dit kan bijvoorbeeld handig zijn wanneer er een specifieke maatregel moet worden meegenomen die niet in de standaard set zit. Denk aan een specifieke maatwerkoplossing op een bepaald dijkvak. Custom maatregelen kunnen worden ingevoerd in het tabblad ``Custom maatregelen``. Hier is een tabel zichtbaar zoals in onderstaande figuur. In dit geval zijn er 2 custom maatregelen ingevoerd: maatregel `Test 1` op dijkvak 1, en `Test 2` op dijkvak 2.
+
+.. figure:: img/custom_measure_interface.png
+    :width: 80%
+    :align: center
+
+Voor beide maatregelen zijn kosten & betrouwbaarheid ingevoerd. Voor de kosten geldt dat bij `Test 1` 2 verschillende bedragen zijn ingevoerd. In dat geval neemt de VRTOOL het hoogste bedrag. Voor de betrouwbaarheid wordt de betrouwbaarheid van de maatregel ingevoerd voor verschillende jaren en mechanismen. Daarbij worden de getallen in de tabel geinterpreteerd als in onderstaande figuur. Wanneer niets wordt ingevoerd wordt aangenomen dat de betrouwbaarheid gelijk blijft. Custom maatregelen worden niet gecombineerd met andere maatregelen.
+
+.. figure:: img/custom_measure_concept.png
+    :width: 80%
+    :align: center
+
+De custom maatregelen zijn terug te vinden door de SQLite te openen in een database viewer. In de tabel ``CustomMeasureDetail`` zijn de ingevoerde waarden te zien. In de tabellen ``MeasureResultMechanism`` en ``MeasureResultSection`` is te zien hoe de betrouwbaarheidsindex en kosten zijn geinterpreteerd. 
+
+.. figure:: img/custom_measure_sqlite.png
+    :width: 80%
+    :align: center
+
+Bij het toevoegen van custom maatregelen wordt altijd een backup gemaakt van de bestaande database om te voorkomen dat de originele resultaten verloren gaan. Deze zijn terug te vinden in de folder van de originele database.

vrtool_docs/Gebruikershandleiding/Postprocessing/ProgrammerenVersterkingen.rst

@@ -0,0 +1,105 @@
+Analyse op gebiedsniveau
+=========================
+
+Met het scherm voor een `Analyse op gebiedsniveau` kan voor 1 of meerdere trajecten een programmering worden gemaakt van dijkversterkingsprojecten. Doel daarbij is om inzicht te geven in de kosten (in de tijd) en het verloop van het risico/afstand tot de norm. De basis van de analyse zijn veiligheidsrendementberekeningen. Er zijn twee hoofdpagina's: `Definitie van projecten` en `Resultaten op gebiedsniveau` die hieronder worden toegelicht.
+
+Definitie van projecten
+------------------------
+
+Importeren van berekeningen
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Deze pagina is als eerste zichtbaar bij het openen van het scherm voor een analyse op gebiedsniveau. De eerste stap is om 1 of meerdere dijktrajecten te laden (d.m.v. bij de analyse op trajectniveau opgeslagen json-bestanden). Er kan 1 json-bestand per traject worden gebruikt. Wanneer een nieuwe wordt geladen, wordt de oude vervangen.
+
+Het is ook mogelijk om een compleet json-bestand inclusief projectdefinities te laden, dat wordt toegelicht in de volgende paragraaf.[ref?]
+
+In het deel `Geimporteerde berekeningen` is zichtbaar voor welk traject welke berekening beschikbaar is. In dit scherm wordt alleen gerekend met de resultaten van veiligheidsrendement, niet van de berekening op basis van doorsnede-eisen.
+
+.. tip::
+    Het is mogelijk om het json-bestand van een andere berekening te laden, ook wanneer er al projecten zijn gedefinieerd. Let dan wel op dat de vakindeling van beide berekeningen hetzelfde is, anders kunnen de projecten niet meer worden gekoppeld aan het traject.
+
+Aanmaken van projecten
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Bij `Overzicht projecten` kan een nieuw project worden aangemaakt, of een bestaand project worden aangepast of verwijderd. Dit wordt gedaan door een (unieke) naam toe te voegen voor het project, en dijkvakken te selecteren die onder dit project vallen. Daarnaast moet een startjaar en eindjaar worden opgegeven: de kosten van het project (conform veiligheidsrendement) worden uitgesmeerd over deze periode.
+
+.. tip:: 
+    Wanneer een dijkvak wordt geselecteerd wat al in een ander project voorkomt geeft dit een foutmelding. Het is niet mogelijk om een dijkvak in meerdere projecten te hebben. Het vak moet dan eerst uit het andere project worden verwijderd. Of het andere project kan volledig worden verwijderd met de knop 'Verwijder project'.
+
+In onderstaande figuur is een voorbeeld van het maken van een project weergegeven. 
+
+.. figure:: img/gebiedspagina_project_maken.png
+    :width: 80%
+    :align: center
+
+In dit voorbeeld is voor het project `Test project` een drietal dijkvakken geselecteerd in traject 10-3 (zie pop-up). Het project start in 2025 en eindigt in 2031. Wanneer nu op `Maak project` wordt geklikt wordt het project toegevoegd aan de lijst met projecten, óf wordt een foutmelding gegeven als de betreffende vakken al onderdeel zijn van een ander project. Op deze wijze kunnen meerdere projecten worden gedefinieerd. 
+
+Weergave van trajecten en projecten
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Aan de rechterkant is een kaart zichtbaar met daarop de geladen trajecten en daar kunnen 4 weergaven worden gekozen die kunnen helpen bij het definieren van projecten. 
+Er zijn 4 weergavemogelijkheden:
+
+* Trajecten
+* Projecten
+* Faalkans 2025
+* VR index
+
+Met de keuze voor `Trajecten` worden de geladen trajecten weergegeven, én wordt in rood weergegeven welke dijkvakken zijn geselecteerd bij het project wat wordt aangemaakt. In onderstaand voorbeeld zijn bijvoorbeeld de dijkvakken 1, 2 en 4 op traject 10-3 in rood weergegeven.
+
+.. figure:: img/gebiedspagina_project_maken_trajecten.png
+    :width: 80%
+    :align: center
+
+Door te kiezen voor `Projecten` worden alle gedefinieerde projecten overzichtelijk weergegeven. 
+
+.. figure:: img/gebiedspagina_project_maken_projecten.png
+    :width: 80%
+    :align: center
+
+In bovenstaand voorbeeld zijn de gedefinieerde projecten te zien. Daarbij is ook te zien welke dijkvakken geen onderdeel zijn van een dijkversterking. Wanneer dijkvakken niet worden toegedeeld aan een project worden deze niet versterkt, en blijven dus op hun huidige veiligheidsniveau. Dit kan worden weergegeven door de weergave `Faalkans 2025` te selecteren. Daarbij wordt voor elk vak de faalkans weergegeven in het jaar 2025. Wanneer zwakke vakken niet versterkt worden betekent dit dat het traject onveilig blijft. Het is dus van belang om dergelijke vakken toe te voegen aan een van de projecten om het risico effectief te verlagen.
+
+Die effectiviteit kan ook in beeld worden gebracht middels de `VR index`. In die weergave wordt een index berekend die het veiligheidsrendement per dijkvak weergeeft. Een voorbeeld is te zien in onderstaande figuur.
+
+.. figure:: img/gebiedspagina_vrindex.png
+    :width: 80%
+    :align: center
+
+Hierbij geldt dat hoge waarden corresponderen met een hoog veiligheidsrendement: in dit geval bijvoorbeeld de dijkvakken in de buurt van Hasselt. Zwarte delen zijn delen die niet worden versterkt (in principe hebben deze een heel laag veiligheidsrendement). Omdat het veiligheidsrendement zeker voor de zwakke vakken sterk wordt bepaald door het risico zullen vakken met een hoge VR index meestal ook een hoge faalkans hebben. De wijze van berekenen van de VR index is in hoofdstuk 4 van de handreiking nader toegelicht.
+
+Resultaten op gebiedsniveau
+---------------------------
+
+Overzicht van projecten
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Wanneer alle gewenste projecten zijn gedefinieerd kan de effectiviteit van het programma worden geanalyseerd in het scherm `Resultaten op gebiedsniveau`. Een overzicht daarvan is gegeven in onderstaande figuur.
+
+.. figure:: img/gebiedspagina_resultaten_overzicht.png
+    :width: 100%
+    :align: center
+
+In het midden is een kaart zichtbaar met daarop de gedefinieerde projecten. Daaronder is een tabel weergegeven met de projecten, en een aantal eigenschappen: aantal dijkvakken, start- en eindjaar, lengte van de versterking en de kosten op basis van de veiligheidsrendementberekening. De kolommen `Faalkans beoordeling` en `Faalkans na versterking` geven de faalkans in het jaar 2025 weer voor de huidige situatie en na uitvoeren van de versterkingsmaatregelen. Let op: het betreft hier enkel de faalkans van de dijkvakken die onderdeel zijn van het project! 
+
+Informatie over faalkans, risico en cashflow
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In het rechterdeel van het scherm wordt informatie gegeven over de kosten van de verschillende projecten in de tijd. Daarbij worden kosten evenredig verdeeld tussen start- en eindjaar. Dit kan helpen bij het bepalen van de capaciteit die nodig is voor de uitvoering van de projecten, en de cashflow die daarbij hoort. Door te schuiven met projecten kan de cashflow beter verdeeld worden in de tijd. In dit geval is er bijvoorbeeld een gat tussen 2031 en 2035, wat zou kunnen worden opgevuld door 1 van de projecten tussen 2025 en 2031 naar achteren te schuiven, of een van de andere projecten naar voren te halen.
+
+In de figuur er onder kan per traject worden gekeken wat het verloop van de veiligheid in de tijd is. Daarbij kan worden gekozen voor een weergave in betrouwbaarheidsindex, trajectfaalkans, afstand tot de norm (hoog getal = onvoldoende veilig) of 2 indicatoren voor het overstromingsrisico. Bij het kiezen voor `Risico` wordt het (niet-verdisconteerde) overstromingsrisico per jaar weergegeven. Bij de `Risico factor` wordt dit gedaan door het risico te delen door het risico wanneer de trajectfaalkans gelijk is aan de ondergrens. In onderstaande figuur is als voorbeeld de faalkans in de tijd weergegeven.
+
+.. figure:: img/gebiedspagina_faalkansen.png
+    :width: 80%
+    :align: center
+
+Te zien is dat de faalkans stapsgewijs afneemt tot deze uiteindelijk voor alle trajecten in 2050 voldoet aan de ondergrens. Tegelijkertijd is er nog ruimte om eerder aan de faalkanseis te voldoen. Dit kan bijvoorbeeld door de twee laatst uitgevoerde projecten eerder uit te voeren. 
+
+Linksboven wordt voor de huidige programmering een overzicht gegeven van de totale versterkingskosten en het risico in de jaren 2030, 2040, 2050 en 2075. Dat laatste wordt berekend door het risico van de afzonderlijke trajecten op te tellen. Er wordt dus aangenomen dat het risico van de trajecten onafhankelijk is.
+
+Wat blijkt uit deze programmering is dat het risico relatief lang vrij hoog blijft. Een mogelijkheid om dit te verlagen is om de als laatste uitgevoerde projecten naar voren te halen. In onderstaande figuur is te zien dat dit leidt tot een fors lager risico in 2040: van 295 M€/jaar naar ... M€/jaar.
+
+.. figure:: img/gebiedspagina_risico_origineel.png
+    :width: 50%
+    :align: center
+    :alt: Risico in 2040 bij de originele en aangepaste (nog toevoegen) programmering
+
+    Links risico in originele programmering, rechts risico in aangepaste programmering (nog toevoegen)

vrtool_docs/Gebruikershandleiding/Postprocessing/VergelijkenOptimalisatieberekeningen.rst

@@ -0,0 +1,65 @@
+Vergelijken van optimalisatieberekeningen
+=========================================
+
+Via het scherm ``Vergelijken berekeningen`` kunnen verschillende berekeningen van hetzelfde (of een ander) traject met elkaar worden vergeleken. Dit kan worden gedaan door 2 of meer ``json``-bestanden die geëxporteerd zijn bij de `analyse per traject <WeergevenResultaten.html#exporteren-van-resultaten>`_ te selecteren. Deze zijn vervolgens zichtbaar in het linkerpaneel.
+
+.. figure:: img/vergelijken_berekeningen_geladen.png
+    :width: 80%
+    :align: center
+
+
+.. warning::
+    Het is mogelijk om berekeningen van verschillende trajecten te vergelijken, maar dit kan leiden tot onverwachte resultaten. Het is daarom aan te raden om enkel berekeningen van hetzelfde traject met elkaar te vergelijken, dat is in principe waar deze pagina voor is gemaakt.
+
+Bovenin het rechterpaneel kan een aantal weergaves worden geselecteerd. Deze weergaves worden hieronder kort toegelicht.
+
+Resultaten optimalisatie
+------------------------
+Met het scherm ``Resultaten optimalisatie`` kunnen de resultaten van de optimalisatieberekeningen worden vergeleken. Hierbij worden de resultaten van de veiligheidsrendementberekeningen van de verschillende invoerbestanden weergegeven in termen van kosten en betrouwbaarheid/faalkans. Dit is met name zinvol om 2 scenario's (bijv. voor verschillende maatregelen, of verschillende beoordelingsinvoer) te vergelijken op resulterende faalkans en kosten.
+
+.. figure:: img/vergelijken_berekeningen_optimalisatie.png
+    :width: 80%
+    :align: center
+
+.. tip::
+    Wanneer er veel verschillende invoerbestanden worden geladen kan de figuur wat onoverzichtelijk worden. Door in de legenda op een van de items te klikken kan deze worden uitgezet. Dit kan helpen om de figuur overzichtelijk te houden en bijvoorbeeld alleen de gewenste lijnen/cases te exporteren.
+
+Faalkans in tijd
+----------------
+Met het scherm ``Faalkans in tijd`` kan de trajectfaalkans/-betrouwbaarheid van verschillende cases worden weergegeven. Dit kan nuttig zijn bij het bepalen van de snelheid van toename van de faalkans richting de toekomst, en zo extra inzicht geven in wat bijv. een effectieve tijdshorizon voor de versterking is.
+
+Maatregelen op kaart
+-------------------
+In het scherm ``Maatregelen op kaart`` kunnen de maatregelen van verschillende cases worden weergegeven per dijkvak. Daarbij worden twee cases die geselecteerd worden met de `Activeer`-knop naast elkaar weergegeven. De eerste case wordt aan de waterkant van het traject weergegeven, de tweede aan de landzijde. Een voorbeeld is gegeven in onderstaande figuur.
+
+.. figure:: img/vergelijken_berekeningen_maatregelenkaart.png
+    :width: 80%
+    :align: center
+
+Met deze kaart kan eenvoudig inzicht worden gekregen in de verschillen tussen de maatregelen van verschillende cases. Zo verkrijgt men een beeld van de invloed van verschillende aannames in scenario's op het type maatregel. 
+
+.. tip::
+    Omdat de lijnen een verschuiving betreffen van het originele traject kan de weergave bij korte dijkvakken en veel (scherpe) bochten soms wat merkwaardig ogen (zie hieronder voor een voorbeeld). Door met de muis over de vakken te gaan wordt meer informatie weergegeven wat bij onduidelijkheid de vergelijking kan vergemakkelijken.
+
+    .. figure:: img/vergelijken_berekeningen_maatregelen_weergavefout.png
+        :width: 80%
+        :align: center
+
+Overzichtstabel maatregelen
+---------------------------
+In het scherm ``Overzichtstabel maatregelen`` wordt een tabel weergegeven met voor 2 berekeningen de maatregelen per dijkvak. Daarbij kan met de activeerknoppen in het linkerpaneel worden gekozen welke berekening moet worden weergegeven. Een voorbeeld is gegeven in onderstaande figuur.
+
+.. figure:: img/vergelijken_berekeningen_maatregeltabel.png
+    :width: 100%
+    :align: center
+
+Van boven naar beneden worden op volgorde de verschillende dijkvakken weergegeven. Wanneer een regel als donkergrijs is weergegeven, betekent dit dat er een ander type maatregel is gekozen. Wanneer een cel groen is, betekent het dat de dimensie van de maatregel verschilt. In het voorbeeld is te zien dat op dijkvak 27 in beide berekeningen voor een grondversterking wordt gekozen. In de eerste berekening met 15 meter berm, in de tweede met 10 meter berm. Op dijkvak 31 wordt in berekening 1 een berm aangelegd (8 meter) en in berekening 2 geen maatregel getroffen. In de tabel worden de volgende kolommen weergegeven.
+
+.. csv-table:: Kolommen in tabel met overzicht maatregelen
+  :file: tables/kolommen_maatregeltabel.csv
+  :widths: 15, 50
+  :header-rows: 1
+
+Volgorde dijkvakken
+-------------------
+In het scherm ``Volgorde dijkvakken`` kan de volgorde van de dijkvakken in de optimalisatie worden weergegeven. Daarbij wordt voor beide berekeningen aangegeven welke dijkvakken als eerste in de optimalisatievolgorde voorkomen. Dit kan helpen bij het bepalen of een ander rekenscenario leidt tot een andere optimale investeringsvolgorde en dus een andere optimale scope van dijkvakken met het hoogste rendement.