CLIMADA documentation

Release 3.1.2

CLIMADA contributors

Apr 21, 2022

 CONTENTS

1 Getting started with CLIMADA 3

2 Introduction 5

3 Installation 7

4 Using Climada on the Euler Cluster (ETH internal) 11

5 Tutorials 19

6 Developer guide 249

7 Software documentation 307

8 License 457

Python Module Index 459

Index 461

i
ii
 CLIMADA documentation, Release 3.1.2

This is the documentation for version v3.1.2. In CLIMADA-project you will find CLIMADA’s contributors, repository
and scientific publications.

CONTENTS 1
CLIMADA documentation, Release 3.1.2

2 CONTENTS
 CHAPTER

ONE

GETTING STARTED WITH CLIMADA

This is a short summary of the guides to help you find the information that you need to get started. To learn more about
CLIMADA, have a look at the introduction. You can also have a look at the paper repository to get an overview of
research projects.

1.1 Installation

The first step to getting started is installing CLIMADA. To do so you will need: 1. To get the lastest release from the
git repository CLIMADA releases or clone the project with git if you are interested in contributing to the development.
2. To build a conda environment with the dependencies needed by CLIMADA.
For details see the Installation Guide.
If you need to run a model on a computational cluster, have a look at this guide to install CLIMADA and run your jobs.

1.2 Programming in Python

It is best to have some basic knowledge of Python programming before starting with CLIMADA. But if you need a
quick introduction or reminder, have a look at the short Python Tutorial. Also have a look at the python Python Dos
and Don’t guide and at the Python Performance Guide for best practice tips.

1.3 Tutorials

A good way to start using CLIMADA is to have a look at the Tutorials. The Main Tutorial will introduce you the
structure of CLIMADA and how to calculate you first impacts, as well as your first appraisal of adaptation options.
You can then look at the specific tutorials for each module (for example if you are interested in a specific hazard, like
Tropical Cyclones, or in learning to estimate the value of asset exposure,. . . ).

3
CLIMADA documentation, Release 3.1.2

1.4 Contributing

If you would like to participate in the development of CLIMADA, carefully read the Git and Development Guide.
Before making a new feature, discuss with one of the repository admins (Now Chahan, Emmanuel and David). Every
new feature or enhancement should be done on a separate branch, which will be merged in the develop branch after
being reviewed (see Checklist). Finally, the develop branch is merged in the main branch in each CLIMADA release.
Each new feature should come with a tutorial and with Unit and Integration Tests.

1.5 Other Questions

If you have any other questions, you might find some information in the Miscellaneous guide. If you cannot find you
answer in the guides, you can open an issue for somebody to help you.

4 Chapter 1. Getting started with CLIMADA

 CHAPTER

TWO

INTRODUCTION

CLIMADA implements a fully probabilistic risk assessment model. According to the IPCC [1], natural risks emerge
through the interplay of climate and weather-related hazards, the exposure of goods or people to this hazard, and the
specific vulnerability of exposed people, infrastructure and environment. The unit chosen to measure risk has to be the
most relevant one in a specific decision problem, not necessarily monetary units. Wildfire hazard might be measured
by burned area, exposure by population or replacement value of homes and hence risk might be expressed as number
of affected people in the context of evacuation, or repair cost of buildings in the context of property insurance.
Risk has been defined by the International Organization for Standardization as the “effect of uncertainty on objec-
tives” as the potential for consequences when something of value is at stake and the outcome is uncertain, recognizing
the diversity of values. Risk can then be quantified as the combination of the probability of a consequence and its
magnitude:

𝑟𝑖𝑠𝑘 = 𝑝𝑟𝑜𝑏𝑎𝑏𝑖𝑙𝑖𝑡𝑦 × 𝑠𝑒𝑣𝑒𝑟𝑖𝑡𝑦

In the simplest case, × stands for a multiplication, but more generally, it represents a convolution of the respective
distributions of probability and severity. We approximate the 𝑠𝑒𝑣𝑒𝑟𝑖𝑡𝑦 as follows:

𝑠𝑒𝑣𝑒𝑟𝑖𝑡𝑦 = 𝐹 (ℎ𝑎𝑧𝑎𝑟𝑑 𝑖𝑛𝑡𝑒𝑛𝑠𝑖𝑡𝑦, 𝑒𝑥𝑝𝑜𝑠𝑢𝑟𝑒, 𝑣𝑢𝑙𝑛𝑒𝑟𝑎𝑏𝑖𝑙𝑖𝑡𝑦) = 𝑒𝑥𝑝𝑜𝑠𝑢𝑟𝑒 * 𝑓𝑖𝑚𝑝 (ℎ𝑎𝑧𝑎𝑟𝑑 𝑖𝑛𝑡𝑒𝑛𝑠𝑖𝑡𝑦)

