diff --git a/doc/user-guide/climada_hazard_Hazard.ipynb b/doc/user-guide/climada_hazard_Hazard.ipynb index 412346d041..d3e195cf96 100644 --- a/doc/user-guide/climada_hazard_Hazard.ipynb +++ b/doc/user-guide/climada_hazard_Hazard.ipynb @@ -7,16 +7,31 @@ "# Hazard class\n", "\n", "## What is a hazard?\n", - "A hazard describes weather events such as storms, floods, droughts, or heat waves both in terms of probability of occurrence as well as physical intensity.\n", + "A hazard describes weather events such as storms, floods, droughts, or heat waves, both in terms of probability of occurrence as well as physical intensity.\n", "\n", "## How are hazards embedded in the CLIMADA architecture?\n", - "Hazards are defined by the base class `Hazard` which gathers the required attributes that enable the impact computation (such as centroids, frequency per event, and intensity per event and centroid) and common methods such as readers and visualization functions. Each hazard class collects historical data or model simulations and transforms them, if necessary, in order to construct a coherent event database. Stochastic events can be generated taking into account the frequency and main intensity characteristics (such as local water depth for floods or gust speed for storms) of historical events, producing an ensemble of probabilistic events for each historical event. CLIMADA provides therefore an event-based probabilistic approach which does not depend on a hypothesis of a priori general probability distribution choices. Note that one can also reduce the probabilistic approach to a deterministic approach (e.g., story-line or forecasting) by defining the frequency to be 1. The source of the historical data (e.g. inventories or satellite images) or model simulations (e.g. synthetic tropical cyclone tracks) and the methodologies used to compute the hazard attributes and its stochastic events depend on each hazard type and are defined in its corresponding Hazard-derived class (e.g. `TropCylcone` for tropical cyclones, explained in the tutorial [TropCyclone](climada_hazard_TropCyclone.ipynb)). This procedure provides a solid and homogeneous methodology to compute impacts worldwide. In the case where the risk analysis comprises a specific region where good quality data or models describing the hazard intensity and frequency are available, these can be directly ingested by the platform through the reader functions, skipping the hazard modelling part (in total or partially), and allowing us to easily and seamlessly combine CLIMADA with external sources. Hence the impact model can be used for a wide variety of applications, e.g. deterministically to assess the impact of a single (past or future) event or to quantify risk based on a (large) set of probabilistic events. Note that since the `Hazard` class is not an abstract class, any hazard that is not defined in CLIMADA can still be used by providing the `Hazard` attributes.\n", + "Hazards are defined by the base class `Hazard` which gathers the required attributes that enable the impact computation (such as centroids, frequency per event, and intensity per event and centroid), and common methods such as readers and visualization functions. \n", + "\n", + "Each hazard class collects observational data or model simulations and transforms them, if necessary, in order to construct a coherent event database. \n", + "Stochastic realizations can be generated by accounting for the frequency and key intensity characteristics (such as local water depth for floods or gust speed for storms) of the input events, producing a probabilistic ensemble for each.\n", + "CLIMADA provides therefore an event-based probabilistic approach which does not assume a-priori probability distributions. Note that one can also reduce the probabilistic approach to a deterministic approach (e.g., story-line or forecasting) by defining the frequency to be 1.\n", + "\n", + "Different hazards rely on different data sources, such as observational datasets (e.g., inventories or satellite images) or model simulations (e.g., synthetic tropical cyclone tracks). Similarly, the methods used to compute hazard attributes and generate a stochastic event ensemble depend on the hazard type. This information is defined in the corresponding Hazard-derived class (e.g. `TropCylcone` for tropical cyclones, explained in the tutorial [TropCyclone](climada_hazard_TropCyclone.ipynb))\n", + "\n", + "When high-quality data or models describing hazard intensity and frequency are available for a specific region, they can be directly imported into the platform via the reader functions. This allows the hazard-modelling step of the risk analysis to be skipped (either partially or entirely), and enables seamless integration of CLIMADA with external data sources. Note that since the `Hazard` class is not an abstract class, any hazard that is not defined in CLIMADA can still be used by providing the `Hazard` attributes.\n", + "\n", + "In summary, the impact computations performed with CLIMADA support a wide range of applications, from deterministic assessments of individual past or future events to comprehensive risk quantification based on large ensembles of probabilistic events.\n", "\n", "## What do hazards look like in CLIMADA?\n", "\n", - "A `Hazard` contains events of some hazard type defined at `centroids`. There are certain variables in a `Hazard` instance that _are needed_ to compute the impact, while others are _descriptive_ and can therefore be set with default values. The full list of looks like this:\n", + "A `Hazard` contains events of some hazard type defined at `centroids`. \n", "\n", - "| Mandatory variables             | Data Type                                    | Description                                        |\n", + "Certain variables in a `Hazard` object are _required for impact computations_. If they are not supplied at initialization, they are assigned empty placeholders; in general, these must be populated with meaningful values before any impact computation can produce valid results.\n", + "The remaining variables serve a _descriptive_ purpose and can be safely left at their default values.\n", + "\n", + "The full list of variables looks like this:\n", + "\n", + "| Variables for Impact Computation             | Data Type                                    | Description                                        |\n", "| :- | :- | :- |\n", "| units |(str)| units of the intensity|\n", "| centroids |`Centroids()`| centroids of the events|\n", @@ -28,14 +43,17 @@ "
\n", "
\n", "\n", - "| Descriptive variables | Data Type | Description|\n", + "| Descriptive Variables | Data Type | Description|\n", "| :- | :- | :- |\n", - "| date |(np.array)| integer date corresponding to the proleptic Gregorian ordinal, where January 1 of year 1 has
ordinal 1 (ordinal format of datetime library)|\n", - "| orig |(np.array)| flags indicating historical events (True) or probabilistic (False) |\n", + "| date |(np.array)| integer date corresponding to the proleptic Gregorian ordinal, where January 1 of year 1 has
ordinal 1 (ordinal format of datetime library) (default: empty)|\n", + "| orig |(np.array)| flags indicating single events (True) or probabilistic ensemble (False) (default: empty) |\n", "| event_name |(list(str))| name of each event (default: event_id)|\n", + "| frequency_unit |(str)| unit of the frequency (default: \"1/year\")|\n", "
\n", "\n", - "Note that `intensity` and `fraction` are scipy.sparse matrices of size num_events x num_centroids. The `fraction` attribute is optional. The `Centroids` class contains the geographical coordinates where the hazard is defined. A `Centroids` instance provides the coordinates either as points or raster data together with their Coordinate Reference System (CRS). The default CRS used in climada is the usual EPSG:4326. `Centroids` provides moreover methods to compute centroids areas, on land mask, country iso mask or distance to coast." + "Note that `intensity` and `fraction` are scipy.sparse matrices of size num_events x num_centroids. The `fraction` attribute can be omitted; in this case, the impact computation treats all exposures as fully affected.\n", + "\n", + "The `Centroids` class contains the geographical coordinates where the hazard is defined. A `Centroids` instance provides the coordinates either as points or raster data together with their Coordinate Reference System (CRS). The default CRS used in climada is the usual EPSG:4326. `Centroids` also provides methods to compute centroids areas, on land mask, country iso mask or distance to coast." ] }, { @@ -942,9 +960,13 @@ } ], "source": [ - "# If you see an error message, try to create a depository named results in the repository tutorial.\n", + "from pathlib import Path\n", + "\n", + "# Creating 'results' folder if not existing already\n", + "Path(\"results\").mkdir(exist_ok=True) \n", "haz_tc_fl.write_hdf5(\"results/haz_tc_fl.h5\")\n", "\n", + "# Read the file back\n", "haz = Hazard.from_hdf5(\"results/haz_tc_fl.h5\")\n", "haz.check()" ] @@ -1003,9 +1025,9 @@ ], "metadata": { "kernelspec": { - "display_name": "Python 3 (ipykernel)", + "display_name": "Python [conda env:.conda-climada_tutorial_review]", "language": "python", - "name": "python3" + "name": "conda-env-.conda-climada_tutorial_review-py" }, "language_info": { "codemirror_mode": { @@ -1017,7 +1039,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.12.6" + "version": "3.12.12" } }, "nbformat": 4,