Impact Functions#

What is an impact function?#

An impact function relates the percentage of damage in the exposure to the hazard intensity, also commonly referred to as a “vulnerability curve” in the modelling community. Every hazard and exposure types are characterized by an impact function.

What is the difference between ImpactFunc and ImpactFuncSet?#

An ImpactFunc is a class for a single impact function. E.g. a function that relates the percentage of damage of a reinforced concrete building (exposure) to the wind speed of a tropical cyclone (hazard intensity).

An ImpactFuncSet class is a container that contains multiple ImpactFunc. For instance, there are 100 ImpactFunc represent 100 types of buildings exposed to tropical cyclone’s wind damage. These 100 ImpactFunc are all gathered in an ImpactFuncSet.

What does an ImpactFunc look like in CLIMADA?#

The ImpactFunc class requires users to define the following attributes.

Mandatory attributes             

Data Type                                    

Description                                        

haz_type

(str)

Hazard type acronym (e.g. ‘TC’)

id

(int or str)

Unique id of the impact function. Exposures of the same type will refer to the same impact function id

name

(str)

Name of the impact function

intensity

(np.array)

Intensity values

intensity_unit

(str)

Unit of the intensity

mdd

(np.array)

Mean damage (impact) degree for each intensity (numbers in [0,1])

paa

(np.array)

Percentage of affected assets (exposures) for each intensity (numbers in [0,1])

Users may use ImpactFunc.check() to check that the attributes have been set correctly. The mean damage ratio mdr (mdr=mdd*paa) is calculated by the method ImpactFunc.calc_mdr().

What does an ImpactFuncSet look like in CLIMADA?#

The ImpactFuncSet class contains all the ImpactFunc classes. Users are not required to define any attributes in ImpactFuncSet.

To add an ImpactFunc into an ImpactFuncSet, simply use the method ImpactFuncSet.append(ImpactFunc). If the users only has one impact function, they should generate an ImpactFuncSet that contains one impact function. ImpactFuncSet is to be used in the impact calculation.

Attributes             

Data Type                                    

Description                                        

_data

(dict)

Contains ImpactFunc classes. Not suppossed to be directly accessed. Use the class methods instead.

Structure of the tutorial#

Part 1: Defining ImpactFunc from your own data

Part 2: Loading ImpactFunc from CLIMADA in-built impact functions

Part 3: Add ImpactFunc into the container ImpactFuncSet

Part 4: Read and write ImpactFuncSet into Excel sheets

Part 5: Loading ImpactFuncSet from CLIMADA in-built impact functions

Part 1: Defining ImpactFunc from your own data#

The essential attributes are listed in the table above. The following example shows you how to define an ImpactFunc from scratch, and using the method ImpactFunc.calc_mdr() to calculate the mean damage ratio.

Generate a dummy impact function from scratch.#

Here we generate an impact function with random dummy data for illustrative reasons. Assuming this impact function is a function that relates building damage to tropical cyclone (TC) wind, with an arbitrary id 3.

import numpy as np
from climada.entity import ImpactFunc

# We initialise a dummy ImpactFunc for tropical cyclone wind damage to building.
# Giving the ImpactFunc an arbitrary id 3.
haz_type = "TC"
id = 3
name = "TC building damage"
# provide unit of the hazard intensity
intensity_unit = "m/s"
# provide values for the hazard intensity, mdd, and paa
intensity = np.linspace(0, 100, num=15)
mdd = np.concatenate((np.array([0]), np.sort(np.random.rand(14))), axis=0)
paa = np.concatenate((np.array([0]), np.sort(np.random.rand(14))), axis=0)
imp_fun = ImpactFunc(
    id=id,
    name=name,
    intensity_unit=intensity_unit,
    haz_type=haz_type,
    intensity=intensity,
    mdd=mdd,
    paa=paa,
)

# check if the all the attributes are set correctly
imp_fun.check()

# Calculate the mdr at hazard intensity 18.7 m/s
print('Mean damage ratio at intensity 18.7 m/s: ', imp_fun.calc_mdr(18.7))