where 𝑓𝑖𝑚𝑝 is the impact function which parametrizes to what extent an exposure will be affected by a specific hazard.
While ‘vulnerability function’ is broadly used in the modelers community, we refer to it as ‘impact function’ to explicitly
include the option of opportunities (i.e. negative damages). Using this approach, CLIMADA constitutes a platform to
analyse risks of different hazard types in a globally consistent fashion at different resolution levels, at scales from
multiple kilometres down to meters, depending on the purpose.

2.1 References

[1] IPCC: Climate Change 2014: Impacts, Adaptation and Vulnerability. Part A: Global and Sectoral Aspects. Contri-
bution of Working Group II to the Fifth Assessment Report of the Intergovernmental Panel on Climate Change, edited
by C. B. Field, V. R. Barros, D. J. Dokken, K. J. Mach, M. D. Mastrandrea, T. E. Bilir, M. Chatterjee, K. L. Ebi, Y.
O. Estrada, R. C. Genova, B. Girma, E. S. Kissel, A. N. Levy, S. MacCracken, P. R. Mastrandrea, and L. L. White,
Cambridge University Press, United Kingdom and New York, NY, USA., 2014.

5
CLIMADA documentation, Release 3.1.2

6 Chapter 2. Introduction
 CHAPTER

THREE

INSTALLATION

Please execute the instructions of the following text boxes in a Terminal or Anaconda Prompt. Chose an installation
directory, e.g., the user’s home directory. In the following it will be referred to as $[installation directory].

3.1 Install CLIMADA from sources

3.1.1 Download the latest version

cd $[installation directory]

git clone https://github.com/CLIMADA-project/climada_python.git

cd climada_python
git checkout develop
cd ..

3.1.2 Set up the environment

It’s highly recommanded to install CLIMADA into a Conda environment. Without Conda, the installation of the
dependencies can be cumbersome. If it is not already installed, download the latest version of Anaconda or Miniconda
and execute it.
Open a command prompt (Windows) or shell (Mac, Linux) and run:

conda env create -n climada_env -f climada_python/requirements/env_climada.yml

conda activate climada_env

3.1.3 Install the climada package

Include the CLIMADA path into the Conda environment as follows:

pip install -e climada_python

With this setup, changes to CLIMADA’s source code will immediately take effect. It removes the need to reinstall
during development.

7
CLIMADA documentation, Release 3.1.2

3.2 Install CLIMADA from PyPi (alternative)

Published releases of CLIMADA (not CLIMADA-petals) can also be installed from the PyPi repository https://pypi.
org/project/climada/, since version 3.0.

3.2.1 Set up the environment

Download the environment specification file from the git repository and save it locally, then create the conda environ-
ment:

curl -o env_climada.yml https://raw.githubusercontent.com/CLIMADA-project/climada_python/

˓→main/requirements/env_climada.yml

conda env create -n climada_env -f env_climada.yml

conda activate climada_env

If this was successful, env_climada.yml can be safely deleted.

3.2.2 Install the climada package

pip install climada

3.3 Install CLIMADA-petals (optional)

3.3.1 Download the latest version

cd $[installation directory]

git clone https://github.com/CLIMADA-project/climada_petals.git

cd climada_petals
git checkout develop
cd ..

3.3.2 Update the environment

It is possible that CLIMADA-petals has slightly different dependencies than CLIMADA-core, hence the conda envi-
ronment should be updated.

conda env update -n climada_env -f climada_petals/requirements/env_climada.yml

conda activate climada_env

8 Chapter 3. Installation
 CLIMADA documentation, Release 3.1.2

3.3.3 Install the climada_petals package

Include the CLIMADA-petals path into the Conda environment as follows:

pip install -e climada_petals

In case of a separate environment for CLIMADA-petals, one needs to install the core package as well, either with the
package from PyPi (pip install climada) or from local sources (pip install -e climada_python)

3.4 Test the installation

Run the following command:

python -m unittest climada.engine.test.test_impact climada.engine.test.test_cost_benefit

If the installation has been successful, an OK will appear at the end (the execution shouldn’t last more than 2 min).

3.4.1 Run tutorials

In the Home section of Anaconda, with climada_env selected, install and launch jupyter notebook. A browser
window will show up. Navigate to your climada_python repository and open doc/tutorial/1_main_CLIMADA.
ipynb. This is the tutorial which will guide you through all CLIMADA’s functionalities. Execute each code cell to see
the results, you might also edit the code cells before executing. See tutorials for more information.

3.5 Working with Spyder

