centroid assign section

Author: sarah-hlsn

doc/user-guide/climada_engine_Impact.ipynb

@@ -841,11 +841,51 @@
    "source": [
     "We are finally ready for the impact computation. This is the simplest step. Just give the exposure, impact function and hazard to the ImpactCalc.impact() method.\n",
     "\n",
-    "Note: we did not specifically assign centroids to the exposures. Hence, the default is used - each exposure is associated with the closest centroids. Since we defined the centroids from the exposures, this is a one-to-one mapping.\n",
-    "\n",
     "Note: we did not define an `Entity`  in this impact calculations. Recall that `Entity` is a container class for __[Exposures](climada_entity_Exposures.ipynb)__, __[Impact Functions](climada_entity_ImpactFuncSet.ipynb)__, __[Discount Rates](climada_entity_DiscRates.ipynb)__ and __[Measures](climada_entity_MeasureSet.ipynb)__. Since we had only one Exposure and one Impact Function, the container would not have added any value, but for more complex projects, the Entity class is very useful."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "#### Assigning centroids manually"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "It is best to create centroids from exposures directly as we have done above, to ensure `Hazard` and `Exposure` are matching well. However, sometimes you may have pre-defined `Hazard` and `Exposure` data. In those cases, it can make sense to manually match `Centroids` and `Exposure`.\n",
+    "\n",
+    "The matching could then look like this:\n",
+    "```\n",
+    "exp_lp.assign_centroids(tc, distance=\"euclidean\", threshold=0.1) # assign centroids manually\n",
+    "```\n",
+    "The `threshold` argument defines the maximum distance of the nearest neighbor in the units of the `Exposure` crs.\n",
+    "\n",
+    "When assingning `Centroids` manually, make sure to pass `assign_centroids=False` to the impact calculation, so that the assignment is not lost:\n",
+    "```\n",
+    "imp = ImpactCalc(exp_lp, impf_set, tc).impact(\n",
+    "    save_mat=False,\n",
+    "    assign_centroids=False, # false, since we assign centroids manually\n",
+    ")  \n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "#### Assigning centroids automatically"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "If we do not specifically assign centroids to the exposures. Hence, the default (i.e. assign_centroids=True) is used - each exposure is associated with the closest centroids. Since we defined the centroids from the exposures above, this is a one-to-one mapping."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 10,