Mean damage ratio at intensity 18.7 m/s:  0.01878041941423081

Visualise the Impact function#

The method plot() uses the matplotlib’s axes plot function to visualise the impact function. It returns a figure and axes, which can be modified by users.

# plot impact function
imp_fun.plot();
../_images/90109571d6f1aee80dd5249d47c99184e8c0a7a70cac59094028c0dc4d13cc93.png

Part 2: Loading impact functions from CLIMADA in-built impact functions#

In CLIMADA there is several defined impact functions that users can directly load and use them. However, users should be aware of the applications of the impact functions to types of assets, reading the background references of the impact functions are strongly recommended.
Currently available perils include tropical cyclones, river floods, European windstorm, crop yield, and drought.Continuous updates of perils are available.
Here we use the impact function of tropical cyclones as an example.

Loading CLIMADA in-built impact function for tropical cyclones#

ImpfTropCyclone is a derivated class of ImpactFunc. This in-built impact function estimates the insured property damages by tropical cyclone wind in USA, following the reference paper Emanuel (2011).

To generate this impact function, method set_emanual_usa() is used.

from climada.entity import ImpfTropCyclone

# Here we generate the impact function for TC damage using the formula of Emanuel 2011
impFunc_emanuel_usa = ImpfTropCyclone.from_emanuel_usa()
# plot the impact function
impFunc_emanuel_usa.plot();
../_images/dd389960244ddd934ca8e11a7770fc3c0c621da7f84641ff6cb2e9f8b7cd5171.png

Part 3: Add ImpactFunc into the container ImpactFuncSet#

ImpactFuncSet is a container of multiple ImpactFunc, it is part of the arguments in ImpactCalc.impact() (see the impact tutorial).

Here we generate 2 arbitrary impact functions and add them into an ImpactFuncSet class. To add them into the container, simply use the method ImpactFuncSet.append(ImpactFunc).

import numpy as np
import matplotlib.pyplot as plt
from climada.entity import ImpactFunc, ImpactFuncSet

# generate the 1st arbitrary impact function
haz_type = "TC"
id = 1
name = "TC Default Damage Function"
intensity_unit = "m/s"
intensity = np.linspace(0, 100, num=10)
mdd = np.concatenate((np.array([0]), np.sort(np.random.rand(9))), axis=0)
paa = np.concatenate((np.array([0]), np.sort(np.random.rand(9))), axis=0)
imp_fun_1 = ImpactFunc(
    id=id,
    name=name,
    intensity_unit=intensity_unit,
    haz_type=haz_type,
    intensity=intensity,
    mdd=mdd,
    paa=paa,
)
imp_fun_1.check()

# generate the 2nd arbitrary impact function
haz_type = "TC"
id = 3
name = "TC Building Damage"
intensity_unit = "m/s"
intensity = np.linspace(0, 100, num=15)
mdd = np.concatenate((np.array([0]), np.sort(np.random.rand(14))), axis=0)
paa = np.concatenate((np.array([0]), np.sort(np.random.rand(14))), axis=0)
imp_fun_3 = ImpactFunc(
    id=id,
    name=name,
    intensity_unit=intensity_unit,
    haz_type=haz_type,
    intensity=intensity,
    mdd=mdd,
    paa=paa,
)
imp_fun_3.check()

# add the 2 impact functions into ImpactFuncSet
imp_fun_set = ImpactFuncSet([imp_fun_1, imp_fun_3])

Plotting all the impact functions in an ImpactFuncSet#

The method plot() in ImpactFuncSet also uses the the matplotlib’s axes plot function to visualise the impact functions, returning a figure with all the subplots of impact functions. Users may modify these plots.

# plotting all the impact functions in impf_set
axes = imp_fun_set.plot()
../_images/efd4033cb1fb111e368b0b101fc21f77825471bc83edadfc36aaeed5d7639427.png

Retrieving an impact function from the ImpactFuncSet#

User may want to retrive a particular impact function from ImpactFuncSet. Using the method get_func(haz_type, id), it returns an ImpactFunc class of the desired impact function. Below is an example of extracting the TC impact function with id 1, and using plot() to visualise the function.