It is possible to use climada in combination with the Spyder-IDE. However, depending on OS, CLIMADA version,
Spyder version and installation tool, installing spyder into the climada_env environment may fail. In particular, Ma-
cOS and conda install spyder don’t work well together. Although there are cases where pip install spyder
bears satisfactory results, it is suggested to install spyder in a separate Conda environment and run it with the python
interpreter from the climada_env environment instead. To do so, follow these instructions:
• Start Anaconda, create a new python_env environment (just click create and enter the name, then press Create)
and install latest Spyder in there (currently 4.2.5). Start this version of Spyder. After Spyder has started, navigate
to Preferences > Python Interpreter > Use the following interpreter and paste the output of the following terminal
command into the text box:

conda activate climada_env

python -c "import sys; print(sys.executable)"
# this returns a path, like /Users/XXX/opt/anaconda3/envs/climada_env/bin/python

• Obtain the version of the package spyder-kernels (currently 1.10.2) that has automatically been installed along
with Spyder in the Anaconda environment and install the same version of spyder-kernels in the climada_env
environment:

conda activate climada_env

conda install spyder-kernels=1.10.2

• Start a new IPython console in Spyder and run tests_install.py.

3.4. Test the installation 9

CLIMADA documentation, Release 3.1.2

3.6 FAQs

• ModuleNotFoundError
– the CLIMADA packages are not found. Check whether the climada environment is activated. If not, activate
it (conda activate climada_env). Otherwise, the installation has failed. Try and follow the installation
instructions above.
– an external python library is not found. It might happen that the pip dependencies of env_climada.yml
(the ones specified after pip:) have not been installed in the environment climada_env. They can be
installed manually one by one as follows:

conda activate climada_env

pip install library_name

where library_name is the missing library.

Another reason may be a recent update of the operating system (macOS). In this case removing and reinstalling
Anaconda will be required.

• Conda permission error

(operation not permitted) in macOS Mojave: try the solutions suggested here
https://github.com/conda/conda/issues/8440
• No ‘impf_TC’ column in GeoDataFrame
This may happen when a demo file from CLIMADA was not updated after the change in the impact function
naming pattern from ‘if_’ to ‘impf_’ (climada v2.2.0).
To solve it, run python -c 'import climada; climada.setup_climada_data(reload=True) in a
terminal.
• How to change the log level
By default the logging level is set to 'INFO', which is quite verbose. This can be changed
– through configuration, by editing the config file climada.conf (see Guide_configuration.ipynb) and set-
ting the value of the global.log_level property.
– programmatically, globally, in a script or interactive python environment (Spyder, Jupyter, IPython) by
executing e.g.,

from climada.util.config import LOGGER

from logging import WARNING
LOGGER.setLevel(WARNING)

– programmatically, context based, using climada.util.log_level:

from climada.util import log_level

with log_level(level='WARNING'):
quietly_do_something()

10 Chapter 3. Installation
 CHAPTER

FOUR

USING CLIMADA ON THE EULER CLUSTER (ETH INTERNAL)

4.1 Content

1. Access to Euler
2. Installation and working directories
3. Pre-installed version of Climada
1. Load dependencies
2. Check installation
3. Adjust the Climada configuration
4. Run a job
4. Working with Git Branches
1. Load dependencies
2. Create installation environment
3. Check out sources
4. Pip install Climada
5. Check installation
6. Adjust the Climada configuration
7. Run a job
5. Fallback: Conda installation
1. Conda installation
2. Check out sources
3. Climada environemnt
4. Adjust the Climada configuration
5. Climada sripts
6. Run a job
6. Conda Deinstallation
1. Conda
2. Climada

11
CLIMADA documentation, Release 3.1.2

4.1.1 Access to Euler

See https://scicomp.ethz.ch/wiki/Getting_started_with_clusters for details on how to register at and get started with
Euler.
For all steps below, first enter the Cluster via SSH.
Installation- and working directories

Please, get familiar with the various Euler storage options: https://scicomp.ethz.ch/wiki/Storage_systems. As a general
rule: use /cluster/project for installation and /cluster/work for data processing.
For ETH WCR group members, the suggested installation and working directories are /cluster/project/climate/
$USER and /cluster/work/climate/$USER respectively. You may have to create the insallation directory:

mkdir -p /cluster/project/climate/$USER \
/cluster/work/climate/$USER

4.1.2 Pre-installed version of Climada

Climada is pre-installed and available in the default pip environment of Euler.

4.2 1. Load dependencies

env2lmod
module load gcc/6.3.0 python/3.8.5 gdal/3.1.2 geos/3.8.1 proj/7.2.1 libspatialindex/1.8.
˓→5 hdf5/1.10.1 netcdf/4.4.1.1 eccodes/2.21.0 zlib/1.2.9

You need to execute these two lines every time you login to Euler before Climada can be used. To safe yourself from
doing it manually, one can append these lines to the ~/.bashrc script, which is automatically executed upon logging in
to Euler.

4.3 2. Check installation

python -c 'import climada; print(climada.__file__)'

should output something like this:

