Clearer values in tutorial

Author: spjuhel

doc/development/Guide_test_fixtures.ipynb

@@ -91,7 +91,7 @@
     "| Fixture | What it gives you |\n",
     "|---|---|\n",
     "| `exposures` | An `Exposures` object with 6 points and values `[0, 1000, 2000, 3000, 4000, 5000]` |\n",
-    "| `hazard` | A `Hazard` with 5 events and known intensities (see below) |\n",
+    "| `hazard` | A `Hazard` with 5 events and \"helpful\" intensities and frequencies (see below) |\n",
     "| `linear_impact_function` | An `ImpactFunc` where intensity % == damage % (identity) |\n",
     "| `impfset` | An `ImpactFuncSet` wrapping the linear impact function |\n",
     "| `centroids` | Hazard centroids (slightly offset from exposure points (`+0.1°`)) |\n",
@@ -105,7 +105,20 @@
     "    assert impact.aai_agg == pytest.approx(18)  # analytically known value\n",
     "```\n",
     "\n",
-    "The expected values are documented at the top of `conftest.py`, here are some key ones:\n",
+    "Values of the defaults fixtures were chosen such that impacts are rather easy to compute by hand. \n",
+    "This is documented at the top of `conftest.py`, but here are some key design choices:\n",
+    "\n",
+    "- There are 4 events, with frequencies == 0.03, 0.01, 0.006, 0.004, 0,\n",
+    "  such that impacts for RP250, 100 and 50 and 20 correspond to `at_event`,\n",
+    "  (sorted frequencies cumulate to 1/250, 1/100, 1/50 and 1/20).\n",
+    "- Hazard intensity is:\n",
+    "  * Event 1: zero everywhere (always no impact)\n",
+    "  * Event 2: max intensity (100) at first centroid (also always no impact (first centroid is 0))\n",
+    "  * Event 3: half max intensity at second centroid (impact == half second centroid)\n",
+    "  * Event 4: quarter max intensity everywhere (impact == 1/4 total value)\n",
+    "  * Event 5: max intensity everywhere (but zero frequency)\n",
+    "\n",
+    "This results in the following expected values:\n",
     "\n",
     "| Metric | Expected value | Why |\n",
     "|---|---|---|\n",
@@ -114,6 +127,8 @@
     "| RP 100 | `500` | Event 3: half intensity on second point (value 1000) |\n",
     "| RP 250 | `3750` | Event 4: quarter intensity on all points |\n",
     "\n",
+    "> Note: The overview above reflects the `conftest.py` file at the time of writing. If you notice any discrepancy, the docstring at the top of `conftest.py` is the authoritative source.\n",
+    "\n",
     "### Using factories for custom scenarios\n",
     "\n",
     "When your test needs a variation (e.g. scaled intensity, a different hazard type, group IDs), you can make use of the `_factory` fixtures. Each factory is a callable that accepts keyword arguments:\n",