# extract the TC impact function with id 1
impf_tc_1 = imp_fun_set.get_func('TC', 1)
# plot the impact function
impf_tc_1.plot();
../_images/7285995c38bb7efc8be1259428644bcb3c09d9deb1a53473aeb19c859f3c008c.png

Removing an impact function from the ImpactFuncSet#

If there is an unwanted impact function from the ImpactFuncSet, we may remove it using the method remove_func(haz_type, id) to remove it from the set.

For example, in the previous generated impact function set imp_fun_set contains an unwanted TC impact function with id 3, we might thus would like to remove that from the set.

# first plotting all the impact functions in the impact function set to see what is in there:
imp_fun_set.plot();
../_images/efd4033cb1fb111e368b0b101fc21f77825471bc83edadfc36aaeed5d7639427.png 
# removing the TC impact function with id 3
imp_fun_set.remove_func('TC', 3)
# plot all the remaining impact functions in imp_fun_set
imp_fun_set.plot();
../_images/7285995c38bb7efc8be1259428644bcb3c09d9deb1a53473aeb19c859f3c008c.png

Part 4: Read and write ImpactFuncSet into Excel sheets#

Users may load impact functions to an ImpactFuncSet class from an excel sheet, or to write the ImpactFuncSet into an excel sheet. This section will give an example of how to do it.

Reading impact functions from an Excel file#

Impact functions defined in an excel file following the template provided in sheet impact_functions of climada_python/climada/data/system/entity_template.xlsx can be ingested directly using the method from_excel().

from climada.entity import ImpactFuncSet
from climada.util import ENT_TEMPLATE_XLS
import matplotlib.pyplot as plt

# provide absolute path of the input excel file
file_name = ENT_TEMPLATE_XLS
# fill ImpactFuncSet from Excel file
imp_set_xlsx = ImpactFuncSet.from_excel(file_name)

# plot all the impact functions from the ImpactFuncSet
imp_set_xlsx.plot()
# adjust the plots
plt.subplots_adjust(right=1., top=4., hspace=0.4, wspace=0.4)
../_images/df181893f37ebdf86e69e5b9c59d59521641d3337aad299804f54f707d0955ef.png

Write impact functions#

Users may write the impact functions in Excel format using write_excel() method.

# write imp_set_xlsx into an excel file
imp_set_xlsx.write_excel('tutorial_impf_set.xlsx')

Alternative saving format#

Alternatively, users may also save the impact functions into pickle format, using CLIMADA in-built function save().

from climada.util.save import save

# this generates a results folder in the current path and stores the output there
save('tutorial_impf_set.p', imp_set_xlsx)

2022-03-28 20:08:56,846 - climada.util.save - INFO - Written file /mnt/c/users/yyljy/documents/climada_main/doc/tutorial/results/tutorial_impf_set.p

Part 5: Loading ImpactFuncSet from CLIMADA in-built impact functions#

Similar to Part 3, some of the impact functions are available as ImpactFuncSet classes. Users may load them from the CLIMADA modules.

Here we use the example of the calibrated impact functions of TC wind damages per region to property damages, following the reference Eberenz et al. (2021). Method from_calibrated_regional_ImpfSet() returns a set of default calibrated impact functions for TC for different regions.

from climada.entity.impact_funcs.trop_cyclone import ImpfSetTropCyclone
import matplotlib.pyplot as plt

# generate the default calibrated TC impact functions for different regions
imp_fun_set_TC = ImpfSetTropCyclone.from_calibrated_regional_ImpfSet()

# plot all the impact functions
imp_fun_set_TC.plot()
# adjust the plots
plt.subplots_adjust(right=1., top=4., hspace=0.4, wspace=0.4)

/tmp/ipykernel_1009/2983082256.py:10: UserWarning: Tight layout not applied. tight_layout cannot make axes height small enough to accommodate all axes decorations.
  plt.tight_layout()
../_images/fc6a0d488fff8d3dc9545d0e93ca1a55cfe63c651c6bc1b7c709d9b66fb9a18b.png