updates Tutorial [wip]

Author: spjuhel

doc/user-guide/climada_trajectories.ipynb

@@ -1,41 +1,5 @@
 {
  "cells": [
-  {
-   "cell_type": "code",
-   "execution_count": 1,
-   "id": "96920214-a14b-4094-9949-36a1175b1df8",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "%load_ext autoreload\n",
-    "%autoreload 2"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "56a07dee-25a8-4bb5-a01c-933ee955f067",
-   "metadata": {},
-   "source": [
-    "Currently, to run this tutorial, from within a climada_python git repo please run:\n",
-    "\n",
-    "```\n",
-    "mamba create -n climada_trajectory \"python==3.11.*\"\n",
-    "git fetch\n",
-    "git checkout feature/risk_trajectory\n",
-    "mamba env update -n climada_trajectory -f requirements/env_climada.yml\n",
-    "mamba activate climada_trajectory\n",
-    "python -m pip install -e ./\n",
-    "\n",
-    "```\n",
-    "\n",
-    "To be able to select that environment in jupyter you possibly might also need:\n",
-    "\n",
-    "```\n",
-    "mamba install ipykernel\n",
-    "python -m ipykernel install --user --name climada_trajectory\n",
-    "```"
-   ]
-  },
   {
    "cell_type": "markdown",
    "id": "856ac388-9edb-497e-a2ff-a325f2a22562",
@@ -94,13 +58,19 @@
    "id": "4e0f3261-f443-4cc6-b85b-c6a3d90b73e3",
    "metadata": {},
    "source": [
-    "The fundamental idea behing the `trajectories` module is to enable a better assessment of the evolution of risk over time, both by facilitating point by point comparison, and risk \"evolutions\".\n",
+    "The fundamental idea behing the `trajectories` module is to enable a better assessment of the evolution of risk over time, both by facilitating point by point comparison, and the \"evolution\" or risk.\n",
     "\n",
-    "It aims at facilitating answering questions such as:\n",
+    "This module aims at facilitating answering questions such as:\n",
     "\n",
     "- How does future hazards (probabilistic event set), exposure and vulnerability change impacts with respect to present?\n",
     "- How would the impacts compare if a past event were to happen again with present / future exposure?\n",
-    "- etc."
+    "- How will risk evolve in the future under different assumptions on the evolution of hazard, exposure, vulnerability and discount rate?\n",
+    "- *etc*.\n",
+    "\n",
+    "To achieve this, this module introduces two concepts:\n",
+    "\n",
+    "- Snapshots of risk, a fixed representation of risk (via its three components Exposure, Hazard and Vulnerability) for a given date. This concept is intended to be generic, as such the given date can be something else than a year, a month or a day for instance, but keep in mind that we will not check that the data you provide makes sense for it!\n",
+    "- Trajectories of risk, a collection of snapshots,for which risk metrics can be computed and regrouped to ease their evaluation."
    ]
   },
   {
@@ -116,7 +86,7 @@
    "id": "274a342f-54c0-4590-9110-5e297010955e",
    "metadata": {},
    "source": [
-    "We use `Snapshot` objects to define a point in time for risk. This object acts as a wrapper of the classic risk framework composed of Exposure, Hazard and Vulnerability. As such it is defined for a specific date (usually a year), and contains references to an `Exposures`, a `Hazard`, and an `ImpactFuncSet` object.\n",
+    "We use `Snapshot` objects to define a point in time for risk. This object acts as a wrapper of the classic risk framework composed of Exposure, Hazard and Vulnerability. As such it is defined for a specific date (usually a year), and contains an `Exposures`, a `Hazard`, and an `ImpactFuncSet` object.\n",
     "\n",
     "Instantiating such a `Snapshot` is done simply with:\n",
     "\n",
@@ -131,10 +101,16 @@
     "\n",
     "Note that to avoid any ambiguity, you need to write explicitly `exposure=your_exposure`.\n",
     "\n",
-    "Think of `Snapshot` as a representation of risk at, or around, a specific date. Your hazard should thus be a probabilistic set of events representative for the specified date.\n",
-    "Note that the date does not need to be a year and can be a datetime if you want to make comparisons on a sub-yearly level.\n",
+    "Think of `Snapshot` as a representation of risk at, or around, a specific date. Your hazard should be a probabilistic set of events that are representative for the designated date.\n",
+    "\n",
+    "To be consistent with the intuitive idea of a snapshot, `Snapshot` objects are make a \"deep copy\" of the risk triplet and are immutable. \n",
+    "This means that they do not change once created (notably even if you change one of the component, e.g. the Hazard object, outside of the `Snapshot`).\n",
+    "If you want a `Snapshot` with a different `Hazard`, you need to create a new one.\n",
     "\n",
-    "Below is an example of how to setup a such Snapshot using data from the data API for tropical cyclones in Haiti:"
+    "In that spirit, you cannot directly instantiate a Snapshot with an adaptation measure. To include adaptation, you need to first create the snapshot without adaptation, and then use `apply_measure()`, which\n",
+    "will return a new `Snapshot`, with the changed (Exposure, Hazard, ImpactFuncSet) according to the given measure.\n",
+    "\n",
+    "Below is an concrete example of how to create a Snapshot using data from the data API for tropical cyclones in Haiti:"
    ]
   },
   {
@@ -184,9 +160,6 @@
     "exp_present.gdf.rename(columns={\"impf_\": \"impf_TC\"}, inplace=True)\n",
     "exp_present.gdf[\"impf_TC\"] = 1\n",
     "\n",
-    "# Trajectories allow to look at the risk faced by specifics groups of coordinates based on the \"group_id\" column of the exposure\n",
-    "exp_present.gdf[\"group_id\"] = (exp_present.gdf[\"value\"] > 500000) * 1\n",
-    "\n",
     "snap = Snapshot(exposure=exp_present, hazard=haz_present, impfset=impf_set, date=2018)"
    ]
   },