Write info/into text for all example networks (#67)

* add network info texts
* update README

.github/workflows/tests.yml

@@ -80,10 +80,9 @@ jobs:
         ./bbn inference _examples/dog-problem.xml
         ./bbn inference _examples/earthquake.yml
         ./bbn train _examples/fruits-untrained.yml _examples/fruits.csv
-        ./bbn inference _examples/medical-treatment.yml
+        ./bbn inference _examples/medical.yml
         ./bbn inference _examples/mendel.yml
         ./bbn inference _examples/monty-hall.yml
-        ./bbn inference _examples/native-fish.yml
         ./bbn inference _examples/oil.yml
         ./bbn inference _examples/robot.yml
         ./bbn inference _examples/sprinkler.yml

CHANGELOG.md

@@ -14,7 +14,7 @@
 * Optional total utility node for weighting individual utilities (#59)
 * Adds support for custom node colors in YAML files (#64)
 * Adds shortcuts for logic nodes like, and, or, if-then, etc. (#65)
-* Networks can have a longer info text, also shown in TUI app (#65)
+* Networks can have a longer info text, also shown in TUI app (#66)
 
 ### Documentation
 
@@ -23,6 +23,7 @@
 * Adds medical treatment decision example (#60)
 * Adds disease control decision example (#61)
 * Adds several examples for logic deduction (#65, #66)
+* All examples have a detailed description that shows up in the TUI app (#66, #67)
 
 ## [[v0.4.0]](https://github.com/mlange-42/bbn/compare/v0.3.0...v0.4.0)
 

README.md

@@ -12,10 +12,12 @@ Bayesian Belief Network library and CLI/TUI tool for [Go](https://go.dev).
 ## Features
 
 * Minimal, fast API for usage as a library.
-* Decision networks with utility and decision nodes.
-* Human-readable YAML format, as well as BIF-XML.
-* Train and query networks from the command line with `bbn`.
 * Visualize, query and explore networks in the interactive TUI app `bbni`.
+* Supports decision networks (aka influence diagrams) for multi-stage decisions.
+* Provides logic nodes for logic inference in addition to probabilistic inference.
+* Train and query networks from the command line with `bbn`.
+* Human-readable YAML format for networks, as well as BIF-XML.
+* Plenty of [examples](https://github.com/mlange-42/bbn/tree/main/_examples) with introductory text, shown in-app.
 
 ## Installation
 

_examples/asia.yml

@@ -1,14 +1,24 @@
 name: Asia
+info: >-
+  The good old Asia example about lung cancer diagnosis.
+
+
+  Yellow are typical evidence nodes. Set/unset their values by clicking the bars.
+
+
+  Observe the probabilities for the three diseases (white nodes).
 variables:
 
 - variable: Visit to Asia
   position: [1, 0]
+  color: yellow
   outcomes: [yes, no]
   table:
   - [1, 99]
 
 - variable: Smoker
   position: [49, 0]
+  color: yellow
   outcomes: [yes, no]
   table:
   - [50, 50]
@@ -39,12 +49,14 @@ variables:
 
 - variable: Tuberculosis or Cancer
   position: [18, 14]
+  color: gray
   given: [Has Tuberculosis, Has Lung Cancer]
   outcomes: [yes, no]
   logic: OR
 
 - variable: XRay Result
   position: [1, 21]
+  color: yellow
   given: [Tuberculosis or Cancer]
   outcomes: [abnormal, normal]
   table:
@@ -53,6 +65,7 @@ variables:
 
 - variable: Dyspnea
   position: [49, 21]
+  color: yellow
   given: [Tuberculosis or Cancer, Has Bronchitis]
   outcomes: [yes, no]
   table:

_examples/disease-control.yml

@@ -1,4 +1,26 @@
 name: Disease Control Decision
+info: >-
+  A decision network for disease control decisions in livestock herds.
+
+
+  Three decisions are taken sequentially:
+  
+  (1) Whether to vaccinate, preventively, depending on herd size.
+  Vaccination reduces infection and spread risk.
+
+  (2) Whether to perform a test, depending on the herd size,
+  previous vaccination, and whether an animal has symptoms.
+
+  (3) Whether to treat (or cull) the animal, depending on the herd size,
+  previous vaccination, the test and its result.
+  Treatment reduces the spread risk.
+
+
+  Get definitive decisions by setting the values of "Herd size",
+  "Symptoms" and "Test result" by clicking on the resp. bars.
+
+
+  Particularly inspect the differences between the policies for the different herd sizes.
 variables:
 
 - variable: Herd size
@@ -89,7 +111,7 @@ variables:
   - [-10] # treatment+
   - [  0] # treatment-
 
-- variable: Outbreak
+- variable: Spread
   position: [79, 6]
   color: gray
   outcomes: [yes, no]
@@ -107,15 +129,15 @@ variables:
   - [0, 100] # inf- treat- vacc+
   - [0, 100] # inf- treat- vacc-
 
-- variable: Outbreak cost
-  given: [Outbreak, Herd size]
+- variable: Spread cost
+  given: [Spread, Herd size]
   outcomes: [euros]
   position: [78, 0]
   type: utility
   table:
-  - [-100] # outbreak+ small
-  - [-500] # outbreak+ medium
-  - [-5000] # outbreak+ large
-  - [0] # outbreak- small
-  - [0] # outbreak- medium
-  - [0] # outbreak- large
+  - [-100] # spread+ small
+  - [-500] # spread+ medium
+  - [-5000] # spread+ large
+  - [0] # spread- small
+  - [0] # spread- medium
+  - [0] # spread- large

_examples/earthquake.yml

@@ -1,8 +1,23 @@
 name: Earthquake Decision Network
+info: >-
+  A network for the decision on evacuating a city,
+  based on warnings from a seismic sensor.
+
+
+  The actor can observe the sensor warning, as well as the quality of sensor maintenance.
+  To trigger a definitive decision, set these two to some value by clicking on the bars.
+
+
+  In this example, multiple utility nodes (green) are used.
+  "Material damage" depends on the actual earthquake,
+  "Human damage" depends on the earthquake and the decision,
+  and "Evacuation cost" only depends on the decision.
+  The sum of all three is optimized.
 variables:
 
 - variable: Earthquake next week
   position: [1, 0]
+  color: gray
   outcomes: [strong, slight, none]
   table: 
   - [1, 5, 94]

_examples/fruits-untrained.yml

@@ -1,7 +1,6 @@
 # An untrained network.
 # Train with:
 # bbn train _examples/fruits.yml _examples/fruits.csv
-
 name: Fruits
 variables:
 

_examples/logic/friends.yml

@@ -1,3 +1,6 @@
+# Source of the puzzle:
+# https://www.logisch-gedacht.de/logikraetsel/wochentag/
+
 name: Who is right?
 info: >-
   Four friends A, B, C and D meet and state the quoted facts below.

_examples/logic/weekday.yml

@@ -1,3 +1,6 @@
+# Source of the puzzle:
+# https://www.logisch-gedacht.de/logikraetsel/wochentag/
+
 name: Weekday 7 friends puzzle
 info: >-
   Seven friends meet, and are not sure which day of the week it is.

_examples/medical-treatment.yml → _examples/medical.yml

@@ -1,5 +1,20 @@
 name: Medical Treatment Decision
+info: >-
+  A decision network for the sequential decisions on whether to test a patient,
+  and whether to treat them.
 
+
+  The decision for testing is based on whether the patient exhibits symptoms.
+  Set the "Symptoms" node to a value by clicking a bar.
+
+
+  The decision for treatment is based on symptoms, whether a test was performed, and the test result.
+  Set the test result to get a definitive decision.
+
+
+  Note that the actual infection state of the patient is not known for the decisions.
+  Also note that it is a severe disease, which is very cheap to treat.
+  Therefore, the optimal policy might be unexpected.
 variables:
 
 - variable: Infected
@@ -12,7 +27,7 @@ variables:
 - variable: Symptoms
   outcomes: [yes, no]
   given: [Infected]
-  position: [1, 8]
+  position: [1, 10]
   table:
   - [0.8, 0.2] # infected+
   - [0.05, 0.95] # infected-
@@ -24,7 +39,7 @@ variables:
   type: utility
   table:
   - [ -100] # infected+ treatment+
-  - [-1000] # infected+ treatment-
+  - [-5000] # infected+ treatment-
   - [    0] # infected- treatment+
   - [    0] # infected- treatment-
 
@@ -37,7 +52,7 @@ variables:
 - variable: Test result
   outcomes: [pos, neg]
   given: [Test, Infected]
-  position: [31, 8]
+  position: [31, 7]
   table:
   - [0.95, 0.05] # test+ infected+
   - [0.05, 0.95] # test+ infected-
@@ -50,12 +65,12 @@ variables:
   position: [1, 24]
   type: utility
   table:
-  - [-5] # test+
+  - [-10] # test+
   - [ 0] # test-
 
 - variable: Treatment
   outcomes: [yes, no]
-  given: [Test, Test result]
+  given: [Symptoms, Test, Test result]
   position: [46, 17]
   type: decision
 
@@ -66,5 +81,5 @@ variables:
   type: utility
   table:
   - [-100] # treatment+
-  - [  0] # treatment-
+  - [   0] # treatment-
 

_examples/mendel.yml

@@ -4,17 +4,33 @@
 # - https://www.norsys.com/netlibrary/nets/tut/Mendel%20Genetics_tut.htm
 
 name: Mendel Genetics
+info: >-
+  Mendel's experiment of breeding red and white flowered peas.
+
+
+  White nodes show observable colors of parents and offspring,
+  while gray nodes are unobservable genetics.
+
+
+  'R' is the dominant allele for red flowers,
+  'w' is the recessive allele for white flowers.
+
+
+  Set evidence on some nodes by clicking the bars.
+  Observe the behavior of other nodes.
 variables:
 
 - variable: Genes Parent 1
   outcomes: [RR, Rw, ww]
   position: [17, 0]
+  color: gray
   table:
   - [25, 50, 25]
 
 - variable: Genes Parent 2
   outcomes: [RR, Rw, ww]
   position: [49, 0]
+  color: gray
   table:
   - [25, 50, 25]
 
@@ -27,10 +43,20 @@ variables:
   - [1, 0] # Rw
   - [0, 1] # ww
 
+- variable: Color Parent 2
+  given: [Genes Parent 2]
+  outcomes: [red, white]
+  position: [65, 8]
+  table:
+  - [1, 0] # RR
+  - [1, 0] # Rw
+  - [0, 1] # ww
+
 - variable: Genes Child
   given: [Genes Parent 1, Genes Parent 2]
   outcomes: [RR, Rw, ww]
   position: [33, 8]
+  color: gray
   table:
   #   RR   Rw   ww     P1 P2
   - [100,   0,   0]  # RR RR
@@ -43,15 +69,6 @@ variables:
   - [  0,  50,  50]  # ww Rw
   - [  0,   0, 100]  # ww ww
 
-- variable: Color Parent 2
-  given: [Genes Parent 2]
-  outcomes: [red, white]
-  position: [65, 8]
-  table:
-  - [1, 0] # RR
-  - [1, 0] # Rw
-  - [0, 1] # ww
-
 - variable: Color Child
   given: [Genes Child]
   outcomes: [red, white]

_examples/monty-hall.yml

@@ -1,4 +1,21 @@
 name: Monty-Hall Problem
+info:
+  The good old Monty Hall Problem.
+
+
+  It is a game with three doors, behind one of which is the price (a car),
+  and nothing is behind the two other doors.
+  First, the player chooses a door.
+  Next, the game host opens one of the two doors that were not selected by the player.
+  Finally, the player may choose to change their decision to the other close door.
+
+
+  Should the player change the decision?
+  This question is solved by the network, already without any interaction.
+
+
+  Explore the network by setting some evidence (by clicking bars),
+  and try to understand why the player should change.
 variables:
 
 - variable: Player