/cluster/apps/nss/gcc-6.3.0/python/3.8.5/x86_64/lib64/python3.8/site-packages/climada/__
˓→init__.py

12 Chapter 4. Using Climada on the Euler Cluster (ETH internal)

 CLIMADA documentation, Release 3.1.2

4.4 3. Adjust the Climada configuration

Edit a configuration file according to your needs (see Guide_Configuration). Create a climada.conf file e.g., in /clus-
ter/home/$USER/.config with the following content:

{
"local_data": {
"system": "/cluster/work/climate/USERNAME/climada/data",
"demo": "/cluster/project/climate/USERNAME/climada_python/data/demo",
"save_dir": "/cluster/work/climate/USERNAME/climada/results"
}
}

(Replace USERNAME with your nethz-id.)

4.5 4. Run a job

Please see the Wiki: https://scicomp.ethz.ch/wiki/Using_the_batch_system for an overview on how to use bsub.

cd /cluster/work/climate/$USER # change to the working directory

bsub [bsub-options*] python climada_job_script.py # submit the job

4.5.1 Working with Git branches

If the Climada version of the default installation is not according to your needs, you can install Climada from a local
Git repository.

4.6 1. Load dependencies

See Load dependencies above.

4.7 2. Create installation environment

python -m venv --system-site-packages /cluster/project/climate/$USER/climada_venv

4.8 3. Checkout sources

cd /cluster/project/climate/$USER
git clone https://github.com/CLIMADA-project/climada_python.git
cd climada_python
git checkout develop # i.e., your branch of interest

4.4. 3. Adjust the Climada configuration 13

CLIMADA documentation, Release 3.1.2

4.9 4. Pip install Climada

source /cluster/project/climate/$USER/climada_venv/bin/activate
pip install -e /cluster/project/climate/$USER/climada_python

4.10 5. Check installation

cd /cluster/work/climate/$USER
python -c 'import climada; print(climada.__file__)'

should output exactly this (with explicit $USER):

/cluster/project/climate/$USER/climada_python/climada/__init__.py

4.11 6. Adjust the Climada configuration

See Adjust the Climada configuration above.

4.12 7. Run a job

See Run a job above.

4.12.1 Fallback: Conda installation

If Climada cannot be installed through pip because of changed dependency requirements, there is still the possibility
to install Climada through the Conda environment. > WARNING: This apporach is highly discouraged, as it imposes
a heavy and mostly unnecessary burdon on the file system of the cluster.

4.13 1. Conda Installation

Download or update to the latest version of Miniconda. Installation is done by execution of the following steps:

cd /cluster/project/climate/USERNAME
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh
miniconda3/bin/conda init
rm Miniconda3-latest-Linux-x86_64.sh

During the installation process of Miniconda, you are prompted to set the working directory according to your choice.
Set it to /cluster/project/climate/USERNAME/miniconda3. Once the installation has finished, log out of Euler
and in again. The command prompt should be preceded by (base), indicating that the installation was a success and
that you login in into conda’s base environment by default.

14 Chapter 4. Using Climada on the Euler Cluster (ETH internal)

 CLIMADA documentation, Release 3.1.2

4.14 2. Checkout sources

See Checkout sources above.

4.15 3. Climada Environment

Create the conda environment:

cd /cluster/project/climate/USERNAME/climada_python
conda env create -f requirements/env_climada.yml --name climada_env
conda env update -n climada_env -f requirements/env_developer.yml

conda activate climada_env

conda install conda-build
conda develop .

4. Adjust the Climada configuration

See Adjust the Climada configuration above.

4.16 5. Climada Scripts

Create a bash script for executing python scripts in the climada environment, climadajob.sh:

#!/bin/bash
PYTHON_SCRIPT=$1
shift
. ~/.bashrc
conda activate climada_env
python $PYTHON_SCRIPT $@
echo $PYTHON_SCRIPT completed

Make it executable:

chmod +x climadajob.sh

Create a python script that executes climada code, e.g., climada_smoke_test.py:

import sys
from climada import CONFIG, SYSTEM_DIR
from climada.util.test.test_finance import TestNetpresValue
TestNetpresValue().test_net_pres_val_pass()
print(SYSTEM_DIR)
print(CONFIG.local_data.save_dir.str())
print("the script ran with arguments", sys.argv)

4.14. 2. Checkout sources 15

CLIMADA documentation, Release 3.1.2

4.17 6. Run a Job

Please see the Wiki: https://scicomp.ethz.ch/wiki/Using_the_batch_system.

With the scripts from above you can submit the python script as a job like this:

bsub [options] /path/to/climadajob.sh /path/to/climada_smoke_test.py arg1 arg2

After the job has finished the lsf output file should look something like this:

Sender: LSF System <lsfadmin@eu-ms-010-32>

Subject: Job 161617875: <./climada_job.sh climada_smoke_test.py arg1 arg2> in cluster
˓→<euler> Done

Job <./climada_job.sh climada_smoke_test.py arg1 arg2> was submitted from host <eu-login-
˓→41> by user <USERNAME> in cluster <euler> at Thu Jan 28 14:10:15 2021

Job was executed on host(s) <eu-ms-010-32>, in queue <normal.4h>, as user <USERNAME> in␣
˓→cluster <euler> at Thu Jan 28 14:10:42 2021

</cluster/home/USERNAME> was used as the home directory.

</cluster/work/climate/USERNAME> was used as the working directory.
Started at Thu Jan 28 14:10:42 2021
Terminated at Thu Jan 28 14:10:53 2021
Results reported at Thu Jan 28 14:10:53 2021

Your job looked like:

------------------------------------------------------------
# LSBATCH: User input
./climada_job.sh climada_smoke_test.py arg1 arg2
------------------------------------------------------------

Successfully completed.

Resource usage summary:

CPU time : 2.99 sec.

Max Memory : 367 MB
Average Memory : 5.00 MB
Total Requested Memory : 1024.00 MB
Delta Memory : 657.00 MB
Max Swap : -
Max Processes : 5
Max Threads : 6
Run time : 22 sec.
Turnaround time : 38 sec.

The output (if any) follows:

/cluster/project/climate/USERNAME/miniconda3/envs/climada/lib/python3.7/site-packages/
˓→pandas_datareader/compat/__init__.py:7: FutureWarning: pandas.util.testing is␣

˓→deprecated. Use the functions in the public API at pandas.testing instead.

from pandas.util.testing import assert_frame_equal

/cluster/work/climate/USERNAME/climada/data
(continues on next page)

16 Chapter 4. Using Climada on the Euler Cluster (ETH internal)

 CLIMADA documentation, Release 3.1.2

(continued from previous page)

/cluster/work/climate/USERNAME/climada/results
the script ran with arguments ['/path/to/climada_smoke_test.py', 'arg1' 'arg2']
python_script.sh completed

Conda Deinstallation

4.18 1. Conda

Remove the miniconda3 directory from the installation directory:

rm -rf /cluster/project/climate/USERNAME/miniconda3/

Delete the conda related parts from /cluster/home/USERNAME/.bashrc, i.e., everything between

# >>> conda initialize >>>

and
# <<< conda initialize <<<

4.19 2. Climada

Remove the climada sources and config file:

rm -rf /cluster/project/climate/USERNAME/climada_python
rm -f /cluster/home/USERNAME/climada.conf /cluster/home/USERNAME/*/climada.conf

4.18. 1. Conda 17
CLIMADA documentation, Release 3.1.2

18 Chapter 4. Using Climada on the Euler Cluster (ETH internal)

 CHAPTER

FIVE

TUTORIALS

5.1 CLIMADA overview

5.1.1 Contents

• Introduction
– What is CLIMADA?
– This tutorial
– Resources beyond this tutorial
• CLIMADA features
– CLIMADA classes
• Tutorial: an example risk assessment
– Hazard
∗ Storm tracks
∗ Centroids
∗ Hazard footprint
– Entity
∗ Exposures
∗ Impact functions
∗ Adaptation measures
∗ Discount rates
– Engine
∗ Impact
∗ Adaptation options appraisal

19
CLIMADA documentation, Release 3.1.2

5.1.2 Introduction

What is CLIMADA?

CLIMADA is a fully probabilistic climate risk assessment tool. It provides a framework for users to combine exposure,
hazard and vulnerability or impact data to calculate risk. Users can create probabilistic impact data from event sets, look
at how climate change affects these impacts, and see how effectively adaptation measures can change them. CLIMADA
also allows for studies of individual events, historical event sets and forecasts.
The model is a highly customisable, meaning that users can work with out-of-the-box data provided for different haz-
ards, population and economic exposure, or can provide their own data for part or all of the analysis. The pre-packaged
data make CLIMADA particularly useful for users who focus on just one element of risk, since CLIMADA can ‘fill in
the gaps’ for hazard, exposure or vulnerability in the rest of the analysis.
The model core is designed to give as much flexibility as possible when describing the elements of risk, meaning that
CLIMADA isn’t limited to particular hazards, exposure types or impacts. We love to see the model applied to new
problems and contexts.
CLIMADA provides classes, methods and data for exposure, hazard and impact functions (also called vulnerability
functions), plus a financial model and a framework to analyse adaptation measures. Additional classes and data for
common uses, such as economic exposures or tropical storms. Tutorials for every class are available: see the CLIMADA
features section below.

This tutorial

This tutorial is for people new to CLIMADA who want to get a high level understanding of the model and work through
an example risk analysis. It will list the current features of the model, and go through a complete CLIMADA analysis
to give an idea of how the model works. Other tutorials go into more detail about different model components and
individual hazards.

Resources beyond this tutorial

• Installation guide - go here if you’ve not installed the model yet

• CLIMADA Read the Docs home page - for all other documentation
• List of CLIMADA’s features and associated tutorials
• CLIMADA GitHub develop branch documentation for the very latest versions of code and documentation
• CLIMADA paper GitHub repository - for publications using CLIMADA

5.1.3 CLIMADA features

A risk analysis with CLIMADA can include

1. the statistical risk to your exposure from a set of events,
2. how it changes under climate change, and
3. a cost-benefit analysis of adaptation measures.
CLIMADA is flexible: the “statistical risk” above could be describing the annual expected insured flood losses to a
property portfolio, the number of people displaced by an ensemble of typhoon forecasts, the annual disruption to a
railway network from landslides, or changes to crop yields.

20 Chapter 5. Tutorials
 CLIMADA documentation, Release 3.1.2

Users from risk-analysis backgrounds will be familiar with describing the impact of events by combining exposure,
hazard and an impact function (or vulnerability curve) that combines the two to describe a hazard’s effects. A CLI-
MADA analysis uses the same approach but wraps the exposures and their impact functions into a single Entity class,
along with discount rates and adaptation options (see the below tutorials for more on CLIMADA’s financial model).
CLIMADA’s Impact object is used to analyse events and event sets, whether this is the impact of a single wildfire, or
the global economic risk from tropical cyclones in 2100.

CLIMADA classes

This is a full directory of tutorials for CLIMADA’s classes to use as a reference. You don’t need to read all this to do
this tutorial, but it may be useful to refer back to.
• Hazard: a class that stores sets of geographic hazard footprints, (e.g. for wind speed, water depth and fraction,
drought index), and metadata including event frequency. Several predefined extensions to create particular haz-
ards from particular datasets and models are included with CLIMADA:
– Tropical cyclone wind: global hazard sets for tropical cyclone events, constructing statistical wind fields
from storm tracks. Subclasses include methods and data to calculate historical wind footprints, create
forecast enembles from ECMWF tracks, and create climatological event sets for different climate scenarios.
– Storm surge: (under development) global surge hazard for tropical storms. Runs the GeoClaw surge model
to create and plot hazard from tropical storm tracks
– European windstorms: includes methods to read and plot footprints from the Copernicus WISC dataset and
for DWD and ICON forecasts.
– River flooding: global water depth hazard for flood, including methods to work with ISIMIP simulations.
– Crop modelling: combines ISIMIP crop simulations and UN Food and Agrigultre Organization data. The
module uses crop production as exposure, with hydrometeorological ‘hazard’ increasing or decreasing
production.
– Wildfire (global): tutorial under development
– Drought (global): tutorial under development
• Entity: this is a container that groups CLIMADA’s socio-economic models. It’s is where the Exposures and
Impact Functions are stored, which can then be combined with a hazard for a risk analysis (using the Engine’s
Impact class). It is also where Discount Rates and Measure Sets are stored, which are used in adaptation cost-
benefit analyses (using the Engine’s CostBenefit class):
– Exposures: geolocated exposures. Each exposure is associated with a value (which can be a dollar value,
population, crop yield, etc), information to associate it with impact functions for the relevant hazard(s)
(in the Entity’s ImpactFuncSet), a geometry, and other optional properties such as deductables and cover.
Exposures can be loaded from a file, specified by the user, or created from regional economic models
accessible within CLIMADA, for example:
∗ LitPop: regional economic model using nightlight and population maps together with several economic
indicators
∗ BlackMarble: regional economic model from nightlight intensities and economic indicators (GDP,
income group). Largely succeeded by LitPop.
∗ OpenStreetMap: methods to create exposures from data available through the OpenStreetMap API
– ImpactFuncSet: functions to describe the impacts that hazards have on exposures, expressed in terms of
e.g. the % dollar value of a building lost as a function of water depth, or the mortality rate for over-70s
as a function of temperature. CLIMADA provides some common impact functions, or they can be user-
specified. The following is an incomplete list:

5.1. CLIMADA overview 21

CLIMADA documentation, Release 3.1.2

∗ ImpactFunc: a basic adjustable impact function, specified by the user

∗ IFTropCyclone: impact functions for tropical cyclone winds
∗ IFRiverFlood: impact functions for river floods
∗ IFStormEurope: impact functions for European windstorms
– DiscRates: discount rates per year
– MeasureSet: a collection of Measure objects that together describe any adaptation measures being mod-
elled. Adaptation measures are described by their cost, and how they modify exposure, hazard, and impact
functions (and have have a method to do these things). Measures also include risk transfer options.
• Engine: the CLIMADA Engine contains the Impact and CostBenefit classes, which are where the main model
calculations are done, combining Hazard and Entity objects.
– Impact: a class that stores CLIMADA’s modelled impacts and the methods to calculate them from Exposure,
Impact Function and Hazard classes. The calculations include average annual impact, expected annual
impact by exposure item, total impact by event, and (optionally) the impact of each event on each exposure
point. Includes statistical and plotting routines for common analysis products.
– CostBenefit: a class to appraise adaptation options. It uses an Entity’s MeasureSet to calculate new Impacts
based on their adjustments to hazard, exposure, and impact functions, and returns statistics and plotting
routines to express cost-benefit comparisons.
This list will be updated periodically along with new CLIMADA releases. To see the latest, development version of all
tutorials, see the tutorials page on the CLIMADA GitHub.

5.1.4 Tutorial: an example risk assessment

This example will work through a risk assessment for tropical storm wind in Puerto Rico, constructing hazard, exposure
and vulnerability and combining them to create an Impact object. Everything you need for this is included in the main
CLIMADA installation and additional data will be downloaded by the scripts as required.

5.1.5 Hazard

Hazards are characterized by their frequency of occurrence and the geographical distribution of their intensity. The
Hazard class collects events of the same hazard type (e.g. tropical cyclone, flood, drought, . . . ) with intensity values
over the same geographic centroids. They might be historical events or synthetic.
See the Hazard tutorial to learn about the Hazard class in more detail, and the CLIMADA features section of this
document to explore tutorials for different hazards, including tropical cyclones, as used here.
Tropical cyclones in CLIMADA and the TropCyclone class work like any hazard, storing each event’s wind speeds
at the geographic centroids specified for the class. Pre-calculated hazards can be loaded from files (see the full Hazard
tutorial, but they can also be modelled from a storm track using the TCTracks class, based on a storm’s parameters at
each time step. This is how we’ll construct the hazards for our example.
So before we create the hazard, we will create our storm tracks and define the geographic centroids for the locations
we want to calculate hazard at.

22 Chapter 5. Tutorials
 CLIMADA documentation, Release 3.1.2

Storm tracks

Storm tracks are created and stored in a separate class, TCTracks. We use its method from_ibtracs_netcdf to create
the tracks from the IBTRaCS storm tracks archive. The first time this runs on your machine it will need to download
the full dataset which might take a little time. See the full TropCyclone tutorial for more detail and troubleshooting.

[1]: import numpy as np

from climada.hazard import TCTracks

tracks = TCTracks.from_ibtracs_netcdf(provider='usa', basin='NA')

2021-10-19 16:41:37,771 - climada.hazard.tc_tracks - WARNING - 1125 storm events are␣
˓→discarded because no valid wind/pressure values have been found: 1851175N26270,␣

˓→1851181N19275, 1851187N22262, 1851192N12300, 1851214N14321, ...

2021-10-19 16:41:37,783 - climada.hazard.tc_tracks - WARNING - 127 storm events are␣

˓→discarded because only one valid timestep has been found: 1852232N21293, 1853242N12336,

˓→ 1855236N12304, 1856221N25277, 1856235N13302, ...

This will load all historical tracks in the North Atlantic into the tracks object (since we set basin='NA'). The
TCTracks.plot method will plot the downloaded tracks, though there are too many for the plot to be very useful:

[2]: tracks.plot()
[2]: <GeoAxesSubplot:>

It’s also worth adding additional time steps to the tracks (though this can be memory intensive!). Most tracks are
reported at 3-hourly intervals (plus a frame at landfall). Event footprints are calculated as the maximum wind from
any time step. For a fast-moving storm these combined three-hourly footprints give quite a rough event footprint, and
it’s worth adding extra frames to smooth the footprint artificially (try running this notebook with and without this
interpolation to see the effect):

[3]: tracks.equal_timestep(time_step_h=0.5)

Now, irresponsibly for a risk analysis, we’re only going to use these historical events: they’re enough to demonstrate
CLIMADA in action. A proper risk analysis would expand it to include enough events for a statistically robust clima-
tology. See the full TropCyclone tutorial for CLIMADA’s stochastic event generation.

5.1. CLIMADA overview 23

 CLIMADA documentation, Release 3.1.2

Centroids

A hazard’s centroids can be any set of locations where we want the hazard to be evaluated. This could be the same as
the locations of your exposure, though commonly it is on a regular lat-lon grid (with hazard being imputed to exposure
between grid points).
Here we’ll set the centroids as a 0.1 degree grid covering Puerto Rico. Centroids are defined by a Centroids class,
which has the from_pnt_bounds method for generating regular grids and a plot method to inspect the centroids.

[4]: from climada.hazard import Centroids

min_lat, max_lat, min_lon, max_lon = 17.5, 19.0, -68.0, -65.0

cent = Centroids.from_pnt_bounds((min_lon, min_lat, max_lon, max_lat), res=0.05)
cent.check()
cent.plot()
[4]: <GeoAxesSubplot:>

Almost every class in CLIMADA has a check() method, as used above. This verifies that the necessary data for an
objet is correctly provided and logs the optional variables that are not present. It is always worth running it after filling
an instance of an object.

Hazard footprint

Now we’re ready to create our hazard object. This will be a TropCyclone class, which inherits from the Hazard class,
and has the from_tracks constructor method to create a hazard from a TCTracks object at given centroids.

[5]: from climada.hazard import TropCyclone

haz = TropCyclone.from_tracks(tracks, centroids=cent)

haz.check()

24 Chapter 5. Tutorials
 CLIMADA documentation, Release 3.1.2

$CONDA_PREFIX/lib/python3.8/site-packages/pyproj/crs/crs.py:68: FutureWarning: '+init=

˓→<authority>:<code>' syntax is deprecated. '<authority>:<code>' is the preferred␣

˓→initialization method. When making the change, be mindful of axis order changes: https:

˓→//pyproj4.github.io/pyproj/stable/gotchas.html#axis-order-changes-in-proj-6

return _prepare_from_string(" ".join(pjargs))

$CONDA_PREFIX/lib/python3.8/site-packages/pyproj/crs/crs.py:68: FutureWarning: '+init=
˓→<authority>:<code>' syntax is deprecated. '<authority>:<code>' is the preferred␣

˓→initialization method. When making the change, be mindful of axis order changes: https:

˓→//pyproj4.github.io/pyproj/stable/gotchas.html#axis-order-changes-in-proj-6

return _prepare_from_string(" ".join(pjargs))

$CONDA_PREFIX/lib/python3.8/site-packages/pyproj/crs/crs.py:68: FutureWarning: '+init=
˓→<authority>:<code>' syntax is deprecated. '<authority>:<code>' is the preferred␣

˓→initialization method. When making the change, be mindful of axis order changes: https:

˓→//pyproj4.github.io/pyproj/stable/gotchas.html#axis-order-changes-in-proj-6

return _prepare_from_string(" ".join(pjargs))

$CONDA_PREFIX/lib/python3.8/site-packages/pyproj/crs/crs.py:68: FutureWarning: '+init=
˓→<authority>:<code>' syntax is deprecated. '<authority>:<code>' is the preferred␣

˓→initialization method. When making the change, be mindful of axis order changes: https:

˓→//pyproj4.github.io/pyproj/stable/gotchas.html#axis-order-changes-in-proj-6

return _prepare_from_string(" ".join(pjargs))

$CONDA_PREFIX/lib/python3.8/site-packages/pyproj/crs/crs.py:68: FutureWarning: '+init=
˓→<authority>:<code>' syntax is deprecated. '<authority>:<code>' is the preferred␣

˓→initialization method. When making the change, be mindful of axis order changes: https:

˓→//pyproj4.github.io/pyproj/stable/gotchas.html#axis-order-changes-in-proj-6

return _prepare_from_string(" ".join(pjargs))

In 2017 Hurricane Maria devastated Puerto Rico. In the IBTRaCs event set, it has ID 2017260N12310 (we use this
rather than the name, as IBTRaCS contains three North Atlantic storms called Maria). We can plot the track:

[6]: tracks.subset({"sid": "2017260N12310"}).plot() # This is how we subset a TCTracks object

[6]: <GeoAxesSubplot:>

5.1. CLIMADA overview 25

 CLIMADA documentation, Release 3.1.2

And plot the hazard on our centroids for Puerto Rico:

[7]: haz.plot_intensity(event='2017260N12310')
[7]: <GeoAxesSubplot:title={'center':'Event ID 948: 2017260N12310'}>

A Hazard object also lets us plot the hazard at different return periods. The IBTRaCS archive produces footprints from
1980 onwards (CLIMADA discarded earlier events) and so the historical period is short. Therefore these plots don’t
make sense as ‘real’ return periods, but we’re being irresponsible and demonstrating the functionality anyway.

26 Chapter 5. Tutorials
 CLIMADA documentation, Release 3.1.2

[8]: haz.plot_rp_intensity(return_periods=(5,10,20,40))
[8]: (array([[<GeoAxesSubplot:title={'center':'Return period: 5 years'}>,
<GeoAxesSubplot:title={'center':'Return period: 10 years'}>],
[<GeoAxesSubplot:title={'center':'Return period: 20 years'}>,
<GeoAxesSubplot:title={'center':'Return period: 40 years'}>]],
dtype=object),
array([[15.08108124, 15.11391293, 15.04906939, ..., 16.39247373,
16.53654363, 16.73792023],
[23.28332256, 23.25727297, 23.23369223, ..., 